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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +130 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +6 -2
- data/README.md +3 -3
- data/Rakefile +3 -0
- data/doc/agent-tools.md +11 -0
- data/doc/api.md +4 -1
- data/doc/composer.md +4 -3
- data/doc/configuration.md +60 -11
- data/doc/extensibility.md +2 -0
- data/doc/getting-started.md +3 -3
- data/doc/git.md +1 -1
- data/doc/memory.md +1 -1
- data/doc/plugins.md +40 -5
- data/doc/providers.md +10 -4
- data/doc/rpc.md +125 -7
- data/doc/session-management.md +36 -1
- data/doc/shell.md +643 -27
- data/doc/tabs.md +2 -1
- data/doc/troubleshooting.md +1 -1
- data/doc/usage.md +21 -11
- 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 +0 -1
- data/exe/kward +2 -2
- data/exe/kwsh +7 -0
- data/kward.gemspec +3 -1
- data/lib/kward/agent.rb +43 -9
- data/lib/kward/cli/commands.rb +41 -11
- data/lib/kward/cli/interactive_turn.rb +10 -0
- data/lib/kward/cli/plugins.rb +5 -1
- data/lib/kward/cli/prompt_interface.rb +4 -1
- data/lib/kward/cli/rendering.rb +21 -28
- data/lib/kward/cli/runtime_helpers.rb +52 -34
- data/lib/kward/cli/settings/model.rb +1 -12
- data/lib/kward/cli/tabs.rb +91 -18
- data/lib/kward/cli/tool_summaries.rb +2 -0
- data/lib/kward/cli/transcript_formatter.rb +3 -10
- data/lib/kward/cli/worktrees.rb +1 -0
- data/lib/kward/cli.rb +56 -7
- data/lib/kward/config/core.rb +16 -5
- data/lib/kward/config/extensions.rb +3 -0
- data/lib/kward/config/paths.rb +11 -0
- data/lib/kward/config/settings.rb +7 -0
- data/lib/kward/conversation.rb +11 -1
- 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/model/catalog.rb +6 -3
- data/lib/kward/model/client.rb +105 -36
- data/lib/kward/model/codex_images.rb +83 -0
- data/lib/kward/model/copilot_models.rb +8 -4
- data/lib/kward/model/model_info.rb +27 -9
- data/lib/kward/model/openrouter_model_cache.rb +4 -2
- data/lib/kward/model/payloads.rb +6 -5
- data/lib/kward/model/sources.rb +3 -1
- data/lib/kward/model/stream_parser.rb +4 -7
- data/lib/kward/pan/index.html.erb +8 -1
- data/lib/kward/pan/server.rb +13 -1
- data/lib/kward/plugins/codex_responses.rb +73 -0
- data/lib/kward/plugins/host.rb +16 -0
- data/lib/kward/plugins/http_server.rb +83 -0
- data/lib/kward/plugins/registry.rb +39 -0
- data/lib/kward/prompt_interface/composer_controller.rb +0 -1
- data/lib/kward/prompt_interface/composer_renderer.rb +159 -72
- data/lib/kward/prompt_interface/editor/controller.rb +1 -1
- data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
- 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 +25 -8
- 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 +31 -9
- data/lib/kward/prompt_interface/screen.rb +24 -21
- 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 +109 -39
- data/lib/kward/prompts.rb +7 -1
- data/lib/kward/pty/adaptive_output_sink.rb +38 -4
- data/lib/kward/pty/interactive_runner.rb +20 -28
- data/lib/kward/pty/transcript_normalizer.rb +65 -21
- data/lib/kward/rpc/config_manager.rb +3 -0
- data/lib/kward/rpc/server.rb +27 -5
- data/lib/kward/rpc/session_manager.rb +62 -17
- data/lib/kward/rpc/transcript_normalizer.rb +11 -7
- data/lib/kward/sessions/store.rb +30 -3
- data/lib/kward/shell/kwsh.rb +27 -7
- data/lib/kward/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/shell/persistent_session.rb +184 -190
- data/lib/kward/shell/prompt.rb +14 -0
- data/lib/kward/shell/prompt_agent.rb +17 -0
- 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/terminal/keys.rb +22 -1
- data/lib/kward/terminal/locale_text.rb +29 -0
- data/lib/kward/terminal/sequences.rb +45 -4
- data/lib/kward/tools/datetime.rb +85 -0
- data/lib/kward/tools/generate_image.rb +36 -0
- data/lib/kward/tools/registry.rb +35 -9
- data/lib/kward/tools/tool_call.rb +3 -1
- data/lib/kward/transcripts/markdown_transcript.rb +8 -0
- data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
- data/lib/kward/transport/gateway.rb +2 -1
- data/lib/kward/turn_summary.rb +68 -0
- data/lib/kward/version.rb +1 -1
- data/lib/main.rb +6 -3
- 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.
|
|
120
|
+
When capability metadata is present, the default picker prioritizes entries that advertise generation or tool/function support and hides the others. Unknown or empty metadata and the current selection stay visible. Use **Show all models** for embedding, preview, private, or unusually described models.
|
|
121
121
|
|
|
122
|
-
|
|
122
|
+
Known model choices can include configured or curated fallbacks, not just discovered IDs. Neither a listing nor successful discovery guarantees account access, tool support, image support, context size, pricing, or regional availability. Provider errors remain authoritative.
|
|
123
|
+
|
|
124
|
+
**Refresh model list** refreshes only the active provider, or the provider chosen in the picker—not every configured provider. OpenRouter uses its own key-associated disk cache; Copilot and Local replace their process-local discovery results. Anthropic consumes its disk catalog alongside curated choices (live discovery requires an API key). API-key providers with discovery use their provider catalogs. Codex and providers without discovery, such as Azure deployment selection, retain curated/configured choices. Failed discovery preserves the last usable catalog.
|
|
125
|
+
|
|
126
|
+
Refreshing is not configuration reload. After another Kward process changes configuration or caches, RPC clients should explicitly call `runtime/reload` then `models/list`. Reload also reloads plugins and reapplies configuration-backed session runtime state; ordinary catalog reads and refreshes do neither. Copilot and Local have no shared persisted model catalog and rediscover lazily after reload. There is no automatic cross-process watcher or model-change notification.
|
|
123
127
|
|
|
124
128
|
## OAuth availability
|
|
125
129
|
|
|
@@ -133,8 +137,10 @@ RPC clients should discover providers rather than hard-code this table:
|
|
|
133
137
|
|
|
134
138
|
- `auth/providers` returns catalog providers and supported authentication methods;
|
|
135
139
|
- `auth/status` returns sanitized configured/source state;
|
|
136
|
-
- `models/list` returns known
|
|
137
|
-
- `models/refresh`
|
|
140
|
+
- `models/list` returns the complete known catalog; use `defaultSelectable` for the default picker and the full list for **Show all models**;
|
|
141
|
+
- `models/refresh` returns the catalog plus a safe `refresh` outcome (`provider`, `status`, `fallbackUsed`), distinguishing `success`, `unsupported`, and `failed`;
|
|
138
142
|
- `models/set` selects the provider and model.
|
|
139
143
|
|
|
144
|
+
Check `initialize` model field and refresh metadata capabilities before consuming additive fields. Keep `OpenAI` and `Codex` identities separate and pass provider/model IDs back unchanged, including slashes.
|
|
145
|
+
|
|
140
146
|
See the [RPC protocol](rpc.md#Config_and_auth_methods) for request shapes and unsupported OAuth capability reporting.
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|