kward 0.85.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 (151) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +130 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +3 -3
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +11 -0
  8. data/doc/api.md +4 -1
  9. data/doc/composer.md +4 -3
  10. data/doc/configuration.md +60 -11
  11. data/doc/extensibility.md +2 -0
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +1 -1
  14. data/doc/memory.md +1 -1
  15. data/doc/plugins.md +40 -5
  16. data/doc/providers.md +10 -4
  17. data/doc/rpc.md +125 -7
  18. data/doc/session-management.md +36 -1
  19. data/doc/shell.md +643 -27
  20. data/doc/tabs.md +2 -1
  21. data/doc/troubleshooting.md +1 -1
  22. data/doc/usage.md +21 -11
  23. data/examples/plugins/openrouter_proxy/README.md +103 -0
  24. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  25. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  26. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  27. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  28. data/examples/plugins/space_invaders.rb +0 -1
  29. data/exe/kward +2 -2
  30. data/exe/kwsh +7 -0
  31. data/kward.gemspec +3 -1
  32. data/lib/kward/agent.rb +43 -9
  33. data/lib/kward/cli/commands.rb +41 -11
  34. data/lib/kward/cli/interactive_turn.rb +10 -0
  35. data/lib/kward/cli/plugins.rb +5 -1
  36. data/lib/kward/cli/prompt_interface.rb +4 -1
  37. data/lib/kward/cli/rendering.rb +21 -28
  38. data/lib/kward/cli/runtime_helpers.rb +52 -34
  39. data/lib/kward/cli/settings/model.rb +1 -12
  40. data/lib/kward/cli/tabs.rb +91 -18
  41. data/lib/kward/cli/tool_summaries.rb +2 -0
  42. data/lib/kward/cli/transcript_formatter.rb +3 -10
  43. data/lib/kward/cli/worktrees.rb +1 -0
  44. data/lib/kward/cli.rb +56 -7
  45. data/lib/kward/config/core.rb +16 -5
  46. data/lib/kward/config/extensions.rb +3 -0
  47. data/lib/kward/config/paths.rb +11 -0
  48. data/lib/kward/config/settings.rb +7 -0
  49. data/lib/kward/conversation.rb +11 -1
  50. data/lib/kward/entrypoint.rb +14 -0
  51. data/lib/kward/events.rb +2 -0
  52. data/lib/kward/generated_images.rb +237 -0
  53. data/lib/kward/model/catalog.rb +6 -3
  54. data/lib/kward/model/client.rb +105 -36
  55. data/lib/kward/model/codex_images.rb +83 -0
  56. data/lib/kward/model/copilot_models.rb +8 -4
  57. data/lib/kward/model/model_info.rb +27 -9
  58. data/lib/kward/model/openrouter_model_cache.rb +4 -2
  59. data/lib/kward/model/payloads.rb +6 -5
  60. data/lib/kward/model/sources.rb +3 -1
  61. data/lib/kward/model/stream_parser.rb +4 -7
  62. data/lib/kward/pan/index.html.erb +8 -1
  63. data/lib/kward/pan/server.rb +13 -1
  64. data/lib/kward/plugins/codex_responses.rb +73 -0
  65. data/lib/kward/plugins/host.rb +16 -0
  66. data/lib/kward/plugins/http_server.rb +83 -0
  67. data/lib/kward/plugins/registry.rb +39 -0
  68. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  69. data/lib/kward/prompt_interface/composer_renderer.rb +159 -72
  70. data/lib/kward/prompt_interface/editor/controller.rb +1 -1
  71. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  72. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  73. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  74. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  75. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  76. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  77. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  78. data/lib/kward/prompt_interface/layout.rb +11 -1
  79. data/lib/kward/prompt_interface/overlay_renderer.rb +25 -8
  80. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  81. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  82. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  83. data/lib/kward/prompt_interface/runtime_state.rb +31 -9
  84. data/lib/kward/prompt_interface/screen.rb +24 -21
  85. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  86. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  87. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  88. data/lib/kward/prompt_interface.rb +109 -39
  89. data/lib/kward/prompts.rb +7 -1
  90. data/lib/kward/pty/adaptive_output_sink.rb +38 -4
  91. data/lib/kward/pty/interactive_runner.rb +20 -28
  92. data/lib/kward/pty/transcript_normalizer.rb +65 -21
  93. data/lib/kward/rpc/config_manager.rb +3 -0
  94. data/lib/kward/rpc/server.rb +27 -5
  95. data/lib/kward/rpc/session_manager.rb +62 -17
  96. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  97. data/lib/kward/sessions/store.rb +30 -3
  98. data/lib/kward/shell/kwsh.rb +27 -7
  99. data/lib/kward/shell/kwshrc.rb +11 -2
  100. data/lib/kward/shell/native_arithmetic.rb +255 -0
  101. data/lib/kward/shell/native_arrays.rb +102 -0
  102. data/lib/kward/shell/native_braces.rb +96 -0
  103. data/lib/kward/shell/native_builtins.rb +476 -0
  104. data/lib/kward/shell/native_completion.rb +169 -0
  105. data/lib/kward/shell/native_condition.rb +75 -0
  106. data/lib/kward/shell/native_directory.rb +116 -0
  107. data/lib/kward/shell/native_exec_state.rb +73 -0
  108. data/lib/kward/shell/native_expansion.rb +252 -0
  109. data/lib/kward/shell/native_fields.rb +62 -0
  110. data/lib/kward/shell/native_glob.rb +96 -0
  111. data/lib/kward/shell/native_history.rb +242 -0
  112. data/lib/kward/shell/native_interactive.rb +164 -0
  113. data/lib/kward/shell/native_invocation.rb +42 -0
  114. data/lib/kward/shell/native_jobs.rb +250 -0
  115. data/lib/kward/shell/native_line_editor.rb +382 -0
  116. data/lib/kward/shell/native_line_terminal.rb +286 -0
  117. data/lib/kward/shell/native_locale.rb +109 -0
  118. data/lib/kward/shell/native_locals.rb +57 -0
  119. data/lib/kward/shell/native_pattern.rb +200 -0
  120. data/lib/kward/shell/native_process.rb +279 -0
  121. data/lib/kward/shell/native_program.rb +40 -0
  122. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  123. data/lib/kward/shell/native_prompt_format.rb +89 -0
  124. data/lib/kward/shell/native_runtime.rb +964 -0
  125. data/lib/kward/shell/native_substitution.rb +110 -0
  126. data/lib/kward/shell/native_syntax.rb +946 -0
  127. data/lib/kward/shell/native_traps.rb +196 -0
  128. data/lib/kward/shell/native_vi.rb +407 -0
  129. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  130. data/lib/kward/shell/native_worker.rb +82 -0
  131. data/lib/kward/shell/persistent_session.rb +184 -190
  132. data/lib/kward/shell/prompt.rb +14 -0
  133. data/lib/kward/shell/prompt_agent.rb +17 -0
  134. data/lib/kward/shell/script_runner.rb +244 -0
  135. data/lib/kward/shell/standalone_agent.rb +31 -0
  136. data/lib/kward/shell/standalone_link.rb +78 -0
  137. data/lib/kward/shell/standalone_terminal.rb +287 -0
  138. data/lib/kward/terminal/keys.rb +22 -1
  139. data/lib/kward/terminal/locale_text.rb +29 -0
  140. data/lib/kward/terminal/sequences.rb +45 -4
  141. data/lib/kward/tools/datetime.rb +85 -0
  142. data/lib/kward/tools/generate_image.rb +36 -0
  143. data/lib/kward/tools/registry.rb +35 -9
  144. data/lib/kward/tools/tool_call.rb +3 -1
  145. data/lib/kward/transcripts/markdown_transcript.rb +8 -0
  146. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  147. data/lib/kward/transport/gateway.rb +2 -1
  148. data/lib/kward/turn_summary.rb +68 -0
  149. data/lib/kward/version.rb +1 -1
  150. data/lib/main.rb +6 -3
  151. metadata +84 -1
