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.
Files changed (245) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +164 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +5 -5
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +24 -1
  8. data/doc/api.md +20 -2
  9. data/doc/composer.md +5 -4
  10. data/doc/configuration.md +86 -14
  11. data/doc/extensibility.md +4 -1
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +4 -2
  14. data/doc/memory.md +1 -1
  15. data/doc/pan.md +6 -0
  16. data/doc/permissions.md +4 -4
  17. data/doc/plugins.md +504 -20
  18. data/doc/providers.md +10 -4
  19. data/doc/rpc.md +279 -23
  20. data/doc/sandboxing.md +11 -5
  21. data/doc/security.md +7 -1
  22. data/doc/session-management.md +41 -5
  23. data/doc/shell.md +643 -27
  24. data/doc/tabs.md +8 -3
  25. data/doc/transports.md +15 -0
  26. data/doc/troubleshooting.md +1 -1
  27. data/doc/usage.md +25 -12
  28. data/doc/workspace-tools.md +9 -0
  29. data/examples/plugins/openrouter_proxy/README.md +103 -0
  30. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  31. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  32. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  33. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  34. data/examples/plugins/space_invaders.rb +1 -2
  35. data/examples/plugins/stardate_footer.rb +2 -2
  36. data/examples/plugins/telegram/plugin.rb +1 -1
  37. data/exe/kward +2 -2
  38. data/exe/kwsh +7 -0
  39. data/kward.gemspec +3 -1
  40. data/lib/kward/agent.rb +66 -19
  41. data/lib/kward/cli/commands.rb +41 -11
  42. data/lib/kward/cli/compaction.rb +9 -3
  43. data/lib/kward/cli/interactive_turn.rb +10 -0
  44. data/lib/kward/cli/plugins.rb +85 -12
  45. data/lib/kward/cli/prompt_interface.rb +29 -6
  46. data/lib/kward/cli/rendering.rb +24 -28
  47. data/lib/kward/cli/runtime_helpers.rb +168 -56
  48. data/lib/kward/cli/sessions.rb +9 -5
  49. data/lib/kward/cli/settings/menus.rb +745 -0
  50. data/lib/kward/cli/settings/model.rb +316 -0
  51. data/lib/kward/cli/settings.rb +6 -1055
  52. data/lib/kward/cli/slash_commands.rb +45 -4
  53. data/lib/kward/cli/tabs.rb +257 -44
  54. data/lib/kward/cli/tool_summaries.rb +2 -0
  55. data/lib/kward/{cli_transcript_formatter.rb → cli/transcript_formatter.rb} +6 -13
  56. data/lib/kward/cli/worktrees.rb +66 -2
  57. data/lib/kward/cli.rb +82 -31
  58. data/lib/kward/compactor.rb +18 -7
  59. data/lib/kward/config/core.rb +400 -0
  60. data/lib/kward/config/extensions.rb +99 -0
  61. data/lib/kward/config/paths.rb +11 -0
  62. data/lib/kward/config/prompts.rb +313 -0
  63. data/lib/kward/config/settings.rb +257 -0
  64. data/lib/kward/config_files.rb +14 -1008
  65. data/lib/kward/conversation.rb +41 -2
  66. data/lib/kward/entrypoint.rb +14 -0
  67. data/lib/kward/events.rb +2 -0
  68. data/lib/kward/generated_images.rb +237 -0
  69. data/lib/kward/image_attachments.rb +1 -1
  70. data/lib/kward/model/catalog.rb +6 -3
  71. data/lib/kward/model/client.rb +107 -38
  72. data/lib/kward/model/codex_images.rb +83 -0
  73. data/lib/kward/model/copilot_models.rb +10 -6
  74. data/lib/kward/model/model_info.rb +42 -7
  75. data/lib/kward/{openrouter_model_cache.rb → model/openrouter_model_cache.rb} +7 -5
  76. data/lib/kward/model/payloads.rb +18 -8
  77. data/lib/kward/model/sources.rb +3 -1
  78. data/lib/kward/model/stream_parser.rb +4 -7
  79. data/lib/kward/model/typesafe_client.rb +78 -0
  80. data/lib/kward/pan/index.html.erb +8 -1
  81. data/lib/kward/pan/server.rb +23 -8
  82. data/lib/kward/permissions/policy.rb +6 -2
  83. data/lib/kward/plugin_registry.rb +2 -659
  84. data/lib/kward/plugins/actions.rb +453 -0
  85. data/lib/kward/plugins/chat_contract.rb +121 -0
  86. data/lib/kward/{plugin_chat_runtime.rb → plugins/chat_runtime.rb} +62 -18
  87. data/lib/kward/plugins/codex_responses.rb +73 -0
  88. data/lib/kward/plugins/host.rb +248 -0
  89. data/lib/kward/plugins/http_server.rb +83 -0
  90. data/lib/kward/plugins/registry.rb +1229 -0
  91. data/lib/kward/plugins/resources.rb +206 -0
  92. data/lib/kward/plugins/turn_request.rb +36 -0
  93. data/lib/kward/plugins/ui.rb +219 -0
  94. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  95. data/lib/kward/prompt_interface/composer_renderer.rb +160 -73
  96. data/lib/kward/prompt_interface/composer_state.rb +1 -1
  97. data/lib/kward/prompt_interface/editor/controller.rb +2 -2
  98. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  99. data/lib/kward/prompt_interface/editor/runner.rb +1 -1
  100. data/lib/kward/prompt_interface/editor/state.rb +1 -1
  101. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  102. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  103. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  104. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  105. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  106. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  107. data/lib/kward/prompt_interface/layout.rb +11 -1
  108. data/lib/kward/prompt_interface/overlay_renderer.rb +26 -9
  109. data/lib/kward/prompt_interface/plugin_ui_requests.rb +82 -0
  110. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  111. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  112. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  113. data/lib/kward/prompt_interface/runtime_state.rb +37 -10
  114. data/lib/kward/prompt_interface/screen.rb +30 -20
  115. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  116. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  117. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  118. data/lib/kward/prompt_interface.rb +149 -30
  119. data/lib/kward/prompts/commands.rb +2 -1
  120. data/lib/kward/prompts.rb +7 -1
  121. data/lib/kward/{adaptive_pty_output_sink.rb → pty/adaptive_output_sink.rb} +39 -5
  122. data/lib/kward/{interactive_pty_runner.rb → pty/interactive_runner.rb} +22 -30
  123. data/lib/kward/{local_command_runner.rb → pty/local_command_runner.rb} +1 -1
  124. data/lib/kward/{local_pty_command_runner.rb → pty/local_pty_runner.rb} +3 -9
  125. data/lib/kward/{pty_output_sink.rb → pty/output_sink.rb} +9 -4
  126. data/lib/kward/pty/transcript_normalizer.rb +137 -0
  127. data/lib/kward/rpc/config_manager.rb +3 -0
  128. data/lib/kward/rpc/plugin_chat_manager.rb +30 -10
  129. data/lib/kward/rpc/prompt_bridge.rb +25 -0
  130. data/lib/kward/rpc/server.rb +118 -17
  131. data/lib/kward/rpc/session_manager.rb +208 -60
  132. data/lib/kward/rpc/session_tree_rows.rb +2 -2
  133. data/lib/kward/rpc/tool_metadata.rb +1 -1
  134. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  135. data/lib/kward/sandbox/command_runner.rb +1 -1
  136. data/lib/kward/{session_catalog.rb → sessions/catalog.rb} +1 -1
  137. data/lib/kward/{session_store.rb → sessions/store.rb} +39 -12
  138. data/lib/kward/{session_tree_nodes.rb → sessions/tree_nodes.rb} +3 -3
  139. data/lib/kward/{session_tree_renderer.rb → sessions/tree_renderer.rb} +4 -4
  140. data/lib/kward/{session_tree_tool_display.rb → sessions/tree_tool_display.rb} +1 -1
  141. data/lib/kward/{kwsh.rb → shell/kwsh.rb} +30 -10
  142. data/lib/kward/{kwshrc.rb → shell/kwshrc.rb} +11 -2
  143. data/lib/kward/shell/native_arithmetic.rb +255 -0
  144. data/lib/kward/shell/native_arrays.rb +102 -0
  145. data/lib/kward/shell/native_braces.rb +96 -0
  146. data/lib/kward/shell/native_builtins.rb +476 -0
  147. data/lib/kward/shell/native_completion.rb +169 -0
  148. data/lib/kward/shell/native_condition.rb +75 -0
  149. data/lib/kward/shell/native_directory.rb +116 -0
  150. data/lib/kward/shell/native_exec_state.rb +73 -0
  151. data/lib/kward/shell/native_expansion.rb +252 -0
  152. data/lib/kward/shell/native_fields.rb +62 -0
  153. data/lib/kward/shell/native_glob.rb +96 -0
  154. data/lib/kward/shell/native_history.rb +242 -0
  155. data/lib/kward/shell/native_interactive.rb +164 -0
  156. data/lib/kward/shell/native_invocation.rb +42 -0
  157. data/lib/kward/shell/native_jobs.rb +250 -0
  158. data/lib/kward/shell/native_line_editor.rb +382 -0
  159. data/lib/kward/shell/native_line_terminal.rb +286 -0
  160. data/lib/kward/shell/native_locale.rb +109 -0
  161. data/lib/kward/shell/native_locals.rb +57 -0
  162. data/lib/kward/shell/native_pattern.rb +200 -0
  163. data/lib/kward/shell/native_process.rb +279 -0
  164. data/lib/kward/shell/native_program.rb +40 -0
  165. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  166. data/lib/kward/shell/native_prompt_format.rb +89 -0
  167. data/lib/kward/shell/native_runtime.rb +964 -0
  168. data/lib/kward/shell/native_substitution.rb +110 -0
  169. data/lib/kward/shell/native_syntax.rb +946 -0
  170. data/lib/kward/shell/native_traps.rb +196 -0
  171. data/lib/kward/shell/native_vi.rb +407 -0
  172. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  173. data/lib/kward/shell/native_worker.rb +82 -0
  174. data/lib/kward/{persistent_shell_session.rb → shell/persistent_session.rb} +187 -193
  175. data/lib/kward/shell/prompt.rb +66 -0
  176. data/lib/kward/shell/prompt_agent.rb +17 -0
  177. data/lib/kward/{shell_prompt_session.rb → shell/prompt_session.rb} +1 -1
  178. data/lib/kward/shell/script_runner.rb +244 -0
  179. data/lib/kward/shell/standalone_agent.rb +31 -0
  180. data/lib/kward/shell/standalone_link.rb +78 -0
  181. data/lib/kward/shell/standalone_terminal.rb +287 -0
  182. data/lib/kward/skills/trust_store.rb +1 -1
  183. data/lib/kward/tabs/driver.rb +194 -0
  184. data/lib/kward/{tab_store.rb → tabs/store.rb} +2 -2
  185. data/lib/kward/{clipboard.rb → terminal/clipboard.rb} +1 -1
  186. data/lib/kward/{terminal_image_support.rb → terminal/image_support.rb} +1 -1
  187. data/lib/kward/{terminal_keys.rb → terminal/keys.rb} +22 -1
  188. data/lib/kward/terminal/locale_text.rb +29 -0
  189. data/lib/kward/{terminal_sequences.rb → terminal/sequences.rb} +45 -4
  190. data/lib/kward/tools/base.rb +18 -0
  191. data/lib/kward/tools/context_for_task.rb +15 -6
  192. data/lib/kward/tools/datetime.rb +85 -0
  193. data/lib/kward/tools/edit_file.rb +9 -6
  194. data/lib/kward/tools/generate_image.rb +36 -0
  195. data/lib/kward/tools/git_commit.rb +13 -7
  196. data/lib/kward/tools/list_directory.rb +4 -4
  197. data/lib/kward/tools/plugin_tool.rb +41 -0
  198. data/lib/kward/tools/prepare_shell_command.rb +1 -1
  199. data/lib/kward/tools/read_file.rb +7 -6
  200. data/lib/kward/tools/registry.rb +130 -21
  201. data/lib/kward/tools/run_shell_command.rb +10 -8
  202. data/lib/kward/tools/search/code.rb +1 -1
  203. data/lib/kward/tools/summarize_file_structure.rb +5 -5
  204. data/lib/kward/tools/tool_call.rb +4 -1
  205. data/lib/kward/tools/typesafe_evaluate.rb +81 -0
  206. data/lib/kward/tools/workspace_targets.rb +58 -0
  207. data/lib/kward/tools/write_file.rb +9 -6
  208. data/lib/kward/{export_path.rb → transcripts/export_path.rb} +1 -1
  209. data/lib/kward/{markdown_transcript.rb → transcripts/markdown_transcript.rb} +10 -2
  210. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  211. data/lib/kward/transport/contracts.rb +200 -0
  212. data/lib/kward/transport/gateway.rb +81 -36
  213. data/lib/kward/transport/plugin_chat_gateway.rb +3 -2
  214. data/lib/kward/transport.rb +1 -200
  215. data/lib/kward/turn_summary.rb +68 -0
  216. data/lib/kward/version.rb +1 -1
  217. data/lib/kward/{workspace_factory.rb → workspace/factory.rb} +2 -2
  218. data/lib/kward/{git_worktree_manager.rb → workspace/git_worktree_manager.rb} +28 -0
  219. data/lib/kward/{workspace.rb → workspace/workspace.rb} +3 -3
  220. data/lib/main.rb +6 -3
  221. data/templates/default/fulldoc/html/css/kward.css +125 -0
  222. data/templates/default/fulldoc/html/images/kward_screen_1.png +0 -0
  223. data/templates/default/fulldoc/html/setup.rb +1 -1
  224. data/templates/default/layout/html/layout.erb +16 -4
  225. metadata +150 -48
  226. data/lib/kward/pty_transcript_normalizer.rb +0 -93
  227. data/lib/kward/shell_prompt.rb +0 -52
  228. data/lib/kward/tab_driver.rb +0 -90
  229. data/templates/default/fulldoc/html/images/kward_workflow.svg +0 -52
  230. /data/lib/kward/{editor_prompt.rb → cli/editor_prompt.rb} +0 -0
  231. /data/lib/kward/{editor_prompt_session.rb → cli/editor_prompt_session.rb} +0 -0
  232. /data/lib/kward/{diff_view_mode.rb → prompt_interface/editor/diff_view_mode.rb} +0 -0
  233. /data/lib/kward/{editor_mode.rb → prompt_interface/editor/editor_mode.rb} +0 -0
  234. /data/lib/kward/{markdown_code_block.rb → prompt_interface/editor/markdown_code_block.rb} +0 -0
  235. /data/lib/kward/{scratchpad_languages.rb → prompt_interface/editor/scratchpad_languages.rb} +0 -0
  236. /data/lib/kward/{scratchpad_runner.rb → prompt_interface/editor/scratchpad_runner.rb} +0 -0
  237. /data/lib/kward/{detached_run.rb → pty/detached_run.rb} +0 -0
  238. /data/lib/kward/{session_diff.rb → sessions/diff.rb} +0 -0
  239. /data/lib/kward/{session_naming.rb → sessions/naming.rb} +0 -0
  240. /data/lib/kward/{session_trash.rb → sessions/trash.rb} +0 -0
  241. /data/lib/kward/{ansi.rb → terminal/ansi.rb} +0 -0
  242. /data/lib/kward/{terminal_text.rb → terminal/text.rb} +0 -0
  243. /data/lib/kward/{transcript_export.rb → transcripts/transcript_export.rb} +0 -0
  244. /data/lib/kward/{project_files.rb → workspace/files.rb} +0 -0
  245. /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 questions | [Tool approval bridge](#Tool_approval_bridge) and [UI question bridge](#UI_question_bridge) |
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
- - `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. 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.
69
- - `events`: the `turn/event` contract, assistant and reasoning events, 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.
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 bridge support via `ui/question` and `ui/answerQuestion`, plus plugin footer updates via `ui/footer`; other UI primitives are explicitly unsupported.
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 sessions. When `initialize.capabilities.pluginChats.supported` is true, use `pluginChats/list` to discover available types.
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 turns are serialized per chat and do not use workspace sessions, agents, or model overrides.
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 question bridge
568
+ ## Structured UI bridge
494
569
 
495
- Kward supports the structured question bridge and plugin footer updates over RPC. The `extensionUi` capability reports `question.supported: true` with `notification: "ui/question"`, `method: "ui/answerQuestion"`, `maxQuestions: 4`, `multiSelect: false`, and `preview: false`. It also reports `footer.supported: true` with `notification: "ui/footer"`. Other Pi-style extension UI primitives (`select`, `confirm`, `input`, `editor`, `widgets`, `custom`, and `terminalInput`) are explicitly reported as unsupported until Kward has a real plugin/extension consumer for them.
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 a loaded Kward plugin registers a footer, RPC emits `ui/footer` after session creation/resume/clone and after each completed turn:
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": "custom footer 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
- An empty `text` value clears the client footer.
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
- Refreshes config-backed runtime state and returns `{ "ok": true, "message": "Resources reloaded." }`.
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 model entries from configured provider catalogs, including cached and curated fallbacks. Entries use `{ "provider", "id", "name", "reasoning", "reasoningEffort", "contextWindow", "current" }`.
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
- Refreshes that provider's live model catalog when discovery is supported and returns the complete sanitized model list. Providers without live discovery retain configured or curated choices.
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 linked
71
- worktree and no configured additional writable roots are carried into the tab.
72
- The configured child-network setting is preserved.
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 interactive `/git` flow remains available for manual review and
86
- commit.
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 MCP 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.
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.
@@ -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 it a useful name:
63
+ Start a chat and give the current session and tab a useful name:
29
64
 
30
65
  ```text
31
- /rename oauth cleanup
66
+ /name oauth cleanup
32
67
  ```
33
68
 
34
- `/rename` requires a name. Use `/session name` without an argument to clear the current session name.
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 | `/rename <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` |