Skip to content
Kward Search API index

Class: Kward::PluginRegistry::DSL

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

Overview

Public DSL object yielded by Kward.plugin blocks.

Plugin files normally interact with this object only through a block:

Examples:

Register a plugin command

Kward.plugin do |plugin|
  plugin.command "hello", description: "Say hello" do |args, ctx|
    name = args.strip.empty? ? "there" : args.strip
    ctx.say "Hello, #{name}."
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(registry, path, host: nil) ⇒ DSL

Creates an object for trusted plugin loading and dispatch.



260
261
262
263
264
 
# File 'lib/kward/plugins/registry.rb', line 260

def initialize(registry, path, host: nil)
  @registry = registry
  @path = path
  @host = host
end

Instance Attribute Details

#host ⇒ PluginHost? (readonly)

Shared metadata, configuration, storage, secrets, and logging services. Legacy plugins without declared identity return nil.

Returns:



270
271
272
 
# File 'lib/kward/plugins/registry.rb', line 270

def host
  @host
end

Instance Method Details

#action(name, description:, schema: { type: "object", properties: {} }) {|args, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a namespaced typed action for trusted RPC clients. Identified plugin metadata is required so the action has a stable ID.

Parameters:

  • name (String, #to_s) —

    action name within the plugin namespace

  • description (String) —

    short client-facing description

  • schema (Hash) (defaults to: { type: "object", properties: {} }) —

    strict object JSON Schema for typed arguments

Yield Parameters:

  • args (Hash) —

    validated action arguments

  • ctx (Context) —

    plugin execution context

Raises:

  • (ArgumentError) 


309
310
311
312
313
 
# File 'lib/kward/plugins/registry.rb', line 309

def action(name, description:, schema: { type: "object", properties: {} }, &block)
  raise ArgumentError, "Plugin actions require stable plugin identity" unless @host

  @registry.register_action(name, plugin_id: @host.id, description: description, schema: schema, path: @path, &block)
end

#command(name, description: "", argument_hint: "", schema: nil, positionals: []) {|args, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a slash command.

The command is available in the interactive CLI and through the RPC command bridge. Command names do not include the leading /.

Parameters:

  • name (String, #to_s) —

    command name without the leading slash

  • description (String) (defaults to: "") —

    short text shown in command listings

  • argument_hint (String) (defaults to: "") —

    optional usage hint for arguments

  • schema (Hash, nil) (defaults to: nil) —

    strict object JSON Schema for typed arguments

  • positionals (Array<String, Symbol>) (defaults to: []) —

    schema properties filled by positional text

Yield Parameters:

  • args (String, Hash) —

    raw text for legacy commands or parsed typed arguments

  • ctx (Context) —

    plugin execution context



286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/kward/plugins/registry.rb', line 286

def command(name, description: "", argument_hint: "", schema: nil, positionals: [], &block)
  @registry.register_command(
    name,
    description: description,
    argument_hint: argument_hint,
    schema: schema,
    positionals: positionals,
    plugin_id: @host&.id,
    path: @path,
    &block
  )
end

#footer {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers a legacy footer contribution. Multiple plugin footers are composed rather than replacing one another. Identified plugins should prefer #status so clients receive a descriptive stable segment ID.

Yield Parameters:

  • ctx (Context) —

    plugin execution context



369
370
371
 
# File 'lib/kward/plugins/registry.rb', line 369

def footer(&block)
  @registry.register_footer(plugin_id: @host&.id, path: @path, &block)
end

#hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil) {|event, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a lifecycle hook handler.

Hooks are deterministic runtime callbacks around Kward lifecycle events. They can return a Hooks::Decision, a decision hash, a decision string, or nil to allow the operation.

Parameters:

  • event (String, #to_s) —

    lifecycle event name

  • id (String, nil) (defaults to: nil) —

    stable hook identifier for logs and diagnostics

  • description (String) (defaults to: "") —

    short human-readable purpose

  • order (Integer) (defaults to: 100) —

    lower values run first

  • match (Hash, nil) (defaults to: nil) —

    optional event selector

Yield Parameters:

  • event (Hooks::Event) —

    immutable lifecycle event

  • ctx (Context) —

    plugin execution context and decision helpers



427
428
429
 
# File 'lib/kward/plugins/registry.rb', line 427

def hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, &block)
  @registry.register_hook(event, id: id, description: description, order: order, match: match, failure_policy: failure_policy, path: @path, &block)
end

#interactive_command(name, rows:, fps: 30, description: "", argument_hint: "") {|ui, ctx| ... } ⇒ void

This method returns an undefined value.

Registers an interactive command that takes over the composer region with a Kward-driven render and input loop. The handler receives an interactive controller object with a canvas API for drawing colored cells and reading keys. Useful for games, dashboards, and viewers.

Parameters:

  • name (String, #to_s) —

    command name without the leading slash

  • rows (Integer) —

    fixed canvas height in terminal rows

  • fps (Numeric) (defaults to: 30) —

    frame rate for tick callbacks (1-120, default 30)

  • description (String) (defaults to: "") —

    short text shown in command listings

  • argument_hint (String) (defaults to: "") —

    optional usage hint for arguments

Yield Parameters:

  • ui (Object) —

    interactive controller with canvas and key API

  • ctx (Context) —

    plugin execution context



457
458
459
 
# File 'lib/kward/plugins/registry.rb', line 457

def interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", &block)
  @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
end

#on_reload {|host| ... } ⇒ void

This method returns an undefined value.

Registers a callback invoked on the old plugin instance immediately before its resources are cleaned up during reload.

Yield Parameters:

  • host (PluginHost) —

    identified plugin host and resource owner



348
349
350
 
# File 'lib/kward/plugins/registry.rb', line 348

def on_reload(&block)
  register_lifecycle(:reload, &block)
end

#on_shutdown {|host| ... } ⇒ void

This method returns an undefined value.

Registers a callback invoked immediately before plugin resources are cleaned up during process shutdown.

Yield Parameters:

  • host (PluginHost) —

    identified plugin host and resource owner



358
359
360
 
# File 'lib/kward/plugins/registry.rb', line 358

def on_shutdown(&block)
  register_lifecycle(:shutdown, &block)
end

#on_start {|host| ... } ⇒ void

This method returns an undefined value.

Registers a callback invoked after plugin loading when the runtime is ready to start owned background work.

Yield Parameters:

  • host (PluginHost) —

    identified plugin host and resource owner



338
339
340
 
# File 'lib/kward/plugins/registry.rb', line 338

def on_start(&block)
  register_lifecycle(:start, &block)
end

#on_transcript_event {|event, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a live transcript event observer.

Observer errors are caught and reported as warnings so a plugin cannot crash the active turn by raising from an event handler.

Yield Parameters:



408
409
410
 
# File 'lib/kward/plugins/registry.rb', line 408

def on_transcript_event(&block)
  @registry.register_transcript_event(path: @path, &block)
end

#prompt_context {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers prompt context text injected into future system prompts.

Keep this text short and never include secrets. The returned string can be sent to the active model as part of Kward's system instructions.

Yield Parameters:

  • ctx (Context) —

    plugin execution context



439
440
441
 
# File 'lib/kward/plugins/registry.rb', line 439

def prompt_context(&block)
  @registry.register_prompt_context(path: @path, &block)
end

#startup_option(name, description:, &block) ⇒ Object

Registers a no-argument top-level CLI mode for an identified plugin. The handler runs only when the user selects this option.

Raises:

  • (ArgumentError) 


513
514
515
516
517
 
# File 'lib/kward/plugins/registry.rb', line 513

def startup_option(name, description:, &block)
  raise ArgumentError, "Plugin startup options require stable plugin identity" unless @host

  @registry.register_startup_option(name, description: description, plugin_id: @host.id, path: @path, &block)
end

#status(name, order: 100, priority: :normal) {|ctx| ... } ⇒ void

This method returns an undefined value.

Registers a composable status contribution.

The renderer may return a string, nil to hide the segment, or a hash with text and optional tooltip. Lower order values render first. On narrow terminals low-priority segments are removed before normal- and high-priority segments.

Parameters:

  • name (String, #to_s) —

    stable name within the plugin namespace

  • order (Integer) (defaults to: 100) —

    display order; lower values render first

  • priority (Symbol, String) (defaults to: :normal) —

    low, normal, or high

Yield Parameters:

  • ctx (Context) —

    plugin execution context

Raises:

  • (ArgumentError) 


386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/kward/plugins/registry.rb', line 386

def status(name, order: 100, priority: :normal, &block)
  raise ArgumentError, "Plugin status contributions require stable plugin identity" unless @host

  @registry.register_status(
    name,
    plugin_id: @host.id,
    order: order,
    priority: priority,
    path: @path,
    &block
  )
end

#tab_type(name, id:, title: nil, singleton: nil, rpc: false, transport: false, local: true, transcript_events: false, api: nil, capabilities: nil) {|host, descriptor| ... } ⇒ void

This method returns an undefined value.

Registers a plugin-owned chat type. id is a durable identifier used in persisted tab layouts and transport chat handles and must not change. The factory receives a PluginTabHost and a descriptor hash.

Parameters:

  • name (String) —

    command name used by /tab open <name>

  • id (String) —

    stable persisted tab type identifier

  • title (String) (defaults to: nil) —

    default tab label

  • singleton (Symbol) (defaults to: nil) —

    :global for one shared plugin runtime

  • rpc (Boolean) (defaults to: false) —

    expose this chat through trusted local RPC

  • transport (Boolean) (defaults to: false) —

    allow external transport adapters to target this chat

  • local (Boolean) (defaults to: true) —

    expose this chat as an interactive local tab

  • transcript_events (Boolean) (defaults to: false) —

    allow global transcript observers to receive this tab's events

  • api (Integer, nil) (defaults to: nil) —

    versioned plugin-chat contract API

  • capabilities (Hash, nil) (defaults to: nil) —

    explicit attachments, steering, and transcript-paging support

Yield Parameters:

  • host (PluginTabHost) —

    supported host dependencies

  • descriptor (Hash) —

    persisted tab descriptor



479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
 
# File 'lib/kward/plugins/registry.rb', line 479

def tab_type(name, id:, title: nil, singleton: nil, rpc: false, transport: false, local: true, transcript_events: false, api: nil, capabilities: nil, &block)
  @registry.register_tab_type(
    name,
    id: id,
    title: title,
    singleton: singleton,
    rpc: rpc,
    transport: transport,
    local: local,
    transcript_events: transcript_events,
    api: api,
    capabilities: capabilities,
    plugin_id: @host&.id,
    path: @path,
    &block
  )
end

#tool(name, description:, schema: { type: "object", properties: {} }) {|args, ctx| ... } ⇒ void

This method returns an undefined value.

Registers a model-callable tool for normal Kward agent turns.

Tool arguments are described with a strict object JSON Schema. The handler must return model-facing text and receives the normal plugin context with the active cancellation token.

Parameters:

  • name (String, #to_s) —

    function name exposed to the model

  • description (String) —

    model-facing description of the operation

  • schema (Hash) (defaults to: { type: "object", properties: {} }) —

    object JSON Schema for parsed tool arguments

Yield Parameters:

  • args (Hash) —

    parsed model-provided arguments

  • ctx (Context) —

    plugin execution context



328
329
330
 
# File 'lib/kward/plugins/registry.rb', line 328

def tool(name, description:, schema: { type: "object", properties: {} }, &block)
  @registry.register_tool(name, description: description, schema: schema, path: @path, &block)
end

#transport(name, id:, capabilities: nil, execution_profile: nil) {|host, config| ... } ⇒ void

This method returns an undefined value.

Registers an external messaging or event transport. The factory is called when the transport runtime starts.

Parameters:

  • name (String) —

    human-readable transport name

  • id (String) —

    stable transport identifier

  • capabilities (Hash, Transport::Capabilities) (defaults to: nil) —

    supported features

Yield Parameters:

  • host (Object) —

    transport host

  • config (Object) —

    transport configuration



507
508
509
 
# File 'lib/kward/plugins/registry.rb', line 507

def transport(name, id:, capabilities: nil, execution_profile: nil, &block)
  @registry.register_transport(name, id: id, capabilities: capabilities, execution_profile: execution_profile, path: @path, &block)
end