data/doc/providers.md CHANGED
@@ -117,9 +117,13 @@ Kward combines several sources so a temporary catalog failure does not lock you
117
117
  4. the currently configured model;
118
118
  5. a manual ID entered in `/model`.
119
119
 
120
- When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Empty or incomplete metadata stays visible. Use **Show all models** for embedding, preview, private, or unusually described models.
120
+ When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Unknown or empty metadata and the current selection stay visible. Use **Show all models** for embedding, preview, private, or unusually described models.
121
121
 
122
- Model discovery proves that an ID exists; it does not guarantee account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
122
+ Known model choices can include configured or curated fallbacks, not just discovered IDs. Neither a listing nor successful discovery guarantees account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
123
+
124
+ **Refresh model list** refreshes only the active provider, or the provider chosen in the picker—not every configured provider. OpenRouter uses its own key-associated disk cache; Copilot and Local replace their process-local discovery results. Anthropic consumes its disk catalog alongside curated choices (live discovery requires an API key). API-key providers with discovery use their provider catalogs. Codex and providers without discovery, such as Azure deployment selection, retain curated/configured choices. Failed discovery preserves the last usable catalog.
125
+
126
+ Refreshing is not configuration reload. After another Kward process changes configuration or caches, RPC clients should explicitly call `runtime/reload` then `models/list`. Reload also reloads plugins and reapplies configuration-backed session runtime state; ordinary catalog reads and refreshes do neither. Copilot and Local have no shared persisted model catalog and rediscover lazily after reload. There is no automatic cross-process watcher or model-change notification.
123
127
 
