kward 0.84.0 → 0.86.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +164 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +6 -2
- data/README.md +5 -5
- data/Rakefile +3 -0
- data/doc/agent-tools.md +24 -1
- data/doc/api.md +20 -2
- data/doc/composer.md +5 -4
- data/doc/configuration.md +86 -14
- data/doc/extensibility.md +4 -1
- data/doc/getting-started.md +3 -3
- data/doc/git.md +4 -2
- data/doc/memory.md +1 -1
- data/doc/pan.md +6 -0
- data/doc/permissions.md +4 -4
- data/doc/plugins.md +504 -20
- data/doc/providers.md +10 -4
- data/doc/rpc.md +279 -23
- data/doc/sandboxing.md +11 -5
- data/doc/security.md +7 -1
- data/doc/session-management.md +41 -5
- data/doc/shell.md +643 -27
- data/doc/tabs.md +8 -3
- data/doc/transports.md +15 -0
- data/doc/troubleshooting.md +1 -1
- data/doc/usage.md +25 -12
- data/doc/workspace-tools.md +9 -0
- data/examples/plugins/openrouter_proxy/README.md +103 -0
- data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
- data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
- data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
- data/examples/plugins/openrouter_proxy/server.rb +186 -0
- data/examples/plugins/space_invaders.rb +1 -2
- data/examples/plugins/stardate_footer.rb +2 -2
- data/examples/plugins/telegram/plugin.rb +1 -1
- data/exe/kward +2 -2
- data/exe/kwsh +7 -0
- data/kward.gemspec +3 -1
- data/lib/kward/agent.rb +66 -19
- data/lib/kward/cli/commands.rb +41 -11
- data/lib/kward/cli/compaction.rb +9 -3
- data/lib/kward/cli/interactive_turn.rb +10 -0
- data/lib/kward/cli/plugins.rb +85 -12
- data/lib/kward/cli/prompt_interface.rb +29 -6
- data/lib/kward/cli/rendering.rb +24 -28
- data/lib/kward/cli/runtime_helpers.rb +168 -56
- data/lib/kward/cli/sessions.rb +9 -5
- data/lib/kward/cli/settings/menus.rb +745 -0
- data/lib/kward/cli/settings/model.rb +316 -0
- data/lib/kward/cli/settings.rb +6 -1055
- data/lib/kward/cli/slash_commands.rb +45 -4
- data/lib/kward/cli/tabs.rb +257 -44
- data/lib/kward/cli/tool_summaries.rb +2 -0
- data/lib/kward/{cli_transcript_formatter.rb → cli/transcript_formatter.rb} +6 -13
- data/lib/kward/cli/worktrees.rb +66 -2
- data/lib/kward/cli.rb +82 -31
- data/lib/kward/compactor.rb +18 -7
- data/lib/kward/config/core.rb +400 -0
- data/lib/kward/config/extensions.rb +99 -0
- data/lib/kward/config/paths.rb +11 -0
- data/lib/kward/config/prompts.rb +313 -0
- data/lib/kward/config/settings.rb +257 -0
- data/lib/kward/config_files.rb +14 -1008
- data/lib/kward/conversation.rb +41 -2
- data/lib/kward/entrypoint.rb +14 -0
- data/lib/kward/events.rb +2 -0
- data/lib/kward/generated_images.rb +237 -0
- data/lib/kward/image_attachments.rb +1 -1
- data/lib/kward/model/catalog.rb +6 -3
- data/lib/kward/model/client.rb +107 -38
- data/lib/kward/model/codex_images.rb +83 -0
- data/lib/kward/model/copilot_models.rb +10 -6
- data/lib/kward/model/model_info.rb +42 -7
- data/lib/kward/{openrouter_model_cache.rb → model/openrouter_model_cache.rb} +7 -5
- data/lib/kward/model/payloads.rb +18 -8
- data/lib/kward/model/sources.rb +3 -1
- data/lib/kward/model/stream_parser.rb +4 -7
- data/lib/kward/model/typesafe_client.rb +78 -0
- data/lib/kward/pan/index.html.erb +8 -1
- data/lib/kward/pan/server.rb +23 -8
- data/lib/kward/permissions/policy.rb +6 -2
- data/lib/kward/plugin_registry.rb +2 -659
- data/lib/kward/plugins/actions.rb +453 -0
- data/lib/kward/plugins/chat_contract.rb +121 -0
- data/lib/kward/{plugin_chat_runtime.rb → plugins/chat_runtime.rb} +62 -18
- data/lib/kward/plugins/codex_responses.rb +73 -0
- data/lib/kward/plugins/host.rb +248 -0
- data/lib/kward/plugins/http_server.rb +83 -0
- data/lib/kward/plugins/registry.rb +1229 -0
- data/lib/kward/plugins/resources.rb +206 -0
- data/lib/kward/plugins/turn_request.rb +36 -0
- data/lib/kward/plugins/ui.rb +219 -0
- data/lib/kward/prompt_interface/composer_controller.rb +0 -1
- data/lib/kward/prompt_interface/composer_renderer.rb +160 -73
- data/lib/kward/prompt_interface/composer_state.rb +1 -1
- data/lib/kward/prompt_interface/editor/controller.rb +2 -2
- data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
- data/lib/kward/prompt_interface/editor/runner.rb +1 -1
- data/lib/kward/prompt_interface/editor/state.rb +1 -1
- data/lib/kward/prompt_interface/file_overlay.rb +3 -3
- data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
- data/lib/kward/prompt_interface/git_prompt.rb +18 -11
- data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
- data/lib/kward/prompt_interface/interactive/state.rb +18 -20
- data/lib/kward/prompt_interface/key_handler.rb +108 -25
- data/lib/kward/prompt_interface/layout.rb +11 -1
- data/lib/kward/prompt_interface/overlay_renderer.rb +26 -9
- data/lib/kward/prompt_interface/plugin_ui_requests.rb +82 -0
- data/lib/kward/prompt_interface/project_browser.rb +27 -54
- data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
- data/lib/kward/prompt_interface/question_prompt.rb +19 -28
- data/lib/kward/prompt_interface/runtime_state.rb +37 -10
- data/lib/kward/prompt_interface/screen.rb +30 -20
- data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
- data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
- data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
- data/lib/kward/prompt_interface.rb +149 -30
- data/lib/kward/prompts/commands.rb +2 -1
- data/lib/kward/prompts.rb +7 -1
- data/lib/kward/{adaptive_pty_output_sink.rb → pty/adaptive_output_sink.rb} +39 -5
- data/lib/kward/{interactive_pty_runner.rb → pty/interactive_runner.rb} +22 -30
- data/lib/kward/{local_command_runner.rb → pty/local_command_runner.rb} +1 -1
- data/lib/kward/{local_pty_command_runner.rb → pty/local_pty_runner.rb} +3 -9
- data/lib/kward/{pty_output_sink.rb → pty/output_sink.rb} +9 -4
- data/lib/kward/pty/transcript_normalizer.rb +137 -0
- data/lib/kward/rpc/config_manager.rb +3 -0
- data/lib/kward/rpc/plugin_chat_manager.rb +30 -10
- data/lib/kward/rpc/prompt_bridge.rb +25 -0
- data/lib/kward/rpc/server.rb +118 -17
- data/lib/kward/rpc/session_manager.rb +208 -60
- data/lib/kward/rpc/session_tree_rows.rb +2 -2
- data/lib/kward/rpc/tool_metadata.rb +1 -1
- data/lib/kward/rpc/transcript_normalizer.rb +11 -7
- data/lib/kward/sandbox/command_runner.rb +1 -1
- data/lib/kward/{session_catalog.rb → sessions/catalog.rb} +1 -1
- data/lib/kward/{session_store.rb → sessions/store.rb} +39 -12
- data/lib/kward/{session_tree_nodes.rb → sessions/tree_nodes.rb} +3 -3
- data/lib/kward/{session_tree_renderer.rb → sessions/tree_renderer.rb} +4 -4
- data/lib/kward/{session_tree_tool_display.rb → sessions/tree_tool_display.rb} +1 -1
- data/lib/kward/{kwsh.rb → shell/kwsh.rb} +30 -10
- data/lib/kward/{kwshrc.rb → shell/kwshrc.rb} +11 -2
- data/lib/kward/shell/native_arithmetic.rb +255 -0
- data/lib/kward/shell/native_arrays.rb +102 -0
- data/lib/kward/shell/native_braces.rb +96 -0
- data/lib/kward/shell/native_builtins.rb +476 -0
- data/lib/kward/shell/native_completion.rb +169 -0
- data/lib/kward/shell/native_condition.rb +75 -0
- data/lib/kward/shell/native_directory.rb +116 -0
- data/lib/kward/shell/native_exec_state.rb +73 -0
- data/lib/kward/shell/native_expansion.rb +252 -0
- data/lib/kward/shell/native_fields.rb +62 -0
- data/lib/kward/shell/native_glob.rb +96 -0
- data/lib/kward/shell/native_history.rb +242 -0
- data/lib/kward/shell/native_interactive.rb +164 -0
- data/lib/kward/shell/native_invocation.rb +42 -0
- data/lib/kward/shell/native_jobs.rb +250 -0
- data/lib/kward/shell/native_line_editor.rb +382 -0
- data/lib/kward/shell/native_line_terminal.rb +286 -0
- data/lib/kward/shell/native_locale.rb +109 -0
- data/lib/kward/shell/native_locals.rb +57 -0
- data/lib/kward/shell/native_pattern.rb +200 -0
- data/lib/kward/shell/native_process.rb +279 -0
- data/lib/kward/shell/native_program.rb +40 -0
- data/lib/kward/shell/native_programmable_completion.rb +115 -0
- data/lib/kward/shell/native_prompt_format.rb +89 -0
- data/lib/kward/shell/native_runtime.rb +964 -0
- data/lib/kward/shell/native_substitution.rb +110 -0
- data/lib/kward/shell/native_syntax.rb +946 -0
- data/lib/kward/shell/native_traps.rb +196 -0
- data/lib/kward/shell/native_vi.rb +407 -0
- data/lib/kward/shell/native_vi_terminal.rb +19 -0
- data/lib/kward/shell/native_worker.rb +82 -0
- data/lib/kward/{persistent_shell_session.rb → shell/persistent_session.rb} +187 -193
- data/lib/kward/shell/prompt.rb +66 -0
- data/lib/kward/shell/prompt_agent.rb +17 -0
- data/lib/kward/{shell_prompt_session.rb → shell/prompt_session.rb} +1 -1
- data/lib/kward/shell/script_runner.rb +244 -0
- data/lib/kward/shell/standalone_agent.rb +31 -0
- data/lib/kward/shell/standalone_link.rb +78 -0
- data/lib/kward/shell/standalone_terminal.rb +287 -0
- data/lib/kward/skills/trust_store.rb +1 -1
- data/lib/kward/tabs/driver.rb +194 -0
- data/lib/kward/{tab_store.rb → tabs/store.rb} +2 -2
- data/lib/kward/{clipboard.rb → terminal/clipboard.rb} +1 -1
- data/lib/kward/{terminal_image_support.rb → terminal/image_support.rb} +1 -1
- data/lib/kward/{terminal_keys.rb → terminal/keys.rb} +22 -1
- data/lib/kward/terminal/locale_text.rb +29 -0
- data/lib/kward/{terminal_sequences.rb → terminal/sequences.rb} +45 -4
- data/lib/kward/tools/base.rb +18 -0
- data/lib/kward/tools/context_for_task.rb +15 -6
- data/lib/kward/tools/datetime.rb +85 -0
- data/lib/kward/tools/edit_file.rb +9 -6
- data/lib/kward/tools/generate_image.rb +36 -0
- data/lib/kward/tools/git_commit.rb +13 -7
- data/lib/kward/tools/list_directory.rb +4 -4
- data/lib/kward/tools/plugin_tool.rb +41 -0
- data/lib/kward/tools/prepare_shell_command.rb +1 -1
- data/lib/kward/tools/read_file.rb +7 -6
- data/lib/kward/tools/registry.rb +130 -21
- data/lib/kward/tools/run_shell_command.rb +10 -8
- data/lib/kward/tools/search/code.rb +1 -1
- data/lib/kward/tools/summarize_file_structure.rb +5 -5
- data/lib/kward/tools/tool_call.rb +4 -1
- data/lib/kward/tools/typesafe_evaluate.rb +81 -0
- data/lib/kward/tools/workspace_targets.rb +58 -0
- data/lib/kward/tools/write_file.rb +9 -6
- data/lib/kward/{export_path.rb → transcripts/export_path.rb} +1 -1
- data/lib/kward/{markdown_transcript.rb → transcripts/markdown_transcript.rb} +10 -2
- data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
- data/lib/kward/transport/contracts.rb +200 -0
- data/lib/kward/transport/gateway.rb +81 -36
- data/lib/kward/transport/plugin_chat_gateway.rb +3 -2
- data/lib/kward/transport.rb +1 -200
- data/lib/kward/turn_summary.rb +68 -0
- data/lib/kward/version.rb +1 -1
- data/lib/kward/{workspace_factory.rb → workspace/factory.rb} +2 -2
- data/lib/kward/{git_worktree_manager.rb → workspace/git_worktree_manager.rb} +28 -0
- data/lib/kward/{workspace.rb → workspace/workspace.rb} +3 -3
- data/lib/main.rb +6 -3
- data/templates/default/fulldoc/html/css/kward.css +125 -0
- data/templates/default/fulldoc/html/images/kward_screen_1.png +0 -0
- data/templates/default/fulldoc/html/setup.rb +1 -1
- data/templates/default/layout/html/layout.erb +16 -4
- metadata +150 -48
- data/lib/kward/pty_transcript_normalizer.rb +0 -93
- data/lib/kward/shell_prompt.rb +0 -52
- data/lib/kward/tab_driver.rb +0 -90
- data/templates/default/fulldoc/html/images/kward_workflow.svg +0 -52
- /data/lib/kward/{editor_prompt.rb → cli/editor_prompt.rb} +0 -0
- /data/lib/kward/{editor_prompt_session.rb → cli/editor_prompt_session.rb} +0 -0
- /data/lib/kward/{diff_view_mode.rb → prompt_interface/editor/diff_view_mode.rb} +0 -0
- /data/lib/kward/{editor_mode.rb → prompt_interface/editor/editor_mode.rb} +0 -0
- /data/lib/kward/{markdown_code_block.rb → prompt_interface/editor/markdown_code_block.rb} +0 -0
- /data/lib/kward/{scratchpad_languages.rb → prompt_interface/editor/scratchpad_languages.rb} +0 -0
- /data/lib/kward/{scratchpad_runner.rb → prompt_interface/editor/scratchpad_runner.rb} +0 -0
- /data/lib/kward/{detached_run.rb → pty/detached_run.rb} +0 -0
- /data/lib/kward/{session_diff.rb → sessions/diff.rb} +0 -0
- /data/lib/kward/{session_naming.rb → sessions/naming.rb} +0 -0
- /data/lib/kward/{session_trash.rb → sessions/trash.rb} +0 -0
- /data/lib/kward/{ansi.rb → terminal/ansi.rb} +0 -0
- /data/lib/kward/{terminal_text.rb → terminal/text.rb} +0 -0
- /data/lib/kward/{transcript_export.rb → transcripts/transcript_export.rb} +0 -0
- /data/lib/kward/{project_files.rb → workspace/files.rb} +0 -0
- /data/lib/kward/{path_guard.rb → workspace/path_guard.rb} +0 -0
data/doc/plugins.md
CHANGED
|
@@ -5,6 +5,7 @@ Plugins are trusted local Ruby extensions for Kward. Use them when you need beha
|
|
|
5
5
|
Good plugin use cases:
|
|
6
6
|
|
|
7
7
|
- add a slash command for a personal workflow,
|
|
8
|
+
- expose a local integration as a model-callable tool,
|
|
8
9
|
- show project/session status in the terminal footer,
|
|
9
10
|
- add concise local context to prompts,
|
|
10
11
|
- log or observe transcript events,
|
|
@@ -21,7 +22,7 @@ Plugins run inside the Kward process with your user permissions. Install only pl
|
|
|
21
22
|
| Repository rules | `AGENTS.md` |
|
|
22
23
|
| Local Ruby code or integration | plugin |
|
|
23
24
|
|
|
24
|
-
See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations.
|
|
25
|
+
See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations. The [OpenRouter proxy example guide](https://github.com/kaiwood/kward/blob/main/examples/plugins/openrouter_proxy/README.md) documents its startup option, managed HTTP listener, and local fake embeddings.
|
|
25
26
|
|
|
26
27
|
## Where plugins live
|
|
27
28
|
|
|
@@ -49,7 +50,7 @@ mkdir -p ~/.kward/plugins
|
|
|
49
50
|
Create `~/.kward/plugins/hello.rb`:
|
|
50
51
|
|
|
51
52
|
```ruby
|
|
52
|
-
Kward.plugin do |plugin|
|
|
53
|
+
Kward.plugin(id: "com.example.hello", version: "1.0.0", api: 1) do |plugin|
|
|
53
54
|
plugin.command "hello", description: "Say hello", argument_hint: "[name]" do |args, ctx|
|
|
54
55
|
name = args.strip.empty? ? "there" : args.strip
|
|
55
56
|
ctx.say("Hello, #{name}.")
|
|
@@ -65,6 +66,146 @@ Start Kward and run:
|
|
|
65
66
|
|
|
66
67
|
When developing plugins or prompt templates, use `/reload` inside Kward to reload configured prompt files and all plugin files without restarting. This picks up prompt edits, changes to existing plugins, and new plugin registrations, then refreshes slash-command completion and rebuilds the system message.
|
|
67
68
|
|
|
69
|
+
## Plugin identity and host services
|
|
70
|
+
|
|
71
|
+
Give a reusable plugin a stable reverse-domain-style `id`, its own `version`, and
|
|
72
|
+
the Kward plugin API it targets. API version `1` is currently supported. Kward
|
|
73
|
+
skips plugins that declare an unsupported API version or duplicate another
|
|
74
|
+
plugin's ID.
|
|
75
|
+
|
|
76
|
+
An identified plugin receives one shared host for configuration, private durable
|
|
77
|
+
storage, secret lookup, and logging:
|
|
78
|
+
|
|
79
|
+
```ruby
|
|
80
|
+
Kward.plugin(id: "com.example.issues", version: "1.2.0", api: 1) do |plugin|
|
|
81
|
+
host = plugin.host
|
|
82
|
+
|
|
83
|
+
plugin.command "issue-server", description: "Show the issue server" do |_args, ctx|
|
|
84
|
+
visits = host.storage.get("visits").to_i + 1
|
|
85
|
+
endpoint = host.config.fetch("endpoint")
|
|
86
|
+
host.storage.put("visits", visits)
|
|
87
|
+
ctx.say("#{endpoint} (visit #{visits})")
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Configure the plugin under its stable ID in `config.json`:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"plugins": {
|
|
97
|
+
"com.example.issues": {
|
|
98
|
+
"endpoint": "https://issues.example.com"
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The host exposes:
|
|
105
|
+
|
|
106
|
+
- `host.id`, `host.version`, and `host.api_version`;
|
|
107
|
+
- `host.config`, an immutable copy of the plugin's namespaced configuration;
|
|
108
|
+
- `host.storage.get`, `put`, and `delete` for JSON-compatible values;
|
|
109
|
+
- `host.secret(name, env: nil)` for private config or environment lookup;
|
|
110
|
+
- `host.logger`, a standard Ruby logger routed through Kward's diagnostic output.
|
|
111
|
+
|
|
112
|
+
Storage is kept in `plugin_state/<plugin-id>/state.json` under Kward's active
|
|
113
|
+
config directory and survives `/reload`. Secret lookup checks plugin config,
|
|
114
|
+
then the optional explicit environment variable, then a conventional name such
|
|
115
|
+
as `KWARD_PLUGIN_COM_EXAMPLE_ISSUES_TOKEN`. Do not log secret values.
|
|
116
|
+
|
|
117
|
+
Existing `Kward.plugin do ... end` files remain supported, but `plugin.host` is
|
|
118
|
+
`nil` until the plugin declares stable identity metadata.
|
|
119
|
+
|
|
120
|
+
## Lifecycle and owned background work
|
|
121
|
+
|
|
122
|
+
Plugin files are loaded without starting runtime work. Identified plugins can
|
|
123
|
+
register lifecycle callbacks for the points where managed work is safe:
|
|
124
|
+
|
|
125
|
+
```ruby
|
|
126
|
+
Kward.plugin(id: "com.example.watcher", version: "1.0.0", api: 1) do |plugin|
|
|
127
|
+
plugin.on_start do |host|
|
|
128
|
+
subscription = Watcher.subscribe { |event| host.logger.info(event) }
|
|
129
|
+
host.on_cleanup(subscription) { |value| Watcher.unsubscribe(value) }
|
|
130
|
+
|
|
131
|
+
host.background(name: "poller") do |cancellation|
|
|
132
|
+
until cancellation.cancelled?
|
|
133
|
+
Watcher.poll
|
|
134
|
+
sleep 1
|
|
135
|
+
end
|
|
136
|
+
end
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
plugin.on_reload { |host| host.logger.info("Reloading") }
|
|
140
|
+
plugin.on_shutdown { |host| host.logger.info("Stopping") }
|
|
141
|
+
end
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Lifecycle behavior is explicit:
|
|
145
|
+
|
|
146
|
+
- `on_start` runs after loading, when the registry becomes active. A newly loaded
|
|
147
|
+
registry receives `on_start` after `/reload` too.
|
|
148
|
+
- `on_reload` runs on the old plugin instance immediately before Kward cleans up
|
|
149
|
+
its resources.
|
|
150
|
+
- `on_shutdown` runs immediately before final process cleanup.
|
|
151
|
+
- Callback failures are reported as warnings and do not prevent other plugins
|
|
152
|
+
from cleaning up.
|
|
153
|
+
|
|
154
|
+
`host.background` returns a `PluginTask`. Its block may accept a cooperative
|
|
155
|
+
`Cancellation` token. Kward cancels and waits up to a bounded deadline for owned
|
|
156
|
+
tasks during reload or shutdown; blocking work should register cleanup that
|
|
157
|
+
closes the socket, stream, or other resource needed to wake it. Tasks also accept
|
|
158
|
+
an optional parent token with `cancellation:`.
|
|
159
|
+
|
|
160
|
+
`host.on_cleanup(resource) { |resource| ... }` returns an idempotent
|
|
161
|
+
`PluginDisposable`. Call `dispose` to unsubscribe early, or leave it registered
|
|
162
|
+
for automatic cleanup. `host.manage` is an alias. Cleanup runs in reverse
|
|
163
|
+
registration order so dependent resources unwind predictably.
|
|
164
|
+
|
|
165
|
+
`host.http_server` creates a loopback-only managed HTTP listener. It defaults to
|
|
166
|
+
an ephemeral port, a 1 MiB maximum request size, a 30-second request timeout,
|
|
167
|
+
and eight clients. Pass an explicit port when a local application needs a stable
|
|
168
|
+
address. Start the server with `server.start`, inspect `server.port`, wait with
|
|
169
|
+
`server.wait`, and stop it with `server.stop`; plugin cleanup stops it
|
|
170
|
+
automatically. The handler receives WEBrick's request and response objects.
|
|
171
|
+
|
|
172
|
+
`host.codex_responses.stream(model:, input:, instructions: nil, text: nil)`
|
|
173
|
+
streams Responses-shaped events through Kward's normal Codex provider client,
|
|
174
|
+
using the configured Codex credentials and account context. It never returns the
|
|
175
|
+
authentication token. The caller should handle failed or incomplete turns. This
|
|
176
|
+
uses Kward's existing private Codex backend route and is coupled to that
|
|
177
|
+
undocumented endpoint; prefer it only when matching normal Kward Codex behavior
|
|
178
|
+
is required. Do not read Kward's auth files directly.
|
|
179
|
+
|
|
180
|
+
Plugin-owned tab hosts expose the same `background`, `on_cleanup`, and `manage`
|
|
181
|
+
methods. Their resources are cleaned up when a local tab closes or its shared
|
|
182
|
+
plugin-chat runtime shuts down. A tab driver may implement `close` (or `shutdown`
|
|
183
|
+
as a fallback) for its own final cleanup; Kward invokes it before closing the tab
|
|
184
|
+
host.
|
|
185
|
+
|
|
186
|
+
Do not open network connections or start threads directly while the plugin file
|
|
187
|
+
is loading. Register them from `on_start`, a command, or a plugin-tab factory so
|
|
188
|
+
Kward can own their lifetime.
|
|
189
|
+
|
|
190
|
+
## Add a top-level startup option
|
|
191
|
+
|
|
192
|
+
Identified plugins can declare a no-argument switch for a foreground CLI mode:
|
|
193
|
+
|
|
194
|
+
```ruby
|
|
195
|
+
Kward.plugin(id: "com.example.server", version: "1.0.0", api: 1) do |plugin|
|
|
196
|
+
plugin.startup_option("--example-server", description: "Run the example server") do |host|
|
|
197
|
+
ExampleServer.new(host).run
|
|
198
|
+
end
|
|
199
|
+
end
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The handler is called only when the user selects the option. Kward loads plugin
|
|
203
|
+
registrations to identify plugin-owned switches before normal command dispatch,
|
|
204
|
+
but does not start lifecycle callbacks or run the handler unless the mode is
|
|
205
|
+
selected. A startup option cannot be combined with a prompt or another startup
|
|
206
|
+
option. Keep loading code side-effect-free; the handler should own the selected
|
|
207
|
+
foreground mode and return when it stops.
|
|
208
|
+
|
|
68
209
|
## Add a slash command
|
|
69
210
|
|
|
70
211
|
Use plugin commands for local actions that should not call the model.
|
|
@@ -82,6 +223,264 @@ Command names do not include `/`. They must start with a letter or number and ma
|
|
|
82
223
|
|
|
83
224
|
A plugin command cannot replace a built-in command or prompt-template command.
|
|
84
225
|
|
|
226
|
+
### Typed command arguments and results
|
|
227
|
+
|
|
228
|
+
Add an object JSON Schema when a command needs validated arguments. Interactive
|
|
229
|
+
slash commands use shell-style `--flags`; RPC clients may send either the same
|
|
230
|
+
text or an argument object. Declare `positionals:` when selected properties may
|
|
231
|
+
be supplied without flags:
|
|
232
|
+
|
|
233
|
+
```ruby
|
|
234
|
+
Kward.plugin(id: "com.example.release", version: "1.0.0", api: 1) do |plugin|
|
|
235
|
+
plugin.command "deploy",
|
|
236
|
+
description: "Deploy a service",
|
|
237
|
+
argument_hint: "SERVICE [--environment NAME] [--dry-run]",
|
|
238
|
+
schema: {
|
|
239
|
+
type: "object",
|
|
240
|
+
properties: {
|
|
241
|
+
service: { type: "string" },
|
|
242
|
+
environment: {
|
|
243
|
+
type: "string",
|
|
244
|
+
enum: %w[staging production],
|
|
245
|
+
default: "staging"
|
|
246
|
+
},
|
|
247
|
+
dry_run: { type: "boolean", default: false },
|
|
248
|
+
labels: { type: "array", items: { type: "string" } }
|
|
249
|
+
},
|
|
250
|
+
required: ["service"]
|
|
251
|
+
},
|
|
252
|
+
positionals: ["service"] do |args, ctx|
|
|
253
|
+
deployment = Release.deploy(
|
|
254
|
+
args.fetch("service"),
|
|
255
|
+
environment: args.fetch("environment"),
|
|
256
|
+
dry_run: args.fetch("dry_run"),
|
|
257
|
+
labels: args.fetch("labels", [])
|
|
258
|
+
)
|
|
259
|
+
ctx.result(
|
|
260
|
+
message: "Queued deployment #{deployment.id}.",
|
|
261
|
+
data: { deployment_id: deployment.id }
|
|
262
|
+
)
|
|
263
|
+
end
|
|
264
|
+
end
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
For example:
|
|
268
|
+
|
|
269
|
+
```text
|
|
270
|
+
/deploy api --environment production --dry-run --labels urgent --labels "release candidate"
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Typed command handlers receive a string-keyed argument hash through both the
|
|
274
|
+
first block argument and `ctx.args`. Supported property types are `string`,
|
|
275
|
+
`integer`, `number`, `boolean`, `array`, and `object`; array items must be scalar.
|
|
276
|
+
Use `--flag` or `--no-flag` for booleans, repeat an array option to collect
|
|
277
|
+
values, and use `--` before positional text that starts with a dash. Unknown,
|
|
278
|
+
missing, duplicate, incorrectly typed, and out-of-enum arguments are rejected
|
|
279
|
+
before plugin code runs. Commands without `schema:` keep receiving their raw
|
|
280
|
+
argument string for compatibility.
|
|
281
|
+
|
|
282
|
+
`ctx.result(message:, data:)` returns optional user-facing text plus optional
|
|
283
|
+
JSON-compatible machine data. The TUI displays `message`. RPC returns the full
|
|
284
|
+
structured result, and asynchronous slash-command turns also emit a
|
|
285
|
+
`pluginCommandResult` event before their normal answer event.
|
|
286
|
+
|
|
287
|
+
## Add a namespaced action
|
|
288
|
+
|
|
289
|
+
Actions are typed operations intended for trusted RPC integrations rather than
|
|
290
|
+
slash-command completion. They require identified plugin metadata and receive a
|
|
291
|
+
stable `<plugin-id>/<action-name>` ID:
|
|
292
|
+
|
|
293
|
+
```ruby
|
|
294
|
+
Kward.plugin(id: "com.example.release", version: "1.0.0", api: 1) do |plugin|
|
|
295
|
+
plugin.action "status",
|
|
296
|
+
description: "Read deployment status",
|
|
297
|
+
schema: {
|
|
298
|
+
type: "object",
|
|
299
|
+
properties: { deployment_id: { type: "integer" } },
|
|
300
|
+
required: ["deployment_id"]
|
|
301
|
+
} do |args, ctx|
|
|
302
|
+
deployment = Release.find(args.fetch("deployment_id"))
|
|
303
|
+
ctx.result(data: { id: deployment.id, state: deployment.state })
|
|
304
|
+
end
|
|
305
|
+
end
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
RPC clients discover actions with `pluginActions/list` and invoke them with
|
|
309
|
+
`pluginActions/run`. Action arguments must be an object and results always use
|
|
310
|
+
the structured `{ message, data }` contract. Synchronous actions support
|
|
311
|
+
`ctx.say`, progress, and notifications, but blocking UI requests fail closed so
|
|
312
|
+
the RPC reader cannot deadlock. Actions are disabled when the session execution
|
|
313
|
+
profile disables plugin commands. They are not exposed as local TUI commands;
|
|
314
|
+
register a typed command as well when people should invoke the operation from
|
|
315
|
+
the composer.
|
|
316
|
+
|
|
317
|
+
## Add a model-callable tool
|
|
318
|
+
|
|
319
|
+
Plugin tools let the model call trusted local Ruby integrations without requiring
|
|
320
|
+
an MCP server. Define a model-facing description and a strict object JSON Schema
|
|
321
|
+
for the arguments:
|
|
322
|
+
|
|
323
|
+
```ruby
|
|
324
|
+
Kward.plugin do |plugin|
|
|
325
|
+
plugin.tool "issue_search",
|
|
326
|
+
description: "Search the local issue tracker",
|
|
327
|
+
schema: {
|
|
328
|
+
type: "object",
|
|
329
|
+
properties: {
|
|
330
|
+
query: { type: "string", description: "Issue search text." },
|
|
331
|
+
limit: { type: "integer", description: "Maximum results." }
|
|
332
|
+
},
|
|
333
|
+
required: ["query"]
|
|
334
|
+
} do |args, ctx|
|
|
335
|
+
ctx.cancellation&.raise_if_cancelled!
|
|
336
|
+
IssueTracker.search(args.fetch("query"), limit: args.fetch("limit", 10))
|
|
337
|
+
.map { |issue| "#{issue.id}: #{issue.title}" }
|
|
338
|
+
.join("\n")
|
|
339
|
+
end
|
|
340
|
+
end
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
The handler receives a parsed argument hash and a normal plugin context. It
|
|
344
|
+
should return model-facing text. `ctx.cancellation` contains the
|
|
345
|
+
active cooperative cancellation token, and `ctx.cancelled?` is a convenient
|
|
346
|
+
boolean check for longer operations.
|
|
347
|
+
|
|
348
|
+
Plugin tool schemas are exposed in normal CLI, RPC, Pan, and transport-backed
|
|
349
|
+
agent turns. Kward forces `additionalProperties: false`, validates required
|
|
350
|
+
property names, reports the tool source as `plugin`, and routes execution through
|
|
351
|
+
the normal permission policy, approval bridge, lifecycle hooks, output
|
|
352
|
+
compaction, and transcript artifact storage. Restricted execution profiles can
|
|
353
|
+
filter plugin tools by name or remove all tools. Editor-scoped prompts,
|
|
354
|
+
shell-agent prompts, and strict worktree agents do not receive plugin tools.
|
|
355
|
+
Plugin-owned chats continue to own their own tool behavior.
|
|
356
|
+
|
|
357
|
+
Plugin tools cannot replace built-in, MCP, or other plugin tools. Duplicate
|
|
358
|
+
plugin registrations are skipped with a warning. Because trusted plugin code can
|
|
359
|
+
perform arbitrary local or network effects, an enabled permission policy treats
|
|
360
|
+
plugin tools as approval-requiring operations unless an explicit allow rule
|
|
361
|
+
matches the tool or `source: plugin`.
|
|
362
|
+
|
|
363
|
+
## Use structured plugin UI
|
|
364
|
+
|
|
365
|
+
Plugin commands and model-callable plugin tools receive `ctx.ui`, a
|
|
366
|
+
frontend-neutral interface for questions, choices, confirmation, text input,
|
|
367
|
+
notifications, and progress:
|
|
368
|
+
|
|
369
|
+
```ruby
|
|
370
|
+
plugin.command "release", description: "Prepare a release" do |_args, ctx|
|
|
371
|
+
environment = ctx.ui.select(
|
|
372
|
+
"Environment",
|
|
373
|
+
[
|
|
374
|
+
{ label: "Staging", value: "staging", description: "Deploy for testing." },
|
|
375
|
+
{ label: "Production", value: "production", description: "Deploy publicly." }
|
|
376
|
+
]
|
|
377
|
+
)
|
|
378
|
+
next unless environment
|
|
379
|
+
next unless ctx.ui.confirm("Release", "Deploy to #{environment}?")
|
|
380
|
+
|
|
381
|
+
tag = ctx.ui.input("Release tag", "For example, v1.2.0")
|
|
382
|
+
next if tag.to_s.empty?
|
|
383
|
+
|
|
384
|
+
ctx.ui.progress(id: "release", message: "Preparing #{tag}", percent: 25)
|
|
385
|
+
# Perform work here.
|
|
386
|
+
ctx.ui.progress(id: "release", message: "Prepared #{tag}", percent: 100, done: true)
|
|
387
|
+
ctx.ui.notify("#{tag} is ready for #{environment}.", level: :success)
|
|
388
|
+
end
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
Available methods:
|
|
392
|
+
|
|
393
|
+
- `ctx.ui.question(questions)` uses the same validated 1-4 question contract as
|
|
394
|
+
`ask_user_question` and returns its answer array or `nil` when cancelled;
|
|
395
|
+
- `ctx.ui.select(title, options, message: nil)` accepts 1-100 strings or
|
|
396
|
+
`{ label:, value:, description: }` objects and returns the selected value;
|
|
397
|
+
- `ctx.ui.confirm(title, message = nil, default: false)` returns a boolean;
|
|
398
|
+
- `ctx.ui.input(title, placeholder = nil, default: nil)` returns text or `nil`;
|
|
399
|
+
- `ctx.ui.progress(id:, message:, percent: nil, done: false)` publishes a
|
|
400
|
+
non-blocking progress update;
|
|
401
|
+
- `ctx.ui.notify(message, level: :info)` publishes an `info`, `success`,
|
|
402
|
+
`warning`, or `error` notification;
|
|
403
|
+
- `ctx.ui.supported?(:select)` and `ctx.ui.capabilities` let a plugin inspect
|
|
404
|
+
the active frontend before requesting interaction.
|
|
405
|
+
|
|
406
|
+
Blocking requests fail closed when the active frontend does not support them:
|
|
407
|
+
questions, selections, and input return `nil`, while confirmation returns
|
|
408
|
+
`false`. Notifications and progress fall back to normal `ctx.say` text. Inputs
|
|
409
|
+
and emitted text are bounded, and plugin-tool cancellation is checked before
|
|
410
|
+
and after blocking requests.
|
|
411
|
+
|
|
412
|
+
The interactive terminal implements all six primitives. RPC implements them for
|
|
413
|
+
plugin commands submitted through `turns/start` and for plugin tools; use that
|
|
414
|
+
asynchronous turn path when a command needs to wait for UI input. Synchronous
|
|
415
|
+
RPC `commands/run` supports notifications and progress but deliberately fails
|
|
416
|
+
closed for blocking requests so the protocol reader cannot deadlock waiting for
|
|
417
|
+
its own response. Pan has no interaction bridge, so blocking requests fail
|
|
418
|
+
closed and non-blocking output falls back to its existing plugin message event.
|
|
419
|
+
Transport gateways expose blocking requests as transport-neutral interactions;
|
|
420
|
+
the transport adapter decides whether and how to render and answer them.
|
|
421
|
+
|
|
422
|
+
## Request a model response from a command
|
|
423
|
+
|
|
424
|
+
Use `ctx.request_turn(system: text)` when a slash command should run the active
|
|
425
|
+
session's model immediately with turn-scoped system instructions. For example,
|
|
426
|
+
save this as `~/.kward/plugins/iddqd.rb` and run `/reload`:
|
|
427
|
+
|
|
428
|
+
```ruby
|
|
429
|
+
Kward.plugin(id: "com.example.iddqd", version: "1.0.0", api: 1) do |plugin|
|
|
430
|
+
plugin.command "iddqd",
|
|
431
|
+
description: "Run a prompt as system instructions",
|
|
432
|
+
argument_hint: "<prompt>" do |text, ctx|
|
|
433
|
+
if text.strip.empty?
|
|
434
|
+
ctx.say("Usage: /iddqd <prompt>")
|
|
435
|
+
next
|
|
436
|
+
end
|
|
437
|
+
|
|
438
|
+
ctx.request_turn(system: text)
|
|
439
|
+
end
|
|
440
|
+
end
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
Then enter `/iddqd Answer in French and explain the current design.` The text
|
|
444
|
+
needs no quoting or flag parsing. Kward streams the response just like an ordinary
|
|
445
|
+
turn, with the same tools, permissions, hooks, cancellation, and tab ownership.
|
|
446
|
+
This does not replace Kward's base system prompt or bypass host security policy.
|
|
447
|
+
|
|
448
|
+
The call stages a request and returns `nil`; the host starts the model only after
|
|
449
|
+
the command successfully returns. A handler error or cancellation discards the
|
|
450
|
+
request. Each command may stage one request, containing nonblank text of at most
|
|
451
|
+
65,536 bytes. Instructions last through tool continuations, prompt refreshes,
|
|
452
|
+
compaction, and retries in that turn, then expire even if the turn fails.
|
|
453
|
+
|
|
454
|
+
Check `ctx.turn_requests_supported?` before offering this behavior on an unknown
|
|
455
|
+
host. It is supported by interactive CLI session commands, asynchronous RPC
|
|
456
|
+
`turns/start` commands, and session-backed transports whose execution profile
|
|
457
|
+
allows plugin commands. Synchronous RPC `commands/run`, plugin actions, plugin
|
|
458
|
+
owned chats, tools, hooks, status renderers, editor/shell prompts, and Pan do not
|
|
459
|
+
provide this capability. Unsupported calls raise an error rather than silently
|
|
460
|
+
launching work or submitting the text as a user prompt. Pan does not dispatch
|
|
461
|
+
plugin slash commands; use the TUI or RPC instead.
|
|
462
|
+
|
|
463
|
+
**History and provider notes:** the invocation and instruction text are stored
|
|
464
|
+
in the session for transcript display and export. Restoring, cloning, or forking
|
|
465
|
+
the session does not reactivate the instructions. Later model requests omit
|
|
466
|
+
these history entries; compaction receives an informational placeholder instead
|
|
467
|
+
of the expired text.
|
|
468
|
+
System-level input uses each provider's native instruction mechanism. On Codex
|
|
469
|
+
(ChatGPT subscription), the command becomes a new `developer` message at its
|
|
470
|
+
position in the conversation: that backend rejects inline `system` messages.
|
|
471
|
+
Direct OpenAI Responses and chat-completions payloads use an ordered `system`
|
|
472
|
+
message. These turn instructions are not folded into the base preamble, so the
|
|
473
|
+
model receives a new instruction after the preceding dialogue.
|
|
474
|
+
|
|
475
|
+
Anthropic and Gemini instead collect system instructions into a separate system
|
|
476
|
+
field; they cannot preserve that ordered-message boundary and require existing
|
|
477
|
+
dialogue. A system-only turn in an empty session is rejected explicitly. Other
|
|
478
|
+
provider/model restrictions surface as normal request errors. No synthetic user
|
|
479
|
+
prompt is inserted.
|
|
480
|
+
|
|
481
|
+
For instructions that should remain active in future turns instead, use prompt
|
|
482
|
+
context below.
|
|
483
|
+
|
|
85
484
|
## Add prompt context
|
|
86
485
|
|
|
87
486
|
Prompt context is short text injected into future model requests.
|
|
@@ -104,20 +503,53 @@ If plugin state changes and Kward should rebuild the active system message, call
|
|
|
104
503
|
ctx.refresh_system_message!
|
|
105
504
|
```
|
|
106
505
|
|
|
107
|
-
## Add
|
|
506
|
+
## Add status to the footer
|
|
507
|
+
|
|
508
|
+
Identified plugins can contribute compact status without replacing status from
|
|
509
|
+
other plugins. Give each contribution a stable name:
|
|
510
|
+
|
|
511
|
+
```ruby
|
|
512
|
+
Kward.plugin(id: "com.example.session-status", version: "1.0.0", api: 1) do |plugin|
|
|
513
|
+
plugin.status "session", order: 10, priority: :high do |ctx|
|
|
514
|
+
{
|
|
515
|
+
text: ctx.session_name || "unnamed",
|
|
516
|
+
tooltip: "Current Kward session"
|
|
517
|
+
}
|
|
518
|
+
end
|
|
519
|
+
|
|
520
|
+
plugin.status "messages", order: 20, priority: :low do |ctx|
|
|
521
|
+
"#{ctx.transcript.messages.length} messages"
|
|
522
|
+
end
|
|
523
|
+
end
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
Kward joins visible contributions with ` · `. Lower `order` values appear
|
|
527
|
+
first. `priority` may be `:low`, `:normal` (the default), or `:high`. When the
|
|
528
|
+
terminal is too narrow, Kward removes complete low-priority contributions
|
|
529
|
+
first, followed by normal- and high-priority contributions. Among contributions
|
|
530
|
+
with the same priority, later ones are removed first.
|
|
531
|
+
|
|
532
|
+
Return a string for ordinary status, a hash with `text` and optional `tooltip`
|
|
533
|
+
for structured clients, or `nil` to hide the contribution temporarily. One
|
|
534
|
+
renderer failing does not hide status from other plugins. Kward evaluates the
|
|
535
|
+
contributions at most once per second and reuses their values between refreshes.
|
|
536
|
+
|
|
537
|
+
RPC clients receive both the combined `text` fallback and the individual
|
|
538
|
+
structured segments. Terminal footers display the combined text; tooltips are
|
|
539
|
+
available to clients that can render them.
|
|
108
540
|
|
|
109
|
-
|
|
541
|
+
The older `plugin.footer` API remains supported. Each legacy footer is treated
|
|
542
|
+
as a normal-priority contribution, so footers from different plugins now
|
|
543
|
+
compose instead of replacing one another:
|
|
110
544
|
|
|
111
545
|
```ruby
|
|
112
546
|
Kward.plugin do |plugin|
|
|
113
547
|
plugin.footer do |ctx|
|
|
114
|
-
"#{ctx.session_name || 'unnamed'}
|
|
548
|
+
"#{ctx.session_name || 'unnamed'}"
|
|
115
549
|
end
|
|
116
550
|
end
|
|
117
551
|
```
|
|
118
552
|
|
|
119
|
-
Only one footer is active. If multiple plugins register footers, the later one replaces the earlier one and Kward prints a warning. Kward evaluates the active footer at most once per second and reuses its last value between refreshes.
|
|
120
|
-
|
|
121
553
|
## Add an interactive command
|
|
122
554
|
|
|
123
555
|
Interactive commands take over the composer region with a Kward-driven render and
|
|
@@ -136,7 +568,7 @@ Kward.plugin do |plugin|
|
|
|
136
568
|
ui.put(0, x, "X", :red)
|
|
137
569
|
x = (x + 1) % ui.width
|
|
138
570
|
key = ui.poll_key
|
|
139
|
-
|
|
571
|
+
next :exit if key == "q"
|
|
140
572
|
ui.render
|
|
141
573
|
end
|
|
142
574
|
end
|
|
@@ -164,8 +596,9 @@ The `ui` controller object passed to the handler block exposes:
|
|
|
164
596
|
| `fps` | Target frame rate |
|
|
165
597
|
|
|
166
598
|
Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
|
|
167
|
-
`:backspace`, `:space`, `:pageup`, `:pagedown`) or raw strings for keys
|
|
168
|
-
without a named mapping.
|
|
599
|
+
`:backspace`, `:space`, `:pageup`, `:pagedown`, `:ctrl_c`) or raw strings for keys
|
|
600
|
+
without a named mapping. Kward exits on plain Esc. To add a quit key such as `q`
|
|
601
|
+
or Ctrl+C, handle it in the tick callback and call `ui.exit` or return `:exit`.
|
|
169
602
|
|
|
170
603
|
The tick callback runs at the configured frame rate (1–120 fps, default 30).
|
|
171
604
|
Calls to `put` and `clear_frame` stage canvas changes; call `render` after the
|
|
@@ -179,7 +612,7 @@ Returning `:exit` from the tick callback ends the loop, same as calling
|
|
|
179
612
|
cursor, and transcript viewport).
|
|
180
613
|
- Interactive mode is a distinct state from the busy-input spinner lifecycle —
|
|
181
614
|
no spinner or busy chrome is shown.
|
|
182
|
-
-
|
|
615
|
+
- Plain Esc, the plugin calling `exit`, or the tick callback returning `:exit`
|
|
183
616
|
all exit cleanly and restore the prior composer state.
|
|
184
617
|
- Resize during interactive mode forces a clean exit and restore.
|
|
185
618
|
|
|
@@ -190,13 +623,25 @@ in piped/non-interactive mode or through RPC.
|
|
|
190
623
|
|
|
191
624
|
A plugin can provide a persistent tab with Kward's normal composer, transcript
|
|
192
625
|
rendering, streaming, image input, cancellation, and tab switching. The plugin
|
|
193
|
-
owns its transcript
|
|
194
|
-
need to use a
|
|
626
|
+
owns its transcript and model behavior, while Kward can provide scoped storage,
|
|
627
|
+
configuration, secrets, logging, and resource cleanup. It does not need to use a
|
|
628
|
+
Kward workspace session.
|
|
195
629
|
|
|
196
630
|
```ruby
|
|
197
|
-
Kward.plugin do |plugin|
|
|
198
|
-
plugin.tab_type
|
|
199
|
-
|
|
631
|
+
Kward.plugin(id: "com.example.plugin", version: "1.0.0", api: 1) do |plugin|
|
|
632
|
+
plugin.tab_type(
|
|
633
|
+
"example",
|
|
634
|
+
id: "com.example.chat",
|
|
635
|
+
title: "Example",
|
|
636
|
+
singleton: :global,
|
|
637
|
+
api: 1,
|
|
638
|
+
capabilities: {
|
|
639
|
+
attachments: [:image],
|
|
640
|
+
steering: false,
|
|
641
|
+
transcript_paging: false
|
|
642
|
+
}
|
|
643
|
+
) do |host, descriptor|
|
|
644
|
+
ExampleChat.new(client: host.client, storage: host.storage, descriptor: descriptor)
|
|
200
645
|
end
|
|
201
646
|
end
|
|
202
647
|
```
|
|
@@ -210,6 +655,39 @@ Open it from interactive Kward:
|
|
|
210
655
|
`id` is a stable persisted identifier: do not change it after release.
|
|
211
656
|
Use `singleton: :global` for one plugin-managed chat shared by all tab views.
|
|
212
657
|
|
|
658
|
+
### Versioned chat contract
|
|
659
|
+
|
|
660
|
+
Pass `api: 1` and `capabilities:` together to opt into the versioned plugin-chat
|
|
661
|
+
contract. The capability object supports:
|
|
662
|
+
|
|
663
|
+
- `attachments`: currently `[]` or `[:image]`;
|
|
664
|
+
- `steering`: whether the driver supports in-flight steering;
|
|
665
|
+
- `transcript_paging`: whether the driver implements `transcript_page`.
|
|
666
|
+
|
|
667
|
+
Kward validates versioned drivers when they are created. A declared driver must
|
|
668
|
+
implement `messages`, `submit`, `descriptor`, `supports_steering?`, and
|
|
669
|
+
`assistant_label`. Its `supports_steering?` result must match the declaration,
|
|
670
|
+
and a driver declaring transcript paging must implement `transcript_page`.
|
|
671
|
+
Omitting both options preserves the legacy method-probing behavior.
|
|
672
|
+
|
|
673
|
+
The factory's `host` exposes:
|
|
674
|
+
|
|
675
|
+
- `host.plugin_id` (nil for a legacy anonymous plugin) and `host.type_id`;
|
|
676
|
+
- `host.surface`, one of `:local`, `:rpc`, `:transport`, or `:shared` when the
|
|
677
|
+
same runtime can serve RPC and transports;
|
|
678
|
+
- `host.scope_key`, persisted for local tabs and stable for RPC/transport scopes;
|
|
679
|
+
- `host.capabilities`, the declared contract;
|
|
680
|
+
- `host.config`, the identified plugin's immutable private configuration;
|
|
681
|
+
- `host.storage`, isolated by plugin, chat type, and scope;
|
|
682
|
+
- `host.secret(name, env: nil)` and `host.logger`;
|
|
683
|
+
- `host.background` and `host.on_cleanup` for work owned by this chat instance.
|
|
684
|
+
|
|
685
|
+
Closing a local tab or shutting down the shared RPC/transport chat runtime calls
|
|
686
|
+
the driver's optional `close` method (or `shutdown` fallback), then cleans up the
|
|
687
|
+
host's managed resources. Scoped storage remains durable across reconstruction.
|
|
688
|
+
Legacy plugins receive the same host surface using their stable tab type ID as
|
|
689
|
+
the configuration namespace.
|
|
690
|
+
|
|
213
691
|
Plugin tabs do not notify global transcript observers by default. Set
|
|
214
692
|
`transcript_events: true` only when the tab explicitly permits its streamed
|
|
215
693
|
content to be delivered to every installed `on_transcript_event` handler, such
|
|
@@ -308,13 +786,15 @@ Handlers receive a `ctx` object. Common methods:
|
|
|
308
786
|
- `ctx.workspace_root`
|
|
309
787
|
- `ctx.args`
|
|
310
788
|
- `ctx.say(message)`
|
|
789
|
+
- `ctx.result(message:, data:)`
|
|
790
|
+
- `ctx.ui`
|
|
311
791
|
- `ctx.transcript.messages`
|
|
312
792
|
- `ctx.session_id`
|
|
313
793
|
- `ctx.session_name`
|
|
314
794
|
- `ctx.session_path`
|
|
315
795
|
- `ctx.refresh_system_message!`
|
|
316
796
|
|
|
317
|
-
These methods are available in all handler types
|
|
797
|
+
These methods are available in all handler types, including model-callable tools, although `ctx.result` is the result contract specifically for typed commands and actions. Typed command and action handlers receive their validated hash through `ctx.args`; legacy commands continue to receive text. Model-callable tools and asynchronous TUI/RPC slash commands expose `ctx.cancellation` and `ctx.cancelled?`. `ctx.say` outputs to the active frontend (terminal or RPC) wherever it is called. Interactive `ctx.ui` methods remain capability-gated because not every handler runs in a frontend context that can wait for an answer.
|
|
318
798
|
|
|
319
799
|
The transcript is read-only. Use context methods instead of mutating Kward internals.
|
|
320
800
|
|
|
@@ -324,15 +804,19 @@ Plugins are available in the CLI and RPC backend.
|
|
|
324
804
|
|
|
325
805
|
RPC clients can:
|
|
326
806
|
|
|
807
|
+
- discover plugin tools through `tools/list`,
|
|
808
|
+
- invoke plugin tools through normal model turns,
|
|
327
809
|
- list plugin commands through `commands/list`,
|
|
328
|
-
- run plugin commands through `commands/run`,
|
|
329
|
-
- run plugin slash commands through `turns/start` input such as `/hello World
|
|
810
|
+
- run plugin commands through `commands/run`, including typed object arguments and structured results,
|
|
811
|
+
- run plugin slash commands through `turns/start` input such as `/hello World`,
|
|
812
|
+
- discover and run namespaced typed actions through `pluginActions/list` and `pluginActions/run`,
|
|
813
|
+
- render and answer structured plugin UI requests advertised through `extensionUi`.
|
|
330
814
|
|
|
331
815
|
Plugin command output is emitted through normal turn events without calling the model.
|
|
332
816
|
|
|
333
817
|
## Security
|
|
334
818
|
|
|
335
|
-
Plugins are local Ruby code. They can read files, write files, run commands, make network requests, and read environment variables as your user.
|
|
819
|
+
Plugins are local Ruby code. They can read files, write files, run commands, make network requests, and read environment variables as your user. Model-callable plugin tools execute in Kward's host process and are not contained by the command sandbox; permission checks decide whether a call starts but do not sandbox trusted plugin code after it begins.
|
|
336
820
|
|
|
337
821
|
Recommended practices:
|
|
338
822
|
|
data/doc/providers.md
CHANGED
|
@@ -117,9 +117,13 @@ Kward combines several sources so a temporary catalog failure does not lock you
|
|
|
117
117
|
4. the currently configured model;
|
|
118
118
|
5. a manual ID entered in `/model`.
|
|
119
119
|
|
|
120
|
-
When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others.
|
|
120
|
+
When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Unknown or empty metadata and the current selection stay visible. Use **Show all models** for embedding, preview, private, or unusually described models.
|
|
121
121
|
|
|
122
|
-
|
|
122
|
+
Known model choices can include configured or curated fallbacks, not just discovered IDs. Neither a listing nor successful discovery guarantees account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
|
|
123
|
+
|
|
124
|
+
**Refresh model list** refreshes only the active provider, or the provider chosen in the picker—not every configured provider. OpenRouter uses its own key-associated disk cache; Copilot and Local replace their process-local discovery results. Anthropic consumes its disk catalog alongside curated choices (live discovery requires an API key). API-key providers with discovery use their provider catalogs. Codex and providers without discovery, such as Azure deployment selection, retain curated/configured choices. Failed discovery preserves the last usable catalog.
|
|
125
|
+
|
|
126
|
+
Refreshing is not configuration reload. After another Kward process changes configuration or caches, RPC clients should explicitly call `runtime/reload` then `models/list`. Reload also reloads plugins and reapplies configuration-backed session runtime state; ordinary catalog reads and refreshes do neither. Copilot and Local have no shared persisted model catalog and rediscover lazily after reload. There is no automatic cross-process watcher or model-change notification.
|
|
123
127
|
|
|
124
128
|
## OAuth availability
|
|
125
129
|
|
|
@@ -133,8 +137,10 @@ RPC clients should discover providers rather than hard-code this table:
|
|
|
133
137
|
|
|
134
138
|
- `auth/providers` returns catalog providers and supported authentication methods;
|
|
135
139
|
- `auth/status` returns sanitized configured/source state;
|
|
136
|
-
- `models/list` returns known
|
|
137
|
-
- `models/refresh`
|
|
140
|
+
- `models/list` returns the complete known catalog; use `defaultSelectable` for the default picker and the full list for **Show all models**;
|
|
141
|
+
- `models/refresh` returns the catalog plus a safe `refresh` outcome (`provider`, `status`, `fallbackUsed`), distinguishing `success`, `unsupported`, and `failed`;
|
|
138
142
|
- `models/set` selects the provider and model.
|
|
139
143
|
|
|
144
|
+
Check `initialize` model field and refresh metadata capabilities before consuming additive fields. Keep `OpenAI` and `Codex` identities separate and pass provider/model IDs back unchanged, including slashes.
|
|
145
|
+
|
|
140
146
|
See the [RPC protocol](rpc.md#Config_and_auth_methods) for request shapes and unsupported OAuth capability reporting.
|