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
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d5f437e5a636602d7742b14f118fd9232cc518c4b796089ae069b6a26edbb276
|
|
4
|
+
data.tar.gz: 135a464bab9b9c844940739243545d5c05a786a4b9757debc001e621b25e6bb7
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 59254bfcee2caf48063b513dd78f1135edaadb4bbb39eb1dc8d929943398e9f60cf60df600d4d588ec854885607d60a1ad1322f689b9e7e3fd06e5108971d733
|
|
7
|
+
data.tar.gz: 993c21c4ba06234d834c72e64c81093d70c5bbbfcb0db04cb4d9c98471b4d9c4a210a6d61733ab6bb76cfc138cc5c54172fe5e934c034baa1da2dc4d4e85f545
|
data/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,136 @@ All notable changes to Kward will be documented in this file.
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.86.0] - 2026-11-22
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- Enable automatic color for commands such as macOS `ls` in interactive `kward shell`, without overriding `TERM=dumb` or changing script environments.
|
|
12
|
+
|
|
13
|
+
- Execute interactive `kward shell` startup files as native shell scripts. The native `source` builtin works like `.`, while hosted `/shell` configuration and its top-level `source` command remain declarative.
|
|
14
|
+
|
|
15
|
+
- Require `kward prompt <text>` for one-shot model prompts and add `kward filter <instruction>` for explicit stdin filtering; unknown CLI arguments now fail instead of being sent to the model.
|
|
16
|
+
- Initialize the model client before launching interactive chat so the configured model catalog and picker are available at startup.
|
|
17
|
+
|
|
18
|
+
- Merge opt-in shell history across terminals and browse matching commands with Up/Down after typing a prefix.
|
|
19
|
+
|
|
20
|
+
- Cycle through ambiguous standalone shell completions with Tab and Shift+Tab, and accept a match without running the command.
|
|
21
|
+
|
|
22
|
+
- Display and edit pasted multiline drafts on separate terminal rows before submitting them.
|
|
23
|
+
|
|
24
|
+
- Show the command and stream its output live when the standalone `kward shell` agent runs it for you.
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- Press `Ctrl+N` in the chat composer to start a new conversation in the current tab, just like `/new`.
|
|
29
|
+
|
|
30
|
+
- Press `Ctrl+Shift+T` to open a new tab immediately to the right of the current tab when using the Ctrl tab shortcuts in a terminal that reports the chord.
|
|
31
|
+
|
|
32
|
+
- Support rbenv’s Bash initialization in interactive `kward shell`, with function-local variables and indexed arrays, `rbenv shell`, and programmable Tab completion.
|
|
33
|
+
|
|
34
|
+
- Pause standalone shell history and shell-agent context capture with `history pause`, then restore recording with `history resume`.
|
|
35
|
+
|
|
36
|
+
- Show local history suggestions in standalone shell drafts; press Right Arrow to accept a suggestion.
|
|
37
|
+
|
|
38
|
+
- Added `kward shell` to run native kwsh directly in your terminal without starting the agent or composer at launch. Use `?` to ask the same shell agent as `/shell` about recent output, run an explicit command, or prefill an editable command draft. Interactive sessions execute `kwshrc` startup scripts. The standalone prompt has Tab completion, arrow-key history and editing, bracketed paste, and native job control.
|
|
39
|
+
|
|
40
|
+
- Customize interactive `kward shell` with Zsh-style `PROMPT` escapes for colors, the current directory, username, host, and exit status. Unset `PROMPT` to return to `PS1`.
|
|
41
|
+
|
|
42
|
+
- Move and cut by word in `kward shell` with Option/Alt shortcuts and Ctrl+W. Ctrl+K cuts to the end of the line, and Ctrl+Y restores text cut by these shortcuts or Ctrl+U.
|
|
43
|
+
|
|
44
|
+
- Search standalone shell history with Ctrl+R/Ctrl+S. The default editor also supports screen redraw, transpose, undo, inserting the previous command’s last word, and cycling through older cuts.
|
|
45
|
+
|
|
46
|
+
- Generate images by asking in a Codex chat. Kward previews the result and can save it to Downloads or a project directory chosen with Tab completion. RPC clients can fetch, save, and discard previews.
|
|
47
|
+
|
|
48
|
+
- Added Claude Fable 5.2, Mythos 5.2, Opus 5.5, Sonnet 5.5, and Haiku 5.5 to the Anthropic model picker.
|
|
49
|
+
- Added GPT-6.2 Astra, GPT-6.2 Sol, and GPT-6.1 Terra to the Codex model picker, with model-specific reasoning controls and context-window metadata.
|
|
50
|
+
- Added native POSIX.1-2024 `ulimit` queries and settings for file/core size, data, descriptors, stack, CPU time, and address space, with soft/hard selection and owned-process isolation from the Kward host and other sessions.
|
|
51
|
+
|
|
52
|
+
- Added standalone native vi line editing with history search, motions/operators, repeat/undo, pathname expansion, and private external-vi editing. Terminal modes and command stdin are preserved; RPC reports history, line editing, and mail notifications as unsupported.
|
|
53
|
+
|
|
54
|
+
- Added native PS4 parameter expansion, standalone PS1 history numbering, terminal `ignoreeof`, compatible no-op `nolog`, and MAIL/MAILPATH/MAILCHECK notifications.
|
|
55
|
+
|
|
56
|
+
- Added standalone native command history and `fc` listing, substitution, and private editor workflows, with opt-in `HISTFILE` persistence and `HISTSIZE` retention. Hosted history remains separate.
|
|
57
|
+
|
|
58
|
+
- Standalone kwsh now supports inherited descriptors 3–9 for redirection, duplication, closing, native scripts, child commands, and executable-text fallback, without exposing hosted private descriptors.
|
|
59
|
+
|
|
60
|
+
- Added bounded multi-character locale collation across native case patterns, parameter trimming, and globs, plus requirement-linked POSIX and installed-locale regression coverage.
|
|
61
|
+
- Added native shared-stream aliases, core builtin flag combinations, command hashing, `type`, `times`, `CDPATH`, and standalone interactive `kwsh -i` with guarded `ENV` startup and parameter-expanded prompts.
|
|
62
|
+
- Added POSIX arithmetic-expansion substitutions, `case ;&` fall-through, and source-aware `LINENO`; new shells reset inherited `IFS`, and `command -V` follows function/builtin execution precedence.
|
|
63
|
+
- Added native kwsh background lists, `$!`, jobs/wait/kill, stopped-job foreground/background control, signal/EXIT traps, persistent exec redirections, and standalone process replacement, with tab-owned cleanup for hosted shells.
|
|
64
|
+
- Added read-time native aliases, incremental script execution, named-user and assignment-context tildes, and installed-locale character counts, bracket matching, pathname expansion, and sorting.
|
|
65
|
+
|
|
66
|
+
- Expanded native kwsh with subshells, nested command/process substitution, here-documents, descriptors 0–9, bounded extended arithmetic and arithmetic loops, indexed/associative arrays, `[[ … ]]`, brace expansion, opt-in globstar, native dot-sourcing and state utilities, read delimiters, shell options, and a standalone `kwsh` executable. Full POSIX/Bash conformance remains unfinished; documented limits remain explicit.
|
|
67
|
+
- Added native kwsh parameter operators, `case` pattern matching, `read -r`, and custom/empty `IFS`, with lazy nested expansion, quote-preserving splitting, and line-reading workflows. This is the first stage toward broader POSIX scripting and Bash-compatible extensions, not full compatibility.
|
|
68
|
+
- Added native kwsh integer arithmetic expansion (`$((5 + 2))`), with basic operators, grouping, integer-valued variables, bounded evaluation, and shell-assistant guidance for the supported syntax. A kwsh-specific extension also accepts spaces or tabs between the final closing parentheses (`$((5 + 2) )`).
|
|
69
|
+
- Added native kwsh scripting inside `/shell`: multiline programs, quoted variables and arguments, conditionals, loops, functions, pipelines, ordered redirection, and isolated `kwsh <file> [args]` execution, without delegating the language to another shell.
|
|
70
|
+
- Added RPC model-picker eligibility and safe provider refresh outcomes, with consistent catalog refresh/fallback behavior and explicit cross-process reload guidance.
|
|
71
|
+
- Added cached-input counts and cache-hit rate, cache-write counts, and reasoning-token counts to detailed turn statistics, preserving unavailable versus reported-zero fields and marking partial breakdowns.
|
|
72
|
+
- Added persistent turn-end elapsed time, token usage, and tool-call summaries across CLI/TUI, RPC, Pan, and transcript exports, with compact/detailed/off display modes and explicit partial or unavailable usage.
|
|
73
|
+
- Added `--ignore-local-instructions` to suppress workspace `AGENTS.md` guidance and project skills for a CLI run while retaining user-level instructions and skills.
|
|
74
|
+
- Added an example `--openrouter-proxy` plugin that serves authenticated, loopback-only OpenRouter Chat Completions requests through Kward's Codex account, with non-streaming and SSE translations and strict JSON-schema output support.
|
|
75
|
+
- Added a local deterministic fake embeddings endpoint to the example OpenRouter proxy, with configured model IDs, bounded dimensions and batches, and no upstream embedding requests.
|
|
76
|
+
- Added a plugin-host Codex Responses streaming client using Kward's OAuth credentials and the documented ChatGPT-plan API endpoint, with storage disabled and safe provider errors.
|
|
77
|
+
- Added a managed, loopback-only HTTP listener to identified plugin hosts with bounded requests and automatic cleanup on reload or shutdown.
|
|
78
|
+
- Added declarative, identified-plugin CLI startup options for foreground modes, parsed before normal command dispatch and activated only when selected.
|
|
79
|
+
- Added the model-callable `datetime` tool for current local/offset time and ISO 8601 timestamp arithmetic with fixed UTC offsets.
|
|
80
|
+
|
|
81
|
+
### Changed
|
|
82
|
+
|
|
83
|
+
- Native kwsh now interprets executable text after an `ENOEXEC` error, including shebangless scripts found through `PATH` and invoked with `exec`, without delegating to another shell. Permission failures and binary-looking files remain rejected; standalone PID replacement and hosted job ownership are preserved.
|
|
84
|
+
- Native `. file` now executes script code consistently in `/shell`; `source file` remains declarative configuration loading. Native aliases apply to subsequent complete input units instead of being reparsed at execution time. Locale selection follows LC_ALL/category/LANG precedence, defaulting to C; unavailable locales error explicitly. Hosted exec closes the logical session without replacing its control-channel worker, and USR2 is reserved for shutdown.
|
|
85
|
+
- Restored the interactive composer's original Braille spinner and animation pace while retaining activity labels, elapsed time, and completion indicators.
|
|
86
|
+
- Removed decorative prefixes from assistant and user transcript labels, retaining speaker names and colors.
|
|
87
|
+
- Replaced the persistent `/shell` system-shell evaluator with kwsh's deliberately limited POSIX-style interpreter. Unsupported syntax now errors explicitly rather than inheriting the host shell's language; declarative rc loading and the separate one-off/model/RPC command paths retain their existing behavior.
|
|
88
|
+
- Routed plugin-host Codex streaming and the OpenRouter proxy through Kward's normal Codex provider client and configured subscription credentials, rather than the public Responses API path.
|
|
89
|
+
|
|
90
|
+
### Fixed
|
|
91
|
+
|
|
92
|
+
- Keep Ctrl+Z working for foreground jobs when the launcher ignores job-control stop signals.
|
|
93
|
+
- Keep standalone shell history in memory if saving it would exceed the file-size limit, rather than terminating the shell.
|
|
94
|
+
- Restore the previous terminal screen after `kward edit` and after leaving full-screen Git logs in `kward shell` with the default pager settings.
|
|
95
|
+
- Use every terminal row in the editor, both inside chat and when launched with `kward edit`.
|
|
96
|
+
- Show the active alias in kwsh’s `which` output instead of reporting the shadowed executable.
|
|
97
|
+
- Return to the shell prompt below the Kward transcript on exit, rather than jumping to the top of the screen.
|
|
98
|
+
- Keep interactive plugin games open when pressing Command or Shift. Only plain Esc exits by default; plugins can define additional quit keys.
|
|
99
|
+
- Keep inline Kitty graphics and capability-probe output visible when the shell prompt returns.
|
|
100
|
+
- Forward lone Escape and legacy Alt keys to shell PTYs without collapsing combined modifiers into control signals.
|
|
101
|
+
- Keep detached shell output on the same line across PTY reads.
|
|
102
|
+
- Restore the current terminal size on new shell PTYs, including after a `/shell` worker restarts.
|
|
103
|
+
- Preserve wide characters, combining accents, and backspace redraws in shell transcript replay.
|
|
104
|
+
- Bound the size of shell transcript replay when a command uses cursor movement.
|
|
105
|
+
- Keep busy composer headers on one line in narrow panes, dropping the cancel hint before clipping the activity text.
|
|
106
|
+
- Keep the draft and cursor visible in short panes by collapsing tabs, footers, and overlays as space runs out, while leaving room for transcript scrolling.
|
|
107
|
+
- Keep the composer cursor steady during spinner and status redraws, and refresh the header and footer even when the spinner is paused or the composer is idle.
|
|
108
|
+
- Prevent standalone modifier presses, such as Cmd or Shift, from printing escape sequences while an interactive shell command runs.
|
|
109
|
+
- Keep pending terminal image previews available when a queued follow-up starts before the preview opens.
|
|
110
|
+
- Return an empty final chunk when an RPC image fetch starts exactly at the end of the image.
|
|
111
|
+
- Native dot-sourcing now continues searching `PATH` when a matching file cannot be opened, selecting the first readable candidate as required.
|
|
112
|
+
- Native `getopts` error diagnostics now identify the invoking shell, including for unknown options and missing option arguments.
|
|
113
|
+
- Standalone `read` now displays the parameter-expanded `PS2` prompt on interactive backslash-newline continuations.
|
|
114
|
+
- Native `type` now rejects a missing operand, and `kill -s name` / `kill -name` accept case-independent signal names as required by POSIX.
|
|
115
|
+
|
|
116
|
+
- Removed native arithmetic's 4,096-byte expression ceiling and recursive evaluation of flat binary chains. Long non-overflowing expressions and zero-padded integers now work; precision, nesting, and other safety policies remain explicit in the resource-limit inventory.
|
|
117
|
+
|
|
118
|
+
- Failed standalone interactive kwsh `exec` now recovers for a fresh submission while retaining successful redirections. Internal IO, directory, mask, and signal state is restored; descriptor reservation keeps Ruby VM handles out of the shell's 3–9 range.
|
|
119
|
+
|
|
120
|
+
- Corrected native kwsh interactive signal defaults, protected inherited ignored signals, and made `trap -p` output include defaults and survive subshell save/restore. Interrupted `wait` traps now observe the wait status and run before `errexit`; hosted shutdown ownership is unchanged.
|
|
121
|
+
|
|
122
|
+
- Kept native shell directory identity across renames for execution, sourcing, redirection and globbing, with owned close-on-exec handles and no host cwd changes. Logical `cd` now validates components before removing `..`.
|
|
123
|
+
- Completed native `umask` symbolic permission copying, sequential operations and `-S`/`--` handling, and added `cd -P -e` pathname-reporting status without undoing successful directory changes.
|
|
124
|
+
- Corrected native alias names and quoted listing output, and traced expanded assignment-only commands without evaluating substitutions twice.
|
|
125
|
+
- Corrected native kwsh startup `PPID`/`OPTIND`, standalone inherited logical `PWD` validation, invocation-derived `$0`, and leading `-` operand handling, while preserving hosted workspace ownership and stdin command boundaries.
|
|
126
|
+
- Fixed native shell redirection operands being split/globbed, here-document continuation order, and premature execution of backslash-continued input lines.
|
|
127
|
+
- Protected TUI tab shortcuts across shell keyboard-mode changes and screen switches, restored composer terminal modes on handback, and hardened fragmented key and bracketed-paste handling without unbounded output buffering.
|
|
128
|
+
- Corrected native kwsh fatal-error handling and POSIX `errexit` inheritance, preserving interactive recovery, subshell isolation, special-builtin behavior through `command`, and EXIT traps.
|
|
129
|
+
- Kept `/shell` background servers responsive after `bg` by draining idle PTY output instead of letting logs fill the terminal buffer and block further requests; idle output is discarded, so redirect jobs to files to retain logs.
|
|
130
|
+
- Fixed native kwsh jobs intermittently stopping again after Ctrl-Z followed by `bg`, by checking for newer continuation or exit events before propagating a child stop report.
|
|
131
|
+
- Kept terminal transcript image attachments badge-only to prevent misplaced graphics during scrolling and redraws, while preserving `/files` image previews and model image input.
|
|
132
|
+
- Displayed Codex commentary as assistant speech instead of reasoning in live CLI/TUI, RPC, and Pan output and restored CLI/RPC transcripts, without folding it into the final answer.
|
|
133
|
+
- Avoided double-counting cached input when deriving token totals, and normalized separately reported Anthropic cache tokens into inclusive input counts for cache-hit rates.
|
|
134
|
+
- Fixed OpenRouter proxy Chat Completions failing while adapting Kward's symbol-keyed model messages.
|
|
135
|
+
- Kept the active tab visible in the composer tab bar when tabs overflow, with indicators for hidden tabs.
|
|
136
|
+
|
|
7
137
|
## [0.85.0] - 2026-10-05
|
|
8
138
|
|
|
9
139
|
### Added
|
data/CONTRIBUTING.md
CHANGED
|
@@ -23,7 +23,7 @@ Run the CLI from the checkout with:
|
|
|
23
23
|
|
|
24
24
|
```bash
|
|
25
25
|
ruby lib/main.rb
|
|
26
|
-
ruby lib/main.rb "Explain this project"
|
|
26
|
+
ruby lib/main.rb prompt "Explain this project"
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
See [Platform support](doc/platform-support.md) for operating-system and terminal expectations.
|
data/Gemfile.lock
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
PATH
|
|
2
2
|
remote: .
|
|
3
3
|
specs:
|
|
4
|
-
kward (0.
|
|
4
|
+
kward (0.86.0)
|
|
5
5
|
base64
|
|
6
|
+
fiddle
|
|
6
7
|
nokogiri
|
|
7
8
|
tiktoken_ruby
|
|
8
9
|
tty-cursor
|
|
@@ -10,6 +11,7 @@ PATH
|
|
|
10
11
|
tty-reader
|
|
11
12
|
tty-screen
|
|
12
13
|
unicode-display_width
|
|
14
|
+
webrick
|
|
13
15
|
|
|
14
16
|
GEM
|
|
15
17
|
remote: https://rubygems.org/
|
|
@@ -43,6 +45,7 @@ GEM
|
|
|
43
45
|
fiber-local (1.1.0)
|
|
44
46
|
fiber-storage
|
|
45
47
|
fiber-storage (1.0.1)
|
|
48
|
+
fiddle (1.1.8)
|
|
46
49
|
hashery (2.1.2)
|
|
47
50
|
html-proofer (5.2.1)
|
|
48
51
|
addressable (~> 2.3)
|
|
@@ -146,11 +149,12 @@ CHECKSUMS
|
|
|
146
149
|
fiber-annotation (0.2.0) sha256=7abfadf1d119f508867d4103bf231c0354d019cc39a5738945dec2edadaf6c03
|
|
147
150
|
fiber-local (1.1.0) sha256=c885f94f210fb9b05737de65d511136ea602e00c5105953748aa0f8793489f06
|
|
148
151
|
fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
|
|
152
|
+
fiddle (1.1.8) sha256=7fa8ee3627271497f3add5503acdbc3f40b32f610fc1cf49634f083ef3f32eee
|
|
149
153
|
hashery (2.1.2) sha256=d239cc2310401903f6b79d458c2bbef5bf74c46f3f974ae9c1061fb74a404862
|
|
150
154
|
html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
|
|
151
155
|
io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
|
|
152
156
|
json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
|
|
153
|
-
kward (0.
|
|
157
|
+
kward (0.86.0)
|
|
154
158
|
logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
|
|
155
159
|
metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
|
|
156
160
|
minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
|
data/README.md
CHANGED
|
@@ -51,8 +51,8 @@ kward login # sign in or save provider credentials
|
|
|
51
51
|
kward # start an interactive chat
|
|
52
52
|
kward help # show available commands and examples
|
|
53
53
|
kward hooks doctor # inspect lifecycle hook setup
|
|
54
|
-
kward "Explain this project" # run one prompt and exit
|
|
55
|
-
kward --working-directory ~/code/project "Explain this project"
|
|
54
|
+
kward prompt "Explain this project" # run one prompt and exit
|
|
55
|
+
kward --working-directory ~/code/project prompt "Explain this project"
|
|
56
56
|
```
|
|
57
57
|
|
|
58
58
|
From inside Kward, `/login` lets you choose API-key or subscription authentication across supported providers. `/model` then switches providers, refreshes model catalogs, or accepts a manual model/deployment ID. Direct OpenAI API credentials and ChatGPT/Codex OAuth can coexist.
|
|
@@ -95,7 +95,7 @@ Everyday workflows:
|
|
|
95
95
|
- [Project files](doc/files.md): browse, search, mention, open, and edit workspace files.
|
|
96
96
|
- [Integrated editor](doc/editor.md): open files from the shell or composer, edit in-place, and choose editor keybindings.
|
|
97
97
|
- [Git](doc/git.md): review changes, use the diff viewer, stage files, and commit from the interactive TUI.
|
|
98
|
-
- [Shell](doc/shell.md): use `/shell
|
|
98
|
+
- [Shell](doc/shell.md): run `kward shell` for a standalone shell without logging in, or use `/shell` for the embedded shell with per-tab state. In either shell, start a line with `?` to ask the agent about your last command.
|
|
99
99
|
- [Memory](doc/memory.md): opt-in core, soft, and session memory.
|
|
100
100
|
- [Personas](doc/personas.md): configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
|
|
101
101
|
- [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
|
data/Rakefile
CHANGED
|
@@ -93,7 +93,10 @@ def verify_public_api_docs
|
|
|
93
93
|
required_links = [
|
|
94
94
|
"Kward.html#plugin-class_method",
|
|
95
95
|
"Kward/PluginRegistry/DSL.html",
|
|
96
|
+
"Kward/PluginRegistry/DSL.html#startup_option-instance_method",
|
|
96
97
|
"Kward/PluginRegistry/Context.html",
|
|
98
|
+
"Kward/PluginHTTPServer.html",
|
|
99
|
+
"Kward/PluginCodexResponses.html",
|
|
97
100
|
"Kward/Tools/Base.html",
|
|
98
101
|
"Kward/ToolRegistry.html",
|
|
99
102
|
"Kward/RPC/Server.html",
|
data/doc/agent-tools.md
CHANGED
|
@@ -18,10 +18,20 @@ Tools also enforce important boundaries:
|
|
|
18
18
|
| Shell prompt tools | `run_shell_command`, `prepare_shell_command` (available only to the transient `?` shell assistant) | [Embedded shell](shell.md) |
|
|
19
19
|
| Web tools | `web_search`, `fetch_content`, `fetch_raw` | [Web search](web-search.md) |
|
|
20
20
|
| Code search | `code_search` | [Code search](code-search.md) |
|
|
21
|
+
| Date/time | `datetime` | Current time and timestamp arithmetic (details below) |
|
|
21
22
|
| Context and interaction tools | `read_skill`, `retrieve_tool_output`, `ask_user_question` | [Context tools](context-tools.md) |
|
|
22
23
|
| Decision tools | `typesafe_evaluate` when `TYPESAFE_API_KEY` is configured | [TypeSafe](#TypeSafe_evaluation) |
|
|
23
24
|
| Plugin tools | Trusted local integrations registered by installed plugins | [Plugins](plugins.md#Add_a_model_callable_tool) |
|
|
24
25
|
|
|
26
|
+
## Date and time
|
|
27
|
+
|
|
28
|
+
The `datetime` tool supports two operations:
|
|
29
|
+
|
|
30
|
+
- `current_time` returns the current date and time in the host's local timezone by default. Supply `timezone_offset` as `Z` or an ISO 8601 UTC offset such as `-05:00` to request a fixed offset.
|
|
31
|
+
- `add_seconds` accepts an ISO 8601 `timestamp` with an explicit offset and a signed integer `seconds` value, then returns the adjusted timestamp while preserving that offset.
|
|
32
|
+
|
|
33
|
+
UTC offsets are fixed offsets, not named timezones; they do not apply daylight-saving transitions.
|
|
34
|
+
|
|
25
35
|
## How tools save tokens
|
|
26
36
|
|
|
27
37
|
Kward tries to gather enough evidence without flooding the conversation. It usually starts with focused context tools, then moves from outlines and previews to exact ranges or full files only when needed:
|
|
@@ -47,6 +57,7 @@ See [Context budgeting](context-budgeting.md) for the full compaction strategy,
|
|
|
47
57
|
- `ask_user_question` is advertised only when the frontend can display structured questions,
|
|
48
58
|
- `typesafe_evaluate` is advertised only in normal turns when `TYPESAFE_API_KEY` is configured,
|
|
49
59
|
- plugin tools are advertised in normal agent turns and remain subject to execution profiles and permission policy.
|
|
60
|
+
- `datetime` is available in normal agent turns and remains subject to the configured tool permission policy.
|
|
50
61
|
|
|
51
62
|
### TypeSafe evaluation
|
|
52
63
|
|
data/doc/api.md
CHANGED
|
@@ -15,7 +15,7 @@ If you use Kward from the terminal, start with the [user guides](file.README.htm
|
|
|
15
15
|
|
|
16
16
|
### Plugin authors
|
|
17
17
|
|
|
18
|
-
Use plugins when you need trusted local Ruby code for typed commands and actions, model-callable tools, prompt context, footer UI, transcript events, plugin-owned chats, or
|
|
18
|
+
Use plugins when you need trusted local Ruby code for typed commands and actions, model-callable tools, prompt context, footer UI, transcript events, plugin-owned chats, external transports, or managed local HTTP and provider access.
|
|
19
19
|
|
|
20
20
|
Session commands can stage a host-owned model response with
|
|
21
21
|
`ctx.request_turn(system: text)`; check `ctx.turn_requests_supported?` before
|
|
@@ -36,7 +36,10 @@ Generated entry points:
|
|
|
36
36
|
- [`Kward::PluginCommand`](Kward/PluginCommand.html)
|
|
37
37
|
- [`Kward::PluginAction`](Kward/PluginAction.html)
|
|
38
38
|
- [`Kward::PluginResult`](Kward/PluginResult.html)
|
|
39
|
+
- [`Kward::PluginRegistry::DSL#startup_option`](Kward/PluginRegistry/DSL.html#startup_option-instance_method)
|
|
39
40
|
- [`Kward::PluginHost`](Kward/PluginHost.html)
|
|
41
|
+
- [`Kward::PluginHTTPServer`](Kward/PluginHTTPServer.html)
|
|
42
|
+
- [`Kward::PluginCodexResponses`](Kward/PluginCodexResponses.html)
|
|
40
43
|
- [`Kward::PluginStore`](Kward/PluginStore.html)
|
|
41
44
|
- [`Kward::PluginScopedStore`](Kward/PluginScopedStore.html)
|
|
42
45
|
- [`Kward::PluginChatCapabilities`](Kward/PluginChatCapabilities.html)
|
data/doc/composer.md
CHANGED
|
@@ -40,6 +40,7 @@ The composer supports familiar line-editing keys:
|
|
|
40
40
|
| `Ctrl+Y` | Yank the most recently killed composer text |
|
|
41
41
|
| `Ctrl+L` | Redraw the terminal UI and remove transient current-view output |
|
|
42
42
|
| `Ctrl+D` | Delete at the cursor, or exit when the composer is empty |
|
|
43
|
+
| `Ctrl+N` | Start a new conversation in the current tab, just like `/new`; discards the current draft |
|
|
43
44
|
|
|
44
45
|
These are composer bindings. The integrated editor, shell, Git view, file browser, and plugin interfaces have their own keymaps.
|
|
45
46
|
|
|
@@ -127,11 +128,11 @@ Tab follows the normal completion behavior:
|
|
|
127
128
|
|
|
128
129
|
`Ctrl+Tab` and `Ctrl+Shift+Tab` switch conversations when your terminal reports those keys. Additional shortcuts depend on `composer.tab_keybindings`:
|
|
129
130
|
|
|
130
|
-
- `ctrl`: `Ctrl+T` creates a tab, `Ctrl+W` closes one, and reported `Ctrl+1` through `Ctrl+9` select numbered tabs.
|
|
131
|
+
- `ctrl`: `Ctrl+T` creates a tab at the end, `Ctrl+Shift+T` creates one immediately to the right of the current tab if your terminal reports it, `Ctrl+W` closes one, and reported `Ctrl+1` through `Ctrl+9` select numbered tabs.
|
|
131
132
|
- `alt`: `Alt+T` creates a tab, `Alt+Left`/`Alt+Right` move between tabs, and `Alt+1` through `Alt+9` select numbered tabs.
|
|
132
133
|
- `auto`: prefers the Ctrl family on macOS and the Alt family elsewhere.
|
|
133
134
|
|
|
134
|
-
Use `/settings` → Interface → Tab keybindings to change the family. If your terminal intercepts a shortcut, `/tab` commands
|
|
135
|
+
Use `/settings` → Interface → Tab keybindings to change the family. If your terminal intercepts a shortcut, you can use `/tab` commands instead. For example, to open a tab next to the current one, use `/tab new`, then `/tab move <number>` to put it where you want it.
|
|
135
136
|
|
|
136
137
|
See [Tabs](tabs.md) for background work, status colors, persistence, naming, and moving tabs.
|
|
137
138
|
|
|
@@ -186,7 +187,7 @@ Example:
|
|
|
186
187
|
|
|
187
188
|
If the cursor is at the start of an otherwise empty draft, Backspace removes the most recently added pending attachment. Submitting the draft clears its pending attachments.
|
|
188
189
|
|
|
189
|
-
The active model must support image input.
|
|
190
|
+
The active model must support image input. Submitted images appear as attachment badges in the terminal transcript, including restored sessions. Images are still sent to the model; inline graphics are omitted so transcript scrolling and redraws stay reliable. To view an image locally, open it through [`/files`](files.md#Image_previews), which retains image previews on supported iTerm2 and Kitty-compatible terminals.
|
|
190
191
|
|
|
191
192
|
## Understand composer status
|
|
192
193
|
|
data/doc/configuration.md
CHANGED
|
@@ -188,11 +188,11 @@ Use `failure_policy` (`allow`, `warn`, `deny`, or `ask`) to decide what happens
|
|
|
188
188
|
|
|
189
189
|
Project-local hooks can also live in `.kward/hooks.json`, but Kward loads them only after you explicitly run `/hooks trust` in that workspace. Trust is tied to the file digest, so changes require re-trusting. See [Lifecycle hooks](lifecycle-hooks.md) for events, decisions, selectors, plugin hooks, command-hook protocol, workspace trust, and security notes.
|
|
190
190
|
|
|
191
|
-
##
|
|
191
|
+
## Shell configuration
|
|
192
192
|
|
|
193
|
-
|
|
193
|
+
Interactive `kward shell` and the hosted `/shell` both load `~/.kward/kwshrc` and then `~/.kwshrc`, but only the standalone shell **executes** them. When `KWARD_CONFIG_PATH` selects another main config file, Kward looks for the first `kwshrc` beside that file instead. The separate `kwsh` executable and non-interactive `kward shell` do not load these files automatically.
|
|
194
194
|
|
|
195
|
-
|
|
195
|
+
For settings shared with `/shell` and leading-`!` commands, stick to declarative directives:
|
|
196
196
|
|
|
197
197
|
```sh
|
|
198
198
|
alias ll='ls -la'
|
|
@@ -202,11 +202,11 @@ export PATH="$HOME/bin:$PATH"
|
|
|
202
202
|
source ~/.kward/kwsh-aliases
|
|
203
203
|
```
|
|
204
204
|
|
|
205
|
-
|
|
205
|
+
In standalone `kward shell`, you can also write functions, `if` statements, and other native shell code. `source` works like `.`: it executes the file in the current shell, looks up bare names on `PATH`, and resolves paths such as `./other.rc` from the working directory. Load only files you trust. The hosted loader does not execute shell code; it reads only `alias`, `export`, and `source` (or `.`), and it resolves relative includes from the containing rc file. See the [Shell guide](shell.md) for startup examples and how `ENV` fits in.
|
|
206
206
|
|
|
207
207
|
### Shell-agent model
|
|
208
208
|
|
|
209
|
-
|
|
209
|
+
By default, the hosted `/shell` agent uses the active conversation's provider, model, and reasoning effort. The standalone `kward shell` agent starts from Kward's configured selection. Override either default in the main JSON configuration:
|
|
210
210
|
|
|
211
211
|
```json
|
|
212
212
|
{
|
|
@@ -220,9 +220,9 @@ The transient shell assistant normally follows the active conversation's model a
|
|
|
220
220
|
}
|
|
221
221
|
```
|
|
222
222
|
|
|
223
|
-
The optional `provider` selects a different backend for the
|
|
223
|
+
The optional `provider` selects a different backend for the shell agent. Use the lowercase configuration IDs listed in [Model providers](providers.md). If you set an explicit provider but omit the model or reasoning effort, Kward uses that provider's defaults for the omitted settings.
|
|
224
224
|
|
|
225
|
-
Environment variables take precedence over the JSON settings:
|
|
225
|
+
Environment variables exported before launching Kward take precedence over the JSON settings:
|
|
226
226
|
|
|
227
227
|
```sh
|
|
228
228
|
export KWSH_PROVIDER="openrouter"
|
|
@@ -232,9 +232,9 @@ export KWSH_REASONING="none"
|
|
|
232
232
|
|
|
233
233
|
`KWSH_PROVIDER` selects the shell-agent provider, `KWSH_MODE` selects its model, and `KWSH_REASONING` selects its reasoning effort. Empty values are ignored.
|
|
234
234
|
|
|
235
|
-
|
|
235
|
+
The declarative exports read by `/shell` and leading-`!` commands support shell quoting and simple `$VAR`/`${VAR}` expansion. Invalid variable names are ignored. The hosted shell applies these exports after Kward’s conservative color defaults and keeps one persistent local shell process per tab.
|
|
236
236
|
|
|
237
|
-
`alias
|
|
237
|
+
`alias ll='ls -la'` makes `ll lib` run `ls -la lib`. Configured aliases are available in `kward shell`, `/shell`, and after the normal composer’s `!` prefix, including command-name Tab completion. Native aliases expand at parse time; the one-off `!` path replaces only the initial command name. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `kwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current shell session and are not available to `!command` input.
|
|
238
238
|
|
|
239
239
|
## Provider and model settings
|
|
240
240
|
|
|
@@ -284,7 +284,7 @@ Model settings:
|
|
|
284
284
|
|
|
285
285
|
`model` is a legacy generic fallback. Provider-specific values take precedence. Catalog providers use `<runtime-id>_model`; for example, direct OpenAI uses `openai_api_model`, Gemini uses `gemini_model`, and Groq uses `groq_model`. Codex keeps `openai_model`. `reasoning_effort` and `thinking_level` are generic reasoning settings. `thinking_level` is an alias for `reasoning_effort` honored by all providers. For each provider, Kward resolves reasoning in this order: the provider-specific key (for example `openai_reasoning_effort`), then the generic `reasoning_effort`, then `thinking_level`, then the default `medium`. `openai_reasoning_effort`, `anthropic_reasoning_effort`, `openrouter_reasoning_effort`, and `copilot_reasoning_effort` are provider-specific forms.
|
|
286
286
|
|
|
287
|
-
OpenAI-hosted models do not expose their raw reasoning tokens. Kward displays
|
|
287
|
+
OpenAI-hosted models do not expose their raw reasoning tokens. Kward displays their reasoning summaries as reasoning, and visible Codex commentary (progress updates addressed to you) as assistant speech, including when restoring a session. Set `codex_show_raw_reasoning` to `true` only for a backend that emits raw Codex `reasoning_text`; it defaults to `false` because raw reasoning can include internal or unstable model output.
|
|
288
288
|
|
|
289
289
|
`stream_idle_timeout_seconds` limits how long a streamed Codex, Anthropic, or Local response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
|
|
290
290
|
|
|
@@ -296,7 +296,7 @@ Defaults:
|
|
|
296
296
|
- Copilot: `gpt-5-mini`
|
|
297
297
|
- Reasoning effort: `medium`
|
|
298
298
|
|
|
299
|
-
The
|
|
299
|
+
The Codex model choices include `gpt-6.2-astra`, `gpt-6.2-sol`, and `gpt-6.1-terra`. These models have a 1,050,000-token context window. GPT-6.2 Astra and Sol support `low`, `medium`, `high`, `xhigh`, and `max` reasoning effort; they do not support `none`. GPT-6.1 Terra also supports `none`. Model availability depends on account access.
|
|
300
300
|
|
|
301
301
|
The Anthropic model choices include `claude-fable-5`, `claude-opus-5`, and `claude-sonnet-5`. Fable and Opus availability depends on the logged-in account and organization. Selecting a model without access returns an Anthropic provider error. Kward keeps Sonnet 5 as its default because it supports both Pro and Max subscriptions; select Opus 5 explicitly when it is available on the account.
|
|
302
302
|
|
|
@@ -429,6 +429,55 @@ In the normal composer prompt, choose reasoning effort with `/reasoning` or `/mo
|
|
|
429
429
|
|
|
430
430
|
`auto` (default) detects terminal support, `ctrl` uses `Ctrl+Tab`/`Shift+Tab` to cycle suggestions and indent, `alt` uses `Alt+Tab` for terminals where `Ctrl+Tab` is swallowed.
|
|
431
431
|
|
|
432
|
+
## Transcript turn statistics
|
|
433
|
+
|
|
434
|
+
By default, each agent turn ends with a compact summary:
|
|
435
|
+
|
|
436
|
+
```text
|
|
437
|
+
Completed · 18.4s · 24.8k tokens · 4 tool calls
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Set `transcript.turn_stats` in `config.json` to `compact` (default), `detailed`,
|
|
441
|
+
or `off`:
|
|
442
|
+
|
|
443
|
+
```json
|
|
444
|
+
{
|
|
445
|
+
"transcript": {
|
|
446
|
+
"turn_stats": "detailed"
|
|
447
|
+
}
|
|
448
|
+
}
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
Detailed mode adds the number of model requests and an input/output token
|
|
452
|
+
breakdown, plus cached input, reasoning tokens, and cache writes when reported:
|
|
453
|
+
|
|
454
|
+
```text
|
|
455
|
+
Completed · 18.4s · 24.8k tokens · 3 model requests · 4 tool calls
|
|
456
|
+
Input 23.6k · Cached 20.0k (85%) · Output 1.2k · Reasoning 800
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
The cache-hit percentage uses total cached input divided by total input across
|
|
460
|
+
the turn, not an average of individual request percentages. Missing details are
|
|
461
|
+
omitted; explicitly reported zeroes are shown. If only some requests report a
|
|
462
|
+
field, its subtotal is marked `(partial)`. A cache-hit percentage is shown only
|
|
463
|
+
when both input and cache counts cover the complete turn and input is nonzero.
|
|
464
|
+
Cached tokens and cache writes are input breakdowns; reasoning tokens are part
|
|
465
|
+
of output. They are not added to total usage again. Availability depends on the
|
|
466
|
+
provider, endpoint, and model; the Codex subscription endpoint may report fewer
|
|
467
|
+
fields than the public OpenAI API.
|
|
468
|
+
|
|
469
|
+
Narrow terminals drop secondary fields rather than wrapping the summary. Invalid or missing values use `compact`. There is no dedicated
|
|
470
|
+
environment override; `KWARD_CONFIG_PATH` selects the configuration file as usual.
|
|
471
|
+
|
|
472
|
+
This preference controls CLI/TUI, Pan, and Markdown/HTML export presentation.
|
|
473
|
+
Stats are still saved and available as structured RPC data when display is off;
|
|
474
|
+
RPC clients own their rendering. Pan reads the preference when its server starts.
|
|
475
|
+
Filter mode keeps stdout answer-only. Editor/shell prompts and plugin-owned chats
|
|
476
|
+
do not automatically display these summaries.
|
|
477
|
+
|
|
478
|
+
See [turn statistics](session-management.md#Turn_statistics) for what the counts
|
|
479
|
+
include and how incomplete provider usage is shown.
|
|
480
|
+
|
|
432
481
|
## Editor settings
|
|
433
482
|
|
|
434
483
|
The built-in TUI file editor supports three keybinding modes. Modern is the default:
|
data/doc/extensibility.md
CHANGED
|
@@ -68,6 +68,8 @@ Use `AGENTS.md` for project facts and engineering rules. Do not put personality
|
|
|
68
68
|
|
|
69
69
|
By default, Kward adds a compact instruction telling the model that `AGENTS.md` exists and should be read when relevant. Set `enforce_workspace_agents_file: true` only if you want the full file injected every time. See [Configuration](configuration.md) for details.
|
|
70
70
|
|
|
71
|
+
The transient `?` assistant inside `/shell` has its own scoped instructions and uses the [native kwsh scripting subset](shell.md). It knows which syntax is unsupported and must not silently invoke Bash or another shell to work around those limits. This does not change the normal agent's shell tools or skill activation.
|
|
72
|
+
|
|
71
73
|
## Prompt templates
|
|
72
74
|
|
|
73
75
|
Use prompt templates when you repeatedly type the same kind of request. Each Markdown file in `~/.kward/prompts/` becomes a slash command; its filename is the command name and `$ARGUMENTS` expands the text after the command.
|
data/doc/getting-started.md
CHANGED
|
@@ -101,16 +101,16 @@ The composer footer highlights the two main discovery shortcuts: type `/` to bro
|
|
|
101
101
|
|
|
102
102
|
## Ask one question and exit
|
|
103
103
|
|
|
104
|
-
For quick tasks,
|
|
104
|
+
For quick tasks, use the explicit `prompt` command. This keeps a misspelled command from being sent to the model by accident:
|
|
105
105
|
|
|
106
106
|
```bash
|
|
107
|
-
kward "Explain this project"
|
|
107
|
+
kward prompt "Explain this project"
|
|
108
108
|
```
|
|
109
109
|
|
|
110
110
|
Review a diff:
|
|
111
111
|
|
|
112
112
|
```bash
|
|
113
|
-
git diff | kward "Review this diff for bugs"
|
|
113
|
+
git diff | kward prompt "Review this diff for bugs"
|
|
114
114
|
```
|
|
115
115
|
|
|
116
116
|
One-shot prompts do not use Kward memory.
|
data/doc/git.md
CHANGED
|
@@ -127,5 +127,5 @@ Selecting `origin` does not add a separate approval prompt; the normal configure
|
|
|
127
127
|
For AI-assisted review without committing, you can still pipe a diff into a one-shot prompt:
|
|
128
128
|
|
|
129
129
|
```bash
|
|
130
|
-
git diff | kward "Review this diff"
|
|
130
|
+
git diff | kward prompt "Review this diff"
|
|
131
131
|
```
|
data/doc/memory.md
CHANGED
|
@@ -11,7 +11,7 @@ Use memory when you keep telling Kward the same things:
|
|
|
11
11
|
|
|
12
12
|
Leave memory off when every session should start clean.
|
|
13
13
|
|
|
14
|
-
Memory is not used for one-shot prompts such as `kward "..."`.
|
|
14
|
+
Memory is not used for one-shot prompts such as `kward prompt "..."`.
|
|
15
15
|
|
|
16
16
|
## Enable memory
|
|
17
17
|
|
data/doc/plugins.md
CHANGED
|
@@ -22,7 +22,7 @@ Plugins run inside the Kward process with your user permissions. Install only pl
|
|
|
22
22
|
| Repository rules | `AGENTS.md` |
|
|
23
23
|
| Local Ruby code or integration | plugin |
|
|
24
24
|
|
|
25
|
-
See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations.
|
|
25
|
+
See [Extensibility](extensibility.md) for the full overview of Kward's extension points and prompt assembly order. See [Transports](transports.md) for external messaging and event integrations. The [OpenRouter proxy example guide](https://github.com/kaiwood/kward/blob/main/examples/plugins/openrouter_proxy/README.md) documents its startup option, managed HTTP listener, and local fake embeddings.
|
|
26
26
|
|
|
27
27
|
## Where plugins live
|
|
28
28
|
|
|
@@ -162,6 +162,21 @@ an optional parent token with `cancellation:`.
|
|
|
162
162
|
for automatic cleanup. `host.manage` is an alias. Cleanup runs in reverse
|
|
163
163
|
registration order so dependent resources unwind predictably.
|
|
164
164
|
|
|
165
|
+
`host.http_server` creates a loopback-only managed HTTP listener. It defaults to
|
|
166
|
+
an ephemeral port, a 1 MiB maximum request size, a 30-second request timeout,
|
|
167
|
+
and eight clients. Pass an explicit port when a local application needs a stable
|
|
168
|
+
address. Start the server with `server.start`, inspect `server.port`, wait with
|
|
169
|
+
`server.wait`, and stop it with `server.stop`; plugin cleanup stops it
|
|
170
|
+
automatically. The handler receives WEBrick's request and response objects.
|
|
171
|
+
|
|
172
|
+
`host.codex_responses.stream(model:, input:, instructions: nil, text: nil)`
|
|
173
|
+
streams Responses-shaped events through Kward's normal Codex provider client,
|
|
174
|
+
using the configured Codex credentials and account context. It never returns the
|
|
175
|
+
authentication token. The caller should handle failed or incomplete turns. This
|
|
176
|
+
uses Kward's existing private Codex backend route and is coupled to that
|
|
177
|
+
undocumented endpoint; prefer it only when matching normal Kward Codex behavior
|
|
178
|
+
is required. Do not read Kward's auth files directly.
|
|
179
|
+
|
|
165
180
|
Plugin-owned tab hosts expose the same `background`, `on_cleanup`, and `manage`
|
|
166
181
|
methods. Their resources are cleaned up when a local tab closes or its shared
|
|
167
182
|
plugin-chat runtime shuts down. A tab driver may implement `close` (or `shutdown`
|
|
@@ -172,6 +187,25 @@ Do not open network connections or start threads directly while the plugin file
|
|
|
172
187
|
is loading. Register them from `on_start`, a command, or a plugin-tab factory so
|
|
173
188
|
Kward can own their lifetime.
|
|
174
189
|
|
|
190
|
+
## Add a top-level startup option
|
|
191
|
+
|
|
192
|
+
Identified plugins can declare a no-argument switch for a foreground CLI mode:
|
|
193
|
+
|
|
194
|
+
```ruby
|
|
195
|
+
Kward.plugin(id: "com.example.server", version: "1.0.0", api: 1) do |plugin|
|
|
196
|
+
plugin.startup_option("--example-server", description: "Run the example server") do |host|
|
|
197
|
+
ExampleServer.new(host).run
|
|
198
|
+
end
|
|
199
|
+
end
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The handler is called only when the user selects the option. Kward loads plugin
|
|
203
|
+
registrations to identify plugin-owned switches before normal command dispatch,
|
|
204
|
+
but does not start lifecycle callbacks or run the handler unless the mode is
|
|
205
|
+
selected. A startup option cannot be combined with a prompt or another startup
|
|
206
|
+
option. Keep loading code side-effect-free; the handler should own the selected
|
|
207
|
+
foreground mode and return when it stops.
|
|
208
|
+
|
|
175
209
|
## Add a slash command
|
|
176
210
|
|
|
177
211
|
Use plugin commands for local actions that should not call the model.
|
|
@@ -534,7 +568,7 @@ Kward.plugin do |plugin|
|
|
|
534
568
|
ui.put(0, x, "X", :red)
|
|
535
569
|
x = (x + 1) % ui.width
|
|
536
570
|
key = ui.poll_key
|
|
537
|
-
|
|
571
|
+
next :exit if key == "q"
|
|
538
572
|
ui.render
|
|
539
573
|
end
|
|
540
574
|
end
|
|
@@ -562,8 +596,9 @@ The `ui` controller object passed to the handler block exposes:
|
|
|
562
596
|
| `fps` | Target frame rate |
|
|
563
597
|
|
|
564
598
|
Keys are returned as symbols (`:left`, `:right`, `:up`, `:down`, `:return`,
|
|
565
|
-
`:backspace`, `:space`, `:pageup`, `:pagedown`) or raw strings for keys
|
|
566
|
-
without a named mapping.
|
|
599
|
+
`:backspace`, `:space`, `:pageup`, `:pagedown`, `:ctrl_c`) or raw strings for keys
|
|
600
|
+
without a named mapping. Kward exits on plain Esc. To add a quit key such as `q`
|
|
601
|
+
or Ctrl+C, handle it in the tick callback and call `ui.exit` or return `:exit`.
|
|
567
602
|
|
|
568
603
|
The tick callback runs at the configured frame rate (1–120 fps, default 30).
|
|
569
604
|
Calls to `put` and `clear_frame` stage canvas changes; call `render` after the
|
|
@@ -577,7 +612,7 @@ Returning `:exit` from the tick callback ends the loop, same as calling
|
|
|
577
612
|
cursor, and transcript viewport).
|
|
578
613
|
- Interactive mode is a distinct state from the busy-input spinner lifecycle —
|
|
579
614
|
no spinner or busy chrome is shown.
|
|
580
|
-
-
|
|
615
|
+
- Plain Esc, the plugin calling `exit`, or the tick callback returning `:exit`
|
|
581
616
|
all exit cleanly and restore the prior composer state.
|
|
582
617
|
- Resize during interactive mode forces a clean exit and restore.
|
|
583
618
|
|