124
128
  ## OAuth availability
125
129
 
@@ -133,8 +137,10 @@ RPC clients should discover providers rather than hard-code this table:
133
137
 
134
138
  - `auth/providers` returns catalog providers and supported authentication methods;
135
139
  - `auth/status` returns sanitized configured/source state;
136
- - `models/list` returns known model entries;
137
- - `models/refresh` refreshes a provider when supported;
140
+ - `models/list` returns the complete known catalog; use `defaultSelectable` for the default picker and the full list for **Show all models**;
141
+ - `models/refresh` returns the catalog plus a safe `refresh` outcome (`provider`, `status`, `fallbackUsed`), distinguishing `success`, `unsupported`, and `failed`;
138
142
  - `models/set` selects the provider and model.
139
143
 
144
+ Check `initialize` model field and refresh metadata capabilities before consuming additive fields. Keep `OpenAI` and `Codex` identities separate and pass provider/model IDs back unchanged, including slashes.
145
+
140
146
  See the [RPC protocol](rpc.md#Config_and_auth_methods) for request shapes and unsupported OAuth capability reporting.
data/doc/rpc.md CHANGED
@@ -87,7 +87,7 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
87
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.
88
88
  - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
89
89
  - `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
90
- - `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.
91
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.
92
92
 
93
93
  ### `shutdown`
@@ -360,7 +360,7 @@ Subscribed clients receive `pluginChat/event` notifications:
360
360
  }
361
361
  ```
362
362
 
363
- 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`.
364
364
 
365
365
  ## Turn methods
366
366
 
@@ -453,12 +453,59 @@ Known event types:
453
453
  - `answer`
454
454
  - `turnCancelRequested`
455
455
  - `error`
456
+ - `turnSummary`
456
457
  - `turnFinished`
457
458
 
458
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.
459
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
+
460
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.
461
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
+
462
509
  `modelRetry` is emitted before Kward retries a transient model request failure. Its payload includes `provider`, `model`, `attempt`, `maxAttempts`, `delaySeconds`, and `error`.
463
510
 
464
511
  `steeringApplied` is emitted after queued steering input has been appended to conversation context. Its payload includes `count`, the number of steering messages applied.
@@ -483,6 +530,19 @@ Examples:
483
530
  - `write_file`: `toolName: "write"`, `args: { "path": "...", "content": "..." }`.
484
531
  - `run_shell_command`: `toolName: "bash"`, `args: { "command": "...", "timeout": 30 }`.
485
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
+
486
546
  ## Tool approval bridge
487
547
 
488
548
  When `turns/start` is called with `options.approvalMode: "ask"`, Kward emits `tool/approvalRequested` before executing each tool.
@@ -629,7 +689,11 @@ Params:
629
689
 
630
690
  - `sessionId`: active RPC session ID.
631
691
 
632
- 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.
633
697
 
634
698
  ## Logging methods
635
699
 
@@ -766,15 +830,63 @@ Returns `{ "memories": [] }`.
766
830
 
767
831
  ### `models/list`
768
832
 
769
- 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
+ ```
770
860
 
771
861
  ### `models/refresh`
772
862
 
773
863
  Params:
774
864
 
775
- - `provider`: optional configured provider name. Defaults to the active provider.
865
+ - `provider`: optional configured provider name or catalog ID. Defaults to the active provider.
776
866
 
777
- 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.
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.
888
+
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.
778
890
 
779
891
  ### `models/current`
780
892
 
@@ -787,7 +899,13 @@ Params:
787
899
  - `model`: model ID string.
788
900
  - `provider`: optional provider name or catalog ID; defaults to the active provider.
789
901
 
790
- 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.
791
909
 
792
910
  ### `reasoning/set`
793
911
 
@@ -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