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/rpc.md
CHANGED
|
@@ -15,7 +15,7 @@ A typical client launches the server, sends `initialize`, creates or resumes a s
|
|
|
15
15
|
| Connect and negotiate capabilities | [Launch](#Launch), [Framing](#Framing), and [Initialization](#Initialization) |
|
|
16
16
|
| Open, resume, branch, or export a conversation | [Session methods](#Session_methods) |
|
|
17
17
|
| Send input and render a response | [Turn methods](#Turn_methods) and [Turn notifications](#Turn_notifications) |
|
|
18
|
-
| Handle tool approval or structured
|
|
18
|
+
| Handle tool approval or structured plugin UI | [Tool approval bridge](#Tool_approval_bridge) and [Structured UI bridge](#Structured_UI_bridge) |
|
|
19
19
|
| Show model, runtime, auth, or configuration controls | [Runtime methods](#Runtime_methods), [Model methods](#Model_methods), and [Config and auth methods](#Config_and_auth_methods) |
|
|
20
20
|
| Discover tools, MCP servers, prompts, skills, or plugins | [Tool and prompt methods](#Tool_and_prompt_methods) |
|
|
21
21
|
|
|
@@ -65,8 +65,10 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
|
|
|
65
65
|
- `transcript`: Kward transcript format support, including normalized messages, image/tool support, compaction summaries, and restored assistant reasoning as Pi-compatible `thinking` content blocks.
|
|
66
66
|
- `sessions`: explicit RPC session mode, JSONL persistence, and methods for listing, auto-resume, live-session discovery, linear forking, compaction, and labeled tree navigation with branch summaries. Import is unsupported. Live session updates are also unsupported but reserve the `session/updated` notification name. Git worktree bindings are reported as interactive-TUI-only.
|
|
67
67
|
- `turns`: asynchronous turns, per-session concurrency, active and recent turn lists, busy-input steering when the provider supports it, queued follow-ups, best-effort cancellation, and recent in-memory event replay. Per-turn options cover model, reasoning, tool scope, and tool approval, with structured client context for editor integrations.
|
|
68
|
-
- `
|
|
69
|
-
- `
|
|
68
|
+
- `plugins`: the supported plugin API version and public `id`, `version`, and `apiVersion` metadata for identified plugins. Private plugin configuration is never included.
|
|
69
|
+
- `pluginTools`: model-callable tools registered by trusted local plugins, including the registered count, `tools/list` discovery, execution-profile filtering, and permission-policy enforcement.
|
|
70
|
+
- `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. Versioned types report declared attachment, steering, and transcript-paging capabilities. Clients must explicitly subscribe before receiving `pluginChat/event` notifications; plugin chats are independent from workspace sessions. A type may also report `transport: true` when a trusted external transport is allowed to target it; RPC opt-in and external transport opt-in remain separate.
|
|
71
|
+
- `events`: the `turn/event` contract, assistant and reasoning events, typed plugin-command results, normalized tool metadata, tool updates and results, diff support, workspace guardrail status, focused-context and context-budget statistics tools, and explicitly unsupported shell changed-file and session-update flags.
|
|
70
72
|
- `attachments`: supported input attachment contract for `turns/start`, with accepted base64 image MIME types and a stable max byte value.
|
|
71
73
|
- `models`: model listing, refresh, selection, and exposed metadata across providers. Scoped model selection is not supported.
|
|
72
74
|
- `runtime`: runtime state, message-count statistics, and OpenAI/Codex context usage. Kward does not yet compute cumulative token or cost statistics.
|
|
@@ -74,17 +76,18 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
|
|
|
74
76
|
- `runtimeSettings`: live `runtime/updateSetting` support for `defaultModel` and `defaultThinkingLevel`, plus `runtime/reload`.
|
|
75
77
|
- `auth`: available providers and authentication methods, private API-key storage, sanitized status, and logout. OpenAI and Anthropic OAuth are supported; Copilot OAuth is CLI-only, OpenRouter PKCE is not implemented, and xAI has no supported stable third-party flow.
|
|
76
78
|
- `memory`: opt-in structured memory support, interactive prompt injection only, JSON/JSONL local storage, and dedicated `memory/*` methods.
|
|
77
|
-
- `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns.
|
|
79
|
+
- `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns. Plugin commands may advertise validated JSON Schema arguments, shell-style text parsing, and structured results while legacy raw-string commands remain supported.
|
|
80
|
+
- `pluginActions`: namespaced typed actions discovered through `pluginActions/list` and synchronously invoked through `pluginActions/run`. They use object arguments and structured results, are not local TUI commands, and cannot make blocking UI requests.
|
|
78
81
|
- `skillCapture`: capture a reviewed personal `SKILL.md` from any saved session’s active branch through `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`.
|
|
79
82
|
- `projectSkillTrust`: explicitly unsupported over RPC. RPC clients cannot answer the interactive Allow/Deny/Review decision, so project skills remain skipped unless the global `skills.trust_project` override is enabled.
|
|
80
83
|
- `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. It does not support MCP resources, prompts, sampling, or Streamable HTTP.
|
|
81
84
|
- `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
|
|
82
|
-
- `extensionUi`: question
|
|
85
|
+
- `extensionUi`: structured question support plus plugin `select`, `confirm`, `input`, `progress`, and `notify` UI through `ui/request`, `ui/answerRequest`, `ui/progress`, and `ui/notification`; plugin footer updates use `ui/footer`. Editor, widget, custom-canvas, and raw terminal-input primitives remain explicitly unsupported.
|
|
83
86
|
- `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access. Vibe editor prompts are unsupported over RPC (`composer.editorPrompt.supported: false`) because RPC has no live integrated editor buffer.
|
|
84
87
|
- `security`: trusted-local behavior and optional per-turn tool approval. By default, RPC turns have no workspace mutation guard or tool approval, so shell commands and file changes can run. Clients can inspect file-tool guardrails through `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the command sandbox mode, enforcement backend, and filesystem and network capabilities; session pinning and one-time elevation are unsupported. See [Command sandboxing](sandboxing.md) for the boundary and its limits.
|
|
85
88
|
- `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
|
|
86
89
|
- `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
|
|
87
|
-
- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell`, its transient `?` shell assistant, `!command`, `/capture`, and PTY handoff require the local TUI. Model-requested `run_shell_command` tools remain bounded, captured, and noninteractive over RPC.
|
|
90
|
+
- `shell`: explicitly unsupported (`supported: false`, `nativeScripting: false`, `history: false`, `lineEditing: false`, `programmableCompletion: false`, `promptFormat: false`, `mailNotifications: false`, reason `interactiveTuiOnly`) because the persistent native kwsh session (including job control, traps, and hosted exec), `/shell`, its transient `?` shell assistant, `!command`, `/capture`, and PTY handoff require the local TUI and its persistent shell/terminal lifecycle. Model-requested `run_shell_command` tools remain bounded, captured, and noninteractive over RPC. They may invoke the standalone `kwsh` executable as an ordinary sandboxed external program; that does not expose a persistent native shell session or bypass tool permissions. Standalone history/`fc`, vi editing, programmable completion, `$PROMPT` rendering, and prompt-time mail notification have no RPC session API or terminal-input channel. Native `ulimit` is likewise part of the unsupported persistent scripting capability, not a host-limit API; limits set by standalone `kwsh` affect that process and its subsequent descendants, within the existing tool sandbox.
|
|
88
91
|
- `logging`: local redacted telemetry, its directory and enabled categories, `logging/stats` and `logging/tokenCsv`, bucketed `usageCsv` support, JSONL storage, and 10 MB rotation with manual retention. Logs contain redacted metadata only. Configuration uses the `logging` key and `KWARD_LOGGING` environment prefix.
|
|
89
92
|
|
|
90
93
|
### `shutdown`
|
|
@@ -294,7 +297,11 @@ Returns `{ "session": {}, "editorText": "...", "cancelled": false, "aborted": fa
|
|
|
294
297
|
|
|
295
298
|
## Plugin chat methods
|
|
296
299
|
|
|
297
|
-
Plugin chats are optional trusted-plugin capabilities, not Kward workspace
|
|
300
|
+
Plugin chats are optional trusted-plugin capabilities, not Kward workspace
|
|
301
|
+
sessions. When `initialize.capabilities.pluginChats.supported` is true, use
|
|
302
|
+
`pluginChats/list` to discover available types. Types using the versioned chat
|
|
303
|
+
contract also report `apiVersion` and `capabilities` with `attachments`,
|
|
304
|
+
`steering`, and `transcriptPaging`; legacy types omit those fields.
|
|
298
305
|
|
|
299
306
|
### `pluginChats/open`
|
|
300
307
|
|
|
@@ -330,7 +337,10 @@ Params:
|
|
|
330
337
|
- `input`;
|
|
331
338
|
- `attachments`: optional base64 image attachments using the same MIME and size limits as `turns/start`.
|
|
332
339
|
|
|
333
|
-
Queues a plugin-chat turn and returns `{ id, chatId, status, ... }`. Plugin chat
|
|
340
|
+
Queues a plugin-chat turn and returns `{ id, chatId, status, ... }`. Plugin chat
|
|
341
|
+
turns are serialized per chat and do not use workspace sessions, agents, or
|
|
342
|
+
model overrides. A versioned chat whose declared `attachments` capability omits
|
|
343
|
+
`image` rejects image attachments before invoking its driver.
|
|
334
344
|
|
|
335
345
|
### `pluginChats/turns/cancel`, `pluginChats/turns/status`, `pluginChats/turns/events`, `pluginChats/turns/list`, `pluginChats/turns/listActive`
|
|
336
346
|
|
|
@@ -350,7 +360,7 @@ Subscribed clients receive `pluginChat/event` notifications:
|
|
|
350
360
|
}
|
|
351
361
|
```
|
|
352
362
|
|
|
353
|
-
Known event types are `turnQueued`, `turnStarted`, `reasoningDelta`, `reasoningBoundary`, `assistantDelta`, `assistantMessage`, `toolCall`, `toolResult`, `answer`, `turnCancelRequested`, and `turnFinished`.
|
|
363
|
+
Known event types are `turnQueued`, `turnStarted`, `reasoningDelta`, `reasoningBoundary`, `assistantDelta`, `assistantMessage`, `toolCall`, `toolResult`, `answer`, `turnCancelRequested`, `turnSummary`, and `turnFinished`.
|
|
354
364
|
|
|
355
365
|
## Turn methods
|
|
356
366
|
|
|
@@ -439,15 +449,63 @@ Known event types:
|
|
|
439
449
|
- `toolCall`
|
|
440
450
|
- `toolUpdate`
|
|
441
451
|
- `toolResult`
|
|
452
|
+
- `pluginCommandResult`
|
|
442
453
|
- `answer`
|
|
443
454
|
- `turnCancelRequested`
|
|
444
455
|
- `error`
|
|
456
|
+
- `turnSummary`
|
|
445
457
|
- `turnFinished`
|
|
446
458
|
|
|
447
459
|
`reasoningBoundary` has an empty payload and marks the end of one reasoning summary message, allowing clients to render the next `reasoningDelta` as a separate block.
|
|
448
460
|
|
|
461
|
+
Codex commentary is user-facing assistant speech: it streams through `assistantDelta`, not `reasoningDelta`, and appears as `text` rather than `thinking` in normalized transcripts. Render it where it arrives, before subsequent tool events. Commentary remains in the raw message's `response_items` with `phase: "commentary"`; it is not folded into final-answer content.
|
|
462
|
+
|
|
449
463
|
Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFinished`. Exactly one terminal `turnFinished` is emitted per turn with `status` set to `completed`, `failed`, or `canceled`; failed turns include a sanitized `{ "message": "...", "code": "...", "fatal": false }` error payload.
|
|
450
464
|
|
|
465
|
+
`turnSummary` is emitted after the answer (or while finishing a failed/canceled
|
|
466
|
+
agent turn), before `turnFinished`. Its payload is `{ "summary": { ... } }`:
|
|
467
|
+
|
|
468
|
+
```json
|
|
469
|
+
{
|
|
470
|
+
"summary": {
|
|
471
|
+
"status": "completed",
|
|
472
|
+
"elapsedMs": 18400,
|
|
473
|
+
"modelRequests": 3,
|
|
474
|
+
"toolCalls": 4,
|
|
475
|
+
"usageStatus": "complete",
|
|
476
|
+
"usage": {
|
|
477
|
+
"input_tokens": 23600,
|
|
478
|
+
"output_tokens": 1200,
|
|
479
|
+
"total_tokens": 24800,
|
|
480
|
+
"estimated": false
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
The same `summary` is included in `turnFinished` and `turns/status`. Restored
|
|
487
|
+
normalized messages carry it as `turnSummary` on the final entry of the turn
|
|
488
|
+
(which can be a user or tool entry after interruption). Render it below that
|
|
489
|
+
entry; it is metadata, not an assistant message. `usageStatus` is `complete`,
|
|
490
|
+
`partial`, or `unavailable`; `usage` may be null and token fields are optional.
|
|
491
|
+
Optional `cache_read_tokens`, `cache_write_tokens`, and `reasoning_tokens`
|
|
492
|
+
fields preserve reported zeroes but are omitted when unavailable. Input counts
|
|
493
|
+
are normalized to include cached input and cache writes; reasoning is already
|
|
494
|
+
part of output. Do not add these breakdowns to `total_tokens` again.
|
|
495
|
+
`usage.partial_fields`, when present, lists fields whose sums cover only part
|
|
496
|
+
of the turn. A `complete` total can coexist with a partial cache or reasoning
|
|
497
|
+
breakdown. Compute cache-hit percentage as `100 * cache_read_tokens /
|
|
498
|
+
input_tokens` only when usage is complete, neither input nor cache reads is
|
|
499
|
+
partial, and input is positive. No new event or capability is required: these
|
|
500
|
+
fields travel in the existing structured summary regardless of display mode.
|
|
501
|
+
Usage covers main agent requests, excluding auxiliary
|
|
502
|
+
compaction/memory calls; see [turn statistics](session-management.md#Turn_statistics).
|
|
503
|
+
|
|
504
|
+
Initialization reports `transcript.turnSummaries` (including the configured
|
|
505
|
+
`defaultMode`) and `events.turnSummary`. Data is emitted regardless of the
|
|
506
|
+
presentation preference. Turns canceled before the agent starts and commands
|
|
507
|
+
or plugin chats that do not run an agent turn have no automatic summary.
|
|
508
|
+
|
|
451
509
|
`modelRetry` is emitted before Kward retries a transient model request failure. Its payload includes `provider`, `model`, `attempt`, `maxAttempts`, `delaySeconds`, and `error`.
|
|
452
510
|
|
|
453
511
|
`steeringApplied` is emitted after queued steering input has been appended to conversation context. Its payload includes `count`, the number of steering messages applied.
|
|
@@ -462,12 +520,29 @@ Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFi
|
|
|
462
520
|
|
|
463
521
|
`toolResult` additionally includes `result` with `content`, `isError`, optional unified `diff`, optional `changedFiles`, and `images`. Failed or declined tools set `isError: true`.
|
|
464
522
|
|
|
523
|
+
A typed plugin slash command emits `pluginCommandResult` with `command` and a
|
|
524
|
+
structured `result` containing optional `message` and `data` fields. It then
|
|
525
|
+
emits the usual text events when the command produced user-facing output.
|
|
526
|
+
|
|
465
527
|
Examples:
|
|
466
528
|
|
|
467
529
|
- `edit_file`: `toolName: "edit"`, `args: { "path": "...", "edits": [{ "oldText": "...", "newText": "..." }] }`.
|
|
468
530
|
- `write_file`: `toolName: "write"`, `args: { "path": "...", "content": "..." }`.
|
|
469
531
|
- `run_shell_command`: `toolName: "bash"`, `args: { "command": "...", "timeout": 30 }`.
|
|
470
532
|
|
|
533
|
+
<a id="generated-image-previews"></a>
|
|
534
|
+
## Generated image previews
|
|
535
|
+
|
|
536
|
+
`initialize` advertises `capabilities.generatedImages`. In a Codex turn, the model can call `generate_image` when the user asks for an image. Show indeterminate progress after its `toolCall` event, and clear progress at `toolResult` or when the turn ends. When a PNG is ready, `turn/event` emits `imageReady` with `id`, `toolCallId`, `filename`, `mimeType`, and `size` in its payload. Failed or cancelled generation does not produce a preview.
|
|
537
|
+
|
|
538
|
+
| Method | Parameters | Result |
|
|
539
|
+
| --- | --- | --- |
|
|
540
|
+
| `images/fetch` | `sessionId`, `imageId`, optional `offset` (default `0`) | Up to 256 KiB of image bytes, encoded as base64 in `data`, with `offset`, `nextOffset`, and image metadata. Follow `nextOffset` until it is `null`, decoding each chunk separately. An `offset` equal to `size` returns empty `data` and a `null` `nextOffset`; larger offsets are invalid. |
|
|
541
|
+
| `images/saveToProject` | `sessionId`, `imageId`, optional `directory` (default `.`) | `path` of the saved file. The directory must exist inside the originating project. Files are never overwritten. |
|
|
542
|
+
| `images/discard` | `sessionId`, `imageId` | `{ "discarded": true }`. Saved copies are not affected. |
|
|
543
|
+
|
|
544
|
+
For **Save to Downloads**, fetch the image and write it to the **client's** Downloads folder. Keep a preview available after a failed save. Explicitly discard it when the user dismisses it; closing its session also removes it. Preview IDs are scoped to the live session and do not survive a server restart. Image bytes are not included in event replay or transcript history.
|
|
545
|
+
|
|
471
546
|
## Tool approval bridge
|
|
472
547
|
|
|
473
548
|
When `turns/start` is called with `options.approvalMode: "ask"`, Kward emits `tool/approvalRequested` before executing each tool.
|
|
@@ -490,11 +565,11 @@ Params:
|
|
|
490
565
|
|
|
491
566
|
Denied tools are returned to the model as error-like tool results instead of executing the local operation.
|
|
492
567
|
|
|
493
|
-
## UI
|
|
568
|
+
## Structured UI bridge
|
|
494
569
|
|
|
495
|
-
Kward supports
|
|
570
|
+
Kward supports model questions and frontend-neutral plugin UI over RPC. The `extensionUi` capability reports the notification and answer method for each operation. `question` continues to use `ui/question` and `ui/answerQuestion`; plugin `select`, `confirm`, and `input` requests use `ui/request` and `ui/answerRequest`. Non-blocking plugin updates use `ui/progress` and `ui/notification`, while plugin footers use `ui/footer`. Editor, widget, custom-canvas, and raw terminal-input primitives remain explicitly unsupported.
|
|
496
571
|
|
|
497
|
-
Question requests are validated before notification. Kward accepts 1-4 questions, each with 2-4 options, and rejects unsupported `multiSelect` or option `preview` requests.
|
|
572
|
+
Question requests are validated before notification. Kward accepts 1-4 questions, each with 2-4 options, and rejects unsupported `multiSelect` or option `preview` requests. Plugin selections accept at most 100 options, and plugin text input is bounded to 16,384 bytes.
|
|
498
573
|
|
|
499
574
|
When the model calls `ask_user_question`, RPC emits a `ui/question` notification:
|
|
500
575
|
|
|
@@ -506,16 +581,37 @@ When the model calls `ask_user_question`, RPC emits a `ui/question` notification
|
|
|
506
581
|
}
|
|
507
582
|
```
|
|
508
583
|
|
|
509
|
-
When
|
|
584
|
+
When loaded Kward plugins contribute footer status, RPC emits `ui/footer` after
|
|
585
|
+
session creation/resume/clone, after each completed turn, and when the status
|
|
586
|
+
changes during its periodic refresh:
|
|
510
587
|
|
|
511
588
|
```json
|
|
512
589
|
{
|
|
513
590
|
"sessionId": "...",
|
|
514
|
-
"text": "
|
|
591
|
+
"text": "Bridge · 2 messages",
|
|
592
|
+
"segments": [
|
|
593
|
+
{
|
|
594
|
+
"id": "com.example.session/session",
|
|
595
|
+
"text": "Bridge",
|
|
596
|
+
"tooltip": "Current Kward session",
|
|
597
|
+
"priority": "high",
|
|
598
|
+
"order": 10
|
|
599
|
+
},
|
|
600
|
+
{
|
|
601
|
+
"id": "com.example.session/messages",
|
|
602
|
+
"text": "2 messages",
|
|
603
|
+
"priority": "low",
|
|
604
|
+
"order": 20
|
|
605
|
+
}
|
|
606
|
+
]
|
|
515
607
|
}
|
|
516
608
|
```
|
|
517
609
|
|
|
518
|
-
|
|
610
|
+
`text` is the combined fallback for clients that do not render segments.
|
|
611
|
+
`segments` remains display-ordered and lets richer clients show tooltips or
|
|
612
|
+
apply their own width policy. An empty `text` with an empty `segments` array
|
|
613
|
+
clears the client footer. The `extensionUi.footer` capability advertises
|
|
614
|
+
segment, tooltip, and priority support.
|
|
519
615
|
|
|
520
616
|
The UI must respond with `ui/answerQuestion`:
|
|
521
617
|
|
|
@@ -525,6 +621,40 @@ Params:
|
|
|
525
621
|
- `questionRequestId`
|
|
526
622
|
- `answers`: answer array returned to the tool.
|
|
527
623
|
|
|
624
|
+
When a plugin calls `ctx.ui.select`, `ctx.ui.confirm`, or `ctx.ui.input` during an asynchronous plugin-command turn or plugin tool call, RPC emits:
|
|
625
|
+
|
|
626
|
+
```json
|
|
627
|
+
{
|
|
628
|
+
"method": "ui/request",
|
|
629
|
+
"params": {
|
|
630
|
+
"sessionId": "...",
|
|
631
|
+
"requestId": "...",
|
|
632
|
+
"kind": "select",
|
|
633
|
+
"payload": {
|
|
634
|
+
"title": "Environment",
|
|
635
|
+
"message": "Choose a target",
|
|
636
|
+
"options": [
|
|
637
|
+
{ "label": "Staging", "value": "staging", "description": "Deploy for testing." }
|
|
638
|
+
]
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
}
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
Answer it with `ui/answerRequest`:
|
|
645
|
+
|
|
646
|
+
```json
|
|
647
|
+
{
|
|
648
|
+
"sessionId": "...",
|
|
649
|
+
"requestId": "...",
|
|
650
|
+
"value": "staging"
|
|
651
|
+
}
|
|
652
|
+
```
|
|
653
|
+
|
|
654
|
+
For `confirm`, `value` must be a boolean. For `input`, it is a string or `null` when cancelled. For `select`, it is one of the advertised option values or `null`. Submit interactive plugin commands through `turns/start`; synchronous `commands/run` deliberately reports blocking plugin UI as unavailable so the RPC reader never waits for an answer it cannot read.
|
|
655
|
+
|
|
656
|
+
`ctx.ui.progress` emits `ui/progress` with `sessionId`, stable `id`, `message`, optional `percent`, and `done`. `ctx.ui.notify` emits `ui/notification` with `sessionId`, `message`, and `level` (`info`, `success`, `warning`, or `error`). These notifications do not require answers.
|
|
657
|
+
|
|
528
658
|
## Runtime methods
|
|
529
659
|
|
|
530
660
|
### `runtime/state`
|
|
@@ -559,7 +689,11 @@ Params:
|
|
|
559
689
|
|
|
560
690
|
- `sessionId`: active RPC session ID.
|
|
561
691
|
|
|
562
|
-
|
|
692
|
+
Reloads configuration, clears memoized provider catalogs, refreshes active sessions' runtime/tool state, and reloads plugins. Returns `{ "ok": true, "message": "Resources reloaded." }`. This is broader than model discovery: existing session runtime selections are reapplied from the process defaults.
|
|
693
|
+
|
|
694
|
+
After another Kward process changes configuration or a shared catalog cache, call `runtime/reload` with an active `sessionId`, then `models/list` (and `models/current` if needed). Environment overrides and explicit launch-time model overrides still take precedence. Disk-backed catalogs are reread; Copilot and Local rediscover lazily because their catalogs are process-local. Use `models/refresh` afterward only if you also want fresh provider discovery.
|
|
695
|
+
|
|
696
|
+
Ordinary list reads and model refresh do not reload plugins or configuration. There is no background file watching, cross-process polling, or `models/changed` notification; clients must request adoption explicitly.
|
|
563
697
|
|
|
564
698
|
## Logging methods
|
|
565
699
|
|
|
@@ -696,15 +830,63 @@ Returns `{ "memories": [] }`.
|
|
|
696
830
|
|
|
697
831
|
### `models/list`
|
|
698
832
|
|
|
699
|
-
Returns known
|
|
833
|
+
Returns `{ "models": [...] }`, the complete known catalog from configured providers, including configured and curated fallbacks. This is not a guarantee that every entry is currently callable or authorized. Listing uses existing cached/curated choices, with lazy discovery for Copilot/Local when needed; it does not force live discovery on every request.
|
|
834
|
+
|
|
835
|
+
`capabilities.models.fields` declares `provider`, `id`, `name`, `reasoning`, `reasoningEffort`, `contextWindow`, `current`, `defaultSelectable`, `supportedParameters`, and `source`:
|
|
836
|
+
|
|
837
|
+
- `provider` and `id` are the identity pair to send unchanged to `models/set`. Preserve slash-containing IDs. Direct `OpenAI` and subscription `Codex` are distinct providers.
|
|
838
|
+
- `current` is relative to the process default, not an individual conversation. `models.scopedModels` remains `false`; use session runtime state for a conversation's selection.
|
|
839
|
+
- `defaultSelectable` is always a boolean. Use it for the default picker instead of duplicating Kward's capability rules. The current model and models with unknown/empty capabilities remain eligible. Known entries without generation/tool/function capabilities have `false` but remain in this response. **Show all models** should display the full array; manual entry remains supported through `models/set`.
|
|
840
|
+
- `supportedParameters` is optional provider capability metadata (an array of strings); absent or empty means unknown, not unsupported.
|
|
841
|
+
- `source` is optional provenance such as `cached`, `curated`, `live`, or `manual`; it is not an authorization or freshness guarantee.
|
|
842
|
+
|
|
843
|
+
The terminal picker uses the same eligibility rule, but relative to its active conversation. A client with a different conversation selection should keep that selection visible alongside the default-eligible list, without reimplementing capability filtering.
|
|
844
|
+
|
|
845
|
+
For example, a known non-generation entry can look like:
|
|
846
|
+
|
|
847
|
+
```json
|
|
848
|
+
{
|
|
849
|
+
"provider": "Google Gemini",
|
|
850
|
+
"id": "embedding-model",
|
|
851
|
+
"name": "embedding-model",
|
|
852
|
+
"reasoning": false,
|
|
853
|
+
"contextWindow": 128000,
|
|
854
|
+
"current": false,
|
|
855
|
+
"defaultSelectable": false,
|
|
856
|
+
"supportedParameters": ["embedContent"],
|
|
857
|
+
"source": "cached"
|
|
858
|
+
}
|
|
859
|
+
```
|
|
700
860
|
|
|
701
861
|
### `models/refresh`
|
|
702
862
|
|
|
703
863
|
Params:
|
|
704
864
|
|
|
705
|
-
- `provider`: optional configured provider name. Defaults to the active provider.
|
|
865
|
+
- `provider`: optional configured provider name or catalog ID. Defaults to the active provider.
|
|
866
|
+
|
|
867
|
+
Refreshes only the targeted provider through its discovery implementation, replacing its in-memory choices on success. Does not reload configuration or plugins, or change any conversation's selected model.
|
|
868
|
+
|
|
869
|
+
The additive response schema is:
|
|
870
|
+
|
|
871
|
+
```json
|
|
872
|
+
{
|
|
873
|
+
"models": [],
|
|
874
|
+
"refresh": {
|
|
875
|
+
"provider": "OpenRouter",
|
|
876
|
+
"status": "success",
|
|
877
|
+
"fallbackUsed": false
|
|
878
|
+
}
|
|
879
|
+
}
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
- `models`: the complete normalized catalog, with the same shape as `models/list`, not just the targeted provider.
|
|
883
|
+
- `refresh.provider`: canonical display name of the targeted provider (for example `OpenAI`, `Codex`, or `Google Gemini`). An omitted request provider targets the process's active provider.
|
|
884
|
+
- `refresh.status`: `success` for completed discovery (including a valid empty catalog), `unsupported` when no discovery implementation is available, or `failed` when discovery failed and existing choices were retained.
|
|
885
|
+
- `refresh.fallbackUsed`: `false` on success; `true` for `unsupported` and `failed`, when known/configured/curated choices are used instead of a fresh discovery result. A successful list can still include curated/configured entries.
|
|
886
|
+
|
|
887
|
+
No raw provider errors, credentials, credential hashes, or authorization headers are included. Discovery failure is an ordinary result with `status: "failed"`, not an RPC error. Providers without discovery retain configured or curated choices.
|
|
706
888
|
|
|
707
|
-
|
|
889
|
+
Negotiate this via `capabilities.models.refresh.resultFields` (`["models", "refresh"]`), `metadataFields` (`["provider", "status", "fallbackUsed"]`), and `statuses` (`["success", "unsupported", "failed"]`). Older clients can continue reading only `models`; the protocol version is unchanged.
|
|
708
890
|
|
|
709
891
|
### `models/current`
|
|
710
892
|
|
|
@@ -717,7 +899,13 @@ Params:
|
|
|
717
899
|
- `model`: model ID string.
|
|
718
900
|
- `provider`: optional provider name or catalog ID; defaults to the active provider.
|
|
719
901
|
|
|
720
|
-
Updates the config-backed provider model and returns the current model payload.
|
|
902
|
+
Updates the config-backed provider model and returns the current model payload. Send the `provider`/`id` pair from the list as `provider`/`model`, without splitting the ID:
|
|
903
|
+
|
|
904
|
+
```json
|
|
905
|
+
{"jsonrpc":"2.0","id":3,"method":"models/set","params":{"provider":"OpenRouter","model":"vendor/model/variant"}}
|
|
906
|
+
```
|
|
907
|
+
|
|
908
|
+
`provider: "OpenAI"` (or catalog ID `openai`) selects the direct API; `provider: "Codex"` selects the subscription backend. The legacy `openai` value in existing configuration files still means Codex; RPC catalog IDs are not that legacy configuration format.
|
|
721
909
|
|
|
722
910
|
### `reasoning/set`
|
|
723
911
|
|
|
@@ -737,11 +925,11 @@ Params:
|
|
|
737
925
|
|
|
738
926
|
Returns current tool schemas. The existing model-facing schema shape is preserved: each entry still has `type: "function"` and `function` with `name`, `description`, and `parameters`. Entries also include additive metadata for UI discovery:
|
|
739
927
|
|
|
740
|
-
- `metadata.source`: one of practical source labels such as `builtin`, `mcp`, `web`, `skill`, `ui`, or `unknown`.
|
|
928
|
+
- `metadata.source`: one of practical source labels such as `builtin`, `plugin`, `mcp`, `web`, `skill`, `ui`, or `unknown`.
|
|
741
929
|
- `metadata.displayName`: human-readable tool label.
|
|
742
930
|
- MCP tools also include `metadata.serverName` and `metadata.remoteName`. The callable name remains sanitized with a double underscore, for example `github__search_issues`, while `displayName` is `github.search_issues`.
|
|
743
931
|
|
|
744
|
-
Clients that only read `tools[].function` remain compatible.
|
|
932
|
+
Clients that only read `tools[].function` remain compatible. Model-callable tools registered by trusted local plugins appear here with `metadata.source: "plugin"` and follow the same per-session execution-profile filtering as built-in tools.
|
|
745
933
|
|
|
746
934
|
### `mcp/status`
|
|
747
935
|
|
|
@@ -766,7 +954,74 @@ Params:
|
|
|
766
954
|
|
|
767
955
|
- `sessionId`: active RPC session ID.
|
|
768
956
|
|
|
769
|
-
Returns frontend-neutral slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
|
|
957
|
+
Returns frontend-neutral slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Typed plugin entries additionally include `typed: true`, their strict object `schema`, declared `positionals`, and `pluginId` when the plugin has stable identity. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
|
|
958
|
+
|
|
959
|
+
### `commands/run`
|
|
960
|
+
|
|
961
|
+
Params:
|
|
962
|
+
|
|
963
|
+
- `sessionId`: active RPC session ID.
|
|
964
|
+
- `name`: plugin command name, with or without the leading slash.
|
|
965
|
+
- `arguments`: shell-style text or, for typed commands, an object matching the advertised schema.
|
|
966
|
+
|
|
967
|
+
Legacy plugin commands return their existing string-or-null `result`. Typed
|
|
968
|
+
commands return `result` as an object containing optional user-facing `message`
|
|
969
|
+
and JSON-compatible `data`; text emitted through `ctx.say` remains in `output`.
|
|
970
|
+
Blocking structured UI requests are unavailable on this synchronous path. Use a
|
|
971
|
+
slash-command `turns/start` call when the command needs interactive UI.
|
|
972
|
+
|
|
973
|
+
Plugin commands can also stage a model response with `ctx.request_turn(system: text)`.
|
|
974
|
+
Submit these through `turns/start`, for example:
|
|
975
|
+
|
|
976
|
+
```json
|
|
977
|
+
{"sessionId":"session-id","input":"/iddqd Answer in French and explain the current design."}
|
|
978
|
+
```
|
|
979
|
+
|
|
980
|
+
The same turn emits the normal model, tool, answer, error, and completion events.
|
|
981
|
+
The host retains cancellation, execution-profile restrictions, and tool approvals.
|
|
982
|
+
The instructions supplement the system prompt for this turn only; they are not
|
|
983
|
+
submitted as user text and are not reactivated by restoring the session.
|
|
984
|
+
`commands/run` and `pluginActions/run` reject model-turn requests. Discover this
|
|
985
|
+
contract under `initialize.capabilities.commands.modelTurns`, including the
|
|
986
|
+
65,536-byte limit, `scope: "turn"`, and `synchronous: false`.
|
|
987
|
+
`inputRole: "system"` describes Kward's internal instruction role;
|
|
988
|
+
`codexInputRole: "developer"` reports the Codex subscription backend's supported
|
|
989
|
+
wire role. Codex receives the command as a new ordered developer message, while
|
|
990
|
+
direct OpenAI Responses receives an ordered system message. Base instructions
|
|
991
|
+
stay separate from these turn-scoped input messages.
|
|
992
|
+
|
|
993
|
+
The invocation is saved as a user-visible history entry with `display_content`
|
|
994
|
+
and `plugin_system_turn` metadata (command, plugin ID, instruction text, request ID,
|
|
995
|
+
and scope). Later model requests omit these history entries; compaction uses an
|
|
996
|
+
informational placeholder, not the expired instructions. Anthropic and Gemini
|
|
997
|
+
use separate system fields rather than ordered system messages and require
|
|
998
|
+
existing dialogue; a system-only request in an empty session fails explicitly
|
|
999
|
+
rather than inserting a synthetic user prompt.
|
|
1000
|
+
|
|
1001
|
+
### `pluginActions/list`
|
|
1002
|
+
|
|
1003
|
+
Params:
|
|
1004
|
+
|
|
1005
|
+
- `sessionId`: active RPC session ID.
|
|
1006
|
+
|
|
1007
|
+
Returns identified-plugin actions with `id`, local `name`, `pluginId`,
|
|
1008
|
+
`description`, and strict object `schema`. Action IDs use
|
|
1009
|
+
`<plugin-id>/<action-name>`.
|
|
1010
|
+
|
|
1011
|
+
### `pluginActions/run`
|
|
1012
|
+
|
|
1013
|
+
Params:
|
|
1014
|
+
|
|
1015
|
+
- `sessionId`: active RPC session ID.
|
|
1016
|
+
- `id`: complete namespaced action ID.
|
|
1017
|
+
- `arguments`: object matching the action schema; defaults to an empty object.
|
|
1018
|
+
|
|
1019
|
+
Returns `action`, `output`, and a structured `result` with optional `message` and
|
|
1020
|
+
`data`. Actions run synchronously and therefore expose notifications and progress
|
|
1021
|
+
but not blocking questions, selections, confirmations, or input. They are
|
|
1022
|
+
rejected when the session execution profile disables plugin commands. Actions
|
|
1023
|
+
are intentionally not exposed in local slash completion; a plugin should also
|
|
1024
|
+
register a typed command when it needs a human-facing TUI entry point.
|
|
770
1025
|
|
|
771
1026
|
### `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`
|
|
772
1027
|
|
|
@@ -884,4 +1139,5 @@ Returns login status for a login ID.
|
|
|
884
1139
|
- RPC is intended for a trusted local UI and can read/write files, run shell commands, update secrets, and use OAuth.
|
|
885
1140
|
- Workspace roots may be any existing local directory accessible to the process.
|
|
886
1141
|
- Tool execution matches current CLI behavior; mutating tools are not approval-gated by RPC.
|
|
1142
|
+
- `commands/run` and `pluginActions/run` execute trusted local plugin code. Action schemas validate data shape but are not an authorization boundary; use execution profiles to disable plugin operations for restricted sessions.
|
|
887
1143
|
- Responses and diagnostics redact secret-looking fields, but clients should still avoid logging full protocol traffic unless necessary.
|
data/doc/sandboxing.md
CHANGED
|
@@ -67,9 +67,12 @@ after changing the mode.
|
|
|
67
67
|
|
|
68
68
|
An active worktree-backed tab uses a strict `workspace_write` policy for its
|
|
69
69
|
model-requested command workers, regardless of the global `sandbox.mode` or
|
|
70
|
-
`tools.workspace_guardrails` settings. The writable root is exactly the
|
|
71
|
-
worktree and no configured additional writable roots are carried into the
|
|
72
|
-
|
|
70
|
+
`tools.workspace_guardrails` settings. The default writable root is exactly the
|
|
71
|
+
linked worktree and no configured additional writable roots are carried into the
|
|
72
|
+
tab. When a workspace tool explicitly selects the verified `origin` target,
|
|
73
|
+
Kward uses a separate strict command worker whose writable root is exactly that
|
|
74
|
+
original worktree. Arbitrary target paths are not accepted. The configured
|
|
75
|
+
child-network setting is preserved.
|
|
73
76
|
|
|
74
77
|
If the current platform cannot provide filesystem enforcement, Kward refuses to
|
|
75
78
|
activate the worktree instead of falling back to an unrestricted command
|
|
@@ -82,8 +85,11 @@ This does not contain the user-directed `/shell`, `!command`, `/capture`, or
|
|
|
82
85
|
model-requested shell commands still cannot write Git metadata. Active worktree tabs additionally
|
|
83
86
|
expose a narrow `git_commit` tool for explicit agent-requested commits; it runs
|
|
84
87
|
through the trusted host-side Git workflow rather than widening the shell
|
|
85
|
-
sandbox. The
|
|
86
|
-
|
|
88
|
+
sandbox. The verified original worktree is available as `target: "origin"` on
|
|
89
|
+
core workspace tools so an agent can inspect and resolve merge conflicts without
|
|
90
|
+
switching tabs. Selecting that target does not add an approval layer; the normal
|
|
91
|
+
configured tool-permission policy applies equally to both worktrees. The
|
|
92
|
+
interactive `/git` flow remains available for manual review and commit.
|
|
87
93
|
|
|
88
94
|
## Platform support
|
|
89
95
|
|
data/doc/security.md
CHANGED
|
@@ -87,7 +87,7 @@ See [Lifecycle hooks](lifecycle-hooks.md) for policy examples and [RPC protocol]
|
|
|
87
87
|
|
|
88
88
|
## Opt-in permission policy
|
|
89
89
|
|
|
90
|
-
`permissions.enabled` is off by default. When enabled, Kward can allow, ask, or deny model-requested file changes, shell commands, web tools, and
|
|
90
|
+
`permissions.enabled` is off by default. When enabled, Kward can allow, ask, or deny model-requested file changes, shell commands, web tools, MCP tools, and plugin tools before execution. The interactive CLI uses an approval overlay; an unavailable approval bridge fails closed. The policy is not a sandbox: after Kward permits a shell command, it still runs with the permissions of your user account. See [Permissions](permissions.md) for workflows, modes, rules, and limits.
|
|
91
91
|
|
|
92
92
|
## Know what you are trusting
|
|
93
93
|
|
|
@@ -113,6 +113,11 @@ They can read files and environment variables, write files, run commands, and
|
|
|
113
113
|
make network requests. Kward intentionally does not load plugins from a
|
|
114
114
|
workspace directory.
|
|
115
115
|
|
|
116
|
+
Identified-plugin configuration and state remain local to the active config
|
|
117
|
+
directory. RPC capability reports include only plugin IDs and versions, never
|
|
118
|
+
plugin configuration or secret values. Treat `host.logger` output as
|
|
119
|
+
user-visible diagnostics and never write credentials to it.
|
|
120
|
+
|
|
116
121
|
### MCP servers
|
|
117
122
|
|
|
118
123
|
Configured MCP servers are local child processes. Their tools can expose application state such as browser pages, console messages, network traffic, or screenshots. Kward currently supports local stdio servers, but local transport does not make an untrusted server safe.
|
|
@@ -168,6 +173,7 @@ Kward keeps user data under `~/.kward` by default, or mostly beside `KWARD_CONFI
|
|
|
168
173
|
| Memory | `~/.kward/memory/` | Off by default; directory `0700` and files `0600`. |
|
|
169
174
|
| Telemetry logs | `~/.kward/logs/` | Off by default; redacted metadata, not intentional prompt or file-content logging. |
|
|
170
175
|
| Plugins | `~/.kward/plugins/` | Trusted Ruby code, not private data storage. |
|
|
176
|
+
| Plugin state | `~/.kward/plugin_state/` | Namespaced by stable plugin ID; state files use mode `0600`. |
|
|
171
177
|
| Hook audit log and trust records | `~/.kward/logs/`, `~/.kward/trusted_workspace_hooks.json` | Audit records use redacted metadata rather than raw event values. |
|
|
172
178
|
|
|
173
179
|
Private file modes help on normal Unix-like systems but do not protect data from your own account, privileged users, backups, malware, or a compromised machine. Session exports are written to the path you choose and should be protected separately.
|
data/doc/session-management.md
CHANGED
|
@@ -4,6 +4,41 @@ Kward saves each interactive chat as a session, so you can close the terminal an
|
|
|
4
4
|
|
|
5
5
|
Rewinding and forking are a kind of **context time travel**: go back to an earlier prompt, try another path, and keep both versions instead of losing the original work.
|
|
6
6
|
|
|
7
|
+
## Turn statistics
|
|
8
|
+
|
|
9
|
+
Each normal agent turn ends with a quiet summary below the answer:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
Completed · 18.4s · 24.8k tokens · 4 tool calls
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Failed and cancelled turns also retain a summary when the agent turn started.
|
|
16
|
+
Existing inline tool timings stay where they are; token counts are not assigned
|
|
17
|
+
to individual tools.
|
|
18
|
+
|
|
19
|
+
- **Elapsed time** covers the agent turn, including its hooks, compaction, model
|
|
20
|
+
requests, tool execution, retries, and approval waits. It excludes time queued
|
|
21
|
+
before the agent starts and post-turn memory work.
|
|
22
|
+
- **Tokens** sum provider-reported usage across the main agent requests, not
|
|
23
|
+
just the final answer. Repeated context counts again on each request. This is
|
|
24
|
+
usage, not context-window occupancy or a monetary cost estimate.
|
|
25
|
+
- **Auxiliary calls** for compaction and memory are excluded from token totals.
|
|
26
|
+
Model-request counts refer to main-loop provider invocations, not individual
|
|
27
|
+
HTTP retry attempts.
|
|
28
|
+
- **Unavailable usage** reads `tokens unavailable`, never a fabricated zero.
|
|
29
|
+
Missing usage from some requests, failed requests without usage, or HTTP
|
|
30
|
+
retries make reported totals `partial`. An estimated total has a `~` prefix.
|
|
31
|
+
|
|
32
|
+
Choose `compact`, `detailed`, or `off` in
|
|
33
|
+
[`transcript.turn_stats`](configuration.md#Transcript_turn_statistics).
|
|
34
|
+
Detailed mode adds model-request counts, input/output totals, and reported
|
|
35
|
+
cached-input, cache-write, and reasoning-token breakdowns. The cache-hit rate
|
|
36
|
+
uses aggregated cached input divided by aggregated input; incomplete breakdowns
|
|
37
|
+
are marked partial and do not produce a cache-hit percentage. Summaries
|
|
38
|
+
survive session restoration and branching, follow their transcript entries into
|
|
39
|
+
exports, and are not sent back to the model. Older sessions without recorded
|
|
40
|
+
summaries remain unchanged; historical timings are not guessed.
|
|
41
|
+
|
|
7
42
|
## Where sessions live
|
|
8
43
|
|
|
9
44
|
Interactive sessions are saved under:
|
|
@@ -14,7 +49,7 @@ Interactive sessions are saved under:
|
|
|
14
49
|
|
|
15
50
|
Sessions are scoped to the workspace. If you run Kward in two different projects, each project has its own recent sessions.
|
|
16
51
|
|
|
17
|
-
One-shot prompts such as `kward "Explain this project"` do not use session history. Start interactive Kward when you want ongoing context:
|
|
52
|
+
One-shot prompts such as `kward prompt "Explain this project"` do not use session history. Start interactive Kward when you want ongoing context:
|
|
18
53
|
|
|
19
54
|
```bash
|
|
20
55
|
cd ~/code/project
|
|
@@ -25,13 +60,13 @@ To automatically resume the last active session for the current workspace on sta
|
|
|
25
60
|
|
|
26
61
|
## A normal session workflow
|
|
27
62
|
|
|
28
|
-
Start a chat and give
|
|
63
|
+
Start a chat and give the current session and tab a useful name:
|
|
29
64
|
|
|
30
65
|
```text
|
|
31
|
-
/
|
|
66
|
+
/name oauth cleanup
|
|
32
67
|
```
|
|
33
68
|
|
|
34
|
-
`/
|
|
69
|
+
`/name` requires a name and updates both the active session and its tab label. It can also be used while the active tab's agent is running; it is unavailable in plugin tabs. Use `/rename` when you only want to rename the session. Use `/session name` without an argument to clear the current session name.
|
|
35
70
|
|
|
36
71
|
Work normally:
|
|
37
72
|
|
|
@@ -227,7 +262,8 @@ This is useful when you want to confirm which session you are in or check whethe
|
|
|
227
262
|
| Need | Use |
|
|
228
263
|
| --- | --- |
|
|
229
264
|
| Continue earlier work | `/session` or `/resume` |
|
|
230
|
-
| Give the current session a better name | `/
|
|
265
|
+
| Give the current session and tab a better name | `/name <name>` |
|
|
266
|
+
| Give only the current session a better name | `/rename <name>` |
|
|
231
267
|
| Clear the current session name | `/session name` |
|
|
232
268
|
| Keep the current state but try another future | `/clone` |
|
|
233
269
|
| Start a separate session from before an earlier prompt | `/fork` |
|