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.



257
258
259
260
261
 
# File 'lib/kward/plugins/registry.rb', line 257

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:



267
268
269
 
# File 'lib/kward/plugins/registry.rb', line 267

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) 


306
307
308
309
310
 
# File 'lib/kward/plugins/registry.rb', line 306

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



283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/kward/plugins/registry.rb', line 283

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



366
367
368
 
# File 'lib/kward/plugins/registry.rb', line 366

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



424
425
426
 
# File 'lib/kward/plugins/registry.rb', line 424

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



454
455
456
 
# File 'lib/kward/plugins/registry.rb', line 454

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



345
346
347
 
# File 'lib/kward/plugins/registry.rb', line 345

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



355
356
357
 
# File 'lib/kward/plugins/registry.rb', line 355

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



335
336
337
 
# File 'lib/kward/plugins/registry.rb', line 335

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:



405
406
407
 
# File 'lib/kward/plugins/registry.rb', line 405

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



436
437
438
 
# File 'lib/kward/plugins/registry.rb', line 436

def prompt_context(&block)
  @registry.register_prompt_context(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) 


383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/kward/plugins/registry.rb', line 383

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



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

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



325
326
327
 
# File 'lib/kward/plugins/registry.rb', line 325

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



504
505
506
 
# File 'lib/kward/plugins/registry.rb', line 504

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