Skip to content
Kward Search API index

Class: Kward::PluginRegistry::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/kward/plugins/registry.rb

Overview

Runtime context passed to plugin commands, tools, footers, prompt context renderers, hooks, and transcript event handlers.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(conversation:, args: "", session: nil, workspace_root: Dir.pwd, say_callback: nil, cancellation: nil, ui: nil, tool_ui: nil, turn_command: nil) ⇒ Context

Creates an object for trusted plugin loading and dispatch.



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/kward/plugins/registry.rb', line 106

def initialize(conversation:, args: "", session: nil, workspace_root: Dir.pwd, say_callback: nil, cancellation: nil, ui: nil, tool_ui: nil, turn_command: nil)
  @conversation = conversation
  @args = args.is_a?(Hash) ? DeepCopy.freeze(DeepCopy.dup(args)) : args.to_s
  @session = session
  @workspace_root = workspace_root
  @say_callback = say_callback
  @cancellation = cancellation
  @ui = (ui || PluginUI.new(say_callback: say_callback)).with_cancellation(cancellation)
  @tool_ui = tool_ui
  @turn_command = turn_command
end

Instance Attribute Details

#args ⇒ Object (readonly)

Returns the value of attribute args.



103
104
105
 
# File 'lib/kward/plugins/registry.rb', line 103

def args
  @args
end

#cancellation ⇒ Object (readonly)

Returns the value of attribute cancellation.



103
104
105
 
# File 'lib/kward/plugins/registry.rb', line 103

def cancellation
  @cancellation
end

#requested_turn ⇒ Object (readonly)

Returns the value of attribute requested_turn.



103
104
105
 
# File 'lib/kward/plugins/registry.rb', line 103

def requested_turn
  @requested_turn
end

#ui ⇒ Object (readonly)

Returns the value of attribute ui.



103
104
105
 
# File 'lib/kward/plugins/registry.rb', line 103

def ui
  @ui
end

#workspace_root ⇒ Object (readonly)

Returns the value of attribute workspace_root.



103
104
105
 
# File 'lib/kward/plugins/registry.rb', line 103

def workspace_root
  @workspace_root
end

Instance Method Details

#allow(message = nil, metadata: nil) ⇒ Hooks::Decision

Allows the current lifecycle event to continue.

Returns:



203
204
205
 
# File 'lib/kward/plugins/registry.rb', line 203

def allow(message = nil, metadata: nil)
  Hooks::Decision.allow(message, metadata: metadata)
end

#ask(message = nil, metadata: nil) ⇒ Hooks::Decision

Requests frontend approval for the current lifecycle event.

Returns:



215
216
217
 
# File 'lib/kward/plugins/registry.rb', line 215

def ask(message = nil, metadata: nil)
  Hooks::Decision.ask(message, metadata: metadata)
end

#cancelled? ⇒ Boolean

Returns whether the active plugin operation has been cancelled. Contexts without a cancellable operation return false.

Returns:

  • (Boolean) 


184
185
186
 
# File 'lib/kward/plugins/registry.rb', line 184

def cancelled?
  @cancellation&.cancelled? == true
end

#defer(message = nil, payload: nil, metadata: nil) ⇒ Hooks::Decision

Defers the event when the current workflow supports it.

Returns:



240
241
242
 
# File 'lib/kward/plugins/registry.rb', line 240

def defer(message = nil, payload: nil, metadata: nil)
  Hooks::Decision.defer(message, payload: payload, metadata: metadata)
end

#deny(message = nil, metadata: nil) ⇒ Hooks::Decision

Denies the current lifecycle event.

Returns:



209
210
211
 
# File 'lib/kward/plugins/registry.rb', line 209

def deny(message = nil, metadata: nil)
  Hooks::Decision.deny(message, metadata: metadata)
end

#for_tool(conversation:, cancellation: nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds a fresh context for one model-callable plugin tool invocation.



190
191
192
193
194
195
196
197
198
199
 
# File 'lib/kward/plugins/registry.rb', line 190

def for_tool(conversation:, cancellation: nil)
  self.class.new(
    conversation: conversation,
    session: @session,
    workspace_root: @workspace_root,
    say_callback: @say_callback,
    cancellation: cancellation,
    ui: @tool_ui || @ui
  )
end

#modify(payload, message: nil, metadata: nil) ⇒ Hooks::Decision

Continues with an event-specific payload replacement.

Parameters:

  • payload (Hash) —

    replacement fields supported by the event

Returns:



222
223
224
 
# File 'lib/kward/plugins/registry.rb', line 222

def modify(payload, message: nil, metadata: nil)
  Hooks::Decision.modify(payload, message: message, metadata: metadata)
end

#refresh_system_message! ⇒ nil

Requests that the conversation rebuild its system message after plugin state changes that affect prompt context.

Returns:

  • (nil) 


168
169
170
171
 
# File 'lib/kward/plugins/registry.rb', line 168

def refresh_system_message!
  @conversation.refresh_system_message! if @conversation.respond_to?(:refresh_system_message!)
  nil
end

#request_turn(system:) ⇒ nil

Stages one turn for dispatch after the command successfully returns. Available only to asynchronous, session-backed plugin commands.

Returns:

  • (nil)

Raises:

  • (ArgumentError) 


126
127
128
129
130
131
132
133
 
# File 'lib/kward/plugins/registry.rb', line 126

def request_turn(system:)
  raise ArgumentError, "Model turn requests are unavailable here; use a session command through the TUI or RPC turns/start" unless turn_requests_supported?
  @cancellation&.raise_if_cancelled!
  raise ArgumentError, "Only one model turn may be requested per command" if @requested_turn

  @requested_turn = PluginTurnRequest.new(system: system, command: @turn_command.name, plugin_id: @turn_command.plugin_id)
  nil
end

#result(message: nil, data: nil) ⇒ PluginResult

Builds a structured result for a typed command or plugin action.

Parameters:

  • message (#to_s, nil) (defaults to: nil) —

    optional user-facing result text

  • data (Object, nil) (defaults to: nil) —

    optional JSON-compatible machine-readable data

Returns:



178
179
180
 
# File 'lib/kward/plugins/registry.rb', line 178

def result(message: nil, data: nil)
  PluginResult.new(message: message, data: data)
end

#retry(message = nil, payload: nil, metadata: nil) ⇒ Hooks::Decision

Requests a retry when the current event supports it.

Returns:



234
235
236
 
# File 'lib/kward/plugins/registry.rb', line 234

def retry(message = nil, payload: nil, metadata: nil)
  Hooks::Decision.retry(message, payload: payload, metadata: metadata)
end

#say(message) ⇒ nil

Emits command output to the active frontend when available.

Parameters:

  • message (#to_s) —

    message to display

Returns:

  • (nil) 


144
145
146
147
 
# File 'lib/kward/plugins/registry.rb', line 144

def say(message)
  @say_callback&.call(message.to_s)
  nil
end

#session_id ⇒ String?

Returns active session identifier.

Returns:

  • (String, nil) —

    active session identifier



150
151
152
 
# File 'lib/kward/plugins/registry.rb', line 150

def session_id
  @session&.id
end

#session_name ⇒ String?

Returns human-readable active session name.

Returns:

  • (String, nil) —

    human-readable active session name



155
156
157
 
# File 'lib/kward/plugins/registry.rb', line 155

def session_name
  @session&.name
end

#session_path ⇒ String?

Returns saved active session path.

Returns:

  • (String, nil) —

    saved active session path



160
161
162
 
# File 'lib/kward/plugins/registry.rb', line 160

def session_path
  @session&.path
end

#transcript ⇒ Transcript

Returns read-only transcript wrapper.

Returns:



136
137
138
 
# File 'lib/kward/plugins/registry.rb', line 136

def transcript
  Transcript.new(@conversation)
end

#turn_requests_supported? ⇒ Boolean

Whether this command runs on a host that can execute a session turn.

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/kward/plugins/registry.rb', line 119

def turn_requests_supported?
  !@turn_command.nil?
end

#warn(message = nil, metadata: nil) ⇒ Hooks::Decision

Allows the event while recording a warning.

Returns:



228
229
230
 
# File 'lib/kward/plugins/registry.rb', line 228

def warn(message = nil, metadata: nil)
  Hooks::Decision.warn(message, metadata: metadata)
end