kward 0.71.0 → 0.73.0

data/doc/rpc.md

@@ -6,6 +6,8 @@ Kward RPC is an experimental backend protocol for UI clients. It is versioned as
 
 This page is for people building UI clients or integrations. If you use Kward from the terminal, you can skip it.
 
+Prompt history search is a CLI terminal feature only. RPC clients own their composer/input UX and Kward does not currently expose prompt-history read, append, or search methods over RPC.
+
 ## Launch
 
 ```bash
@@ -48,14 +50,14 @@ Result fields:
 Detailed capability fields include:
 
 - `transcript`: Tauren transcript format support, including normalized messages, image/tool support, compaction summaries, and restored assistant reasoning as Pi-compatible `thinking` content blocks.
-- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, supported linear-session fork methods, supported compaction, and explicit unsupported import/tree/update features.
+- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, explicit unsupported import support, and unsupported live session updates reported with `notification: "session/updated"`.
 - `turns`: async turn mode, per-session concurrency, provider-gated native busy-input steering, queued follow-up input, best-effort cancellation, and recent in-memory event replay behavior.
-- `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, diff result support, configured workspace guardrail status, and explicit unsupported shell changed-file detection/session update flags.
+- `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, diff result support, configured workspace guardrail status, focused context and context-budget stats tool support, and explicit unsupported shell changed-file detection/session update flags.
 - `attachments`: supported input attachment contract for `turns/start`, with accepted base64 image MIME types and a stable max byte value.
 - `models`: model/reasoning RPC methods, explicit OpenRouter catalog listing, exposed model fields, and no scoped model support.
 - `runtime`: supported state/stats methods with message-count stats and OpenAI/Codex context usage. Cumulative token and cost stats are not computed.
 - `runtimeSettings`: live `runtime/updateSetting` support for `defaultModel` and `defaultThinkingLevel`, plus `runtime/reload`.
-- `auth`: Tauren auth provider format, OpenAI and Anthropic OAuth, OpenRouter API-key login, and provider logout for stored credentials.
+- `auth`: Tauren auth provider format, OpenAI and Anthropic OAuth, OpenRouter API-key login, GitHub/Copilot status reporting, and provider logout for stored credentials. GitHub OAuth login is CLI-only; RPC reports `supported: false` for the GitHub provider with a reason string.
 - `memory`: opt-in structured memory support, interactive prompt injection only, JSON/JSONL local storage, and dedicated `memory/*` methods.
 - `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
@@ -63,6 +65,10 @@ Detailed capability fields include:
 - `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access.
 - `security`: trusted-local behavior; no workspace mutation guard or tool approval, shell/file mutation can run. File-tool workspace guardrails are reported under `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
+- `workers`: experimental agent worker pipeline. Reports `supported: false` by default; set to `supported: true` with `methods: ["workers/list", "workers/show"]` when Kward is launched with `--experimental-workers`.
+- `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
+- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell` is the local embedded TUI shell.
+- `logging`: local redacted telemetry logging support, the log directory, enabled categories, `methods: ["logging/stats", "logging/tokenCsv"]`, `usageCsv` sub-capability with bucket support, JSONL format, rotation (10 MB, manual retention), config key `logging`, env prefix `KWARD_LOGGING`, and redacted-metadata-only content.
 
 ### `shutdown`
 
@@ -217,6 +223,37 @@ Closes the RPC session. Empty unnamed session files may be cleaned up.
 
 Returns session metadata and full conversation messages. Assistant `reasoning_summary` values and existing `thinking`/`reasoning` content parts are restored as normalized `{ "type": "thinking", "thinking": "..." }` blocks before assistant text; reasoning is not merged into normal text blocks.
 
+### `sessions/tree`
+
+Params:
+
+- `sessionId`
+
+Returns the full branching session tree as flattened Tauren-compatible rows (`tauren-tree-items-v1`). Each row includes `entryId`, `parentId`, `role`, `text` (compact display text), `current` (whether it is the active leaf), `depth`, `isLast`, `ancestorContinues`, `activePath`, `selectable`, `label`, `labelTimestamp`, and `prefix` (tree-drawing connector string). User-message entries are selectable; assistant/tool entries are not.
+
+### `sessions/tree/setLabel`
+
+Params:
+
+- `sessionId`
+- `entryId`
+- `label`: optional display label override for the entry.
+
+Persists a label override for one tree entry and returns `{ "ok": true }`.
+
+### `sessions/tree/navigate`
+
+Params:
+
+- `sessionId`
+- `entryId`: a selectable entry ID from `sessions/tree`.
+- `summarize`: optional boolean; when true, Kward summarizes the abandoned branch before moving.
+- `customInstructions`: optional additional guidance for the summarizer.
+
+Moves the active branch to the selected tree entry. If the entry is a user message, its parent becomes the new active leaf and the user message text is returned as `editorText` so clients can place it into the composer for editing/resubmission. When `summarize` is true, a branch summary is generated and appended to the session before moving.
+
+Returns `{ "session": {}, "editorText": "...", "cancelled": false, "aborted": false }`. Fields with no value are omitted.
+
 ## Turn methods
 
 Turns are asynchronous. A session queues turns sequentially; only one turn runs per session at a time.
@@ -276,6 +313,7 @@ Known event types:
 
 - `turnQueued`
 - `turnSteered`
+- `steeringApplied`
 - `turnStarted`
 - `reasoningDelta`
 - `assistantDelta`
@@ -292,6 +330,8 @@ Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFi
 
 `modelRetry` is emitted before Kward retries a transient model request failure. Its payload includes `provider`, `model`, `attempt`, `maxAttempts`, `delaySeconds`, and `error`.
 
+`steeringApplied` is emitted after queued steering input has been appended to conversation context. Its payload includes `count`, the number of steering messages applied.
+
 `toolCall` and `toolResult` payloads include canonical Tauren-normalized fields:
 
 - `toolCallId`: tool call ID.
@@ -365,7 +405,7 @@ Params:
 
 - `sessionId`: active RPC session ID.
 - `settingId`: currently `defaultModel` or `defaultThinkingLevel`.
-- `value`: setting value. `defaultModel` accepts `Provider/model-id` and preserves slashes after the provider separator.
+- `value`: setting value. `defaultModel` accepts a structured object such as `{ "provider": "OpenRouter", "model": "anthropic/claude-sonnet-4.5" }`. For compatibility, it also accepts `Provider/model-id` strings and preserves slashes after the provider separator.
 
 Applies the setting live by updating config and refreshing client config. Unsupported setting IDs are rejected.
 
@@ -379,7 +419,7 @@ Refreshes config-backed runtime state and returns `{ "ok": true, "message": "Res
 
 ## Logging methods
 
-The `logging` capability reports local redacted telemetry logging support, the log directory, enabled categories, and `methods: ["logging/stats"]`. Logging stats require logging to be enabled by config or environment for at least one category.
+The `logging` capability reports local redacted telemetry logging support, the log directory, enabled categories, `methods: ["logging/stats", "logging/tokenCsv"]`, `usageCsv` sub-capability with bucket support, JSONL format with 10 MB rotation and manual retention, config key `logging`, env prefix `KWARD_LOGGING`, and redacted-metadata-only content. Logging methods require logging to be enabled by config or environment for at least one category.
 
 ### `logging/stats`
 
@@ -391,6 +431,15 @@ Accepted units are minutes, hours, days, weeks, months, and years. Ranges use UT
 
 Returns structured stats for enabled categories only, including the requested range, log directory, record counts by category/event, `usageStats` token totals, performance duration summaries, tool call summaries, and error counts by event/class/provider/code. Error messages are not included in the stats response.
 
+### `logging/tokenCsv`
+
+Params:
+
+- `range`: optional duration string; defaults to `1 week`.
+- `bucket`: optional aggregation bucket: `second`, `minute`, `hour`, `day`, `week`, `month`, or `year`.
+
+Returns `{ "csv": "..." }` with token usage data as CSV. Accepted range units and calendar-period behavior match `logging/stats`. This is the RPC equivalent of `kward stats tokens`.
+
 ## Memory methods
 
 Memory is disabled by default. Auto-summary is also disabled by default. RPC memory methods operate on the same local storage as the CLI: `<config-dir>/memory/core.json`, `<config-dir>/memory/soft.jsonl`, and `<config-dir>/memory/events.jsonl`. Retrieved memory is injected only for normal session turns when memory is enabled.
@@ -639,6 +688,27 @@ Completes the login using the submitted code.
 
 Returns login status for a login ID.
 
+## Worker methods (experimental)
+
+Worker methods are available only when Kward is launched with `--experimental-workers`. The `workers` capability reports `supported: false` by default and `supported: true` with `methods: ["workers/list", "workers/show"]` when the flag is active.
+
+### `workers/list`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+
+Returns the list of agent workers for the session.
+
+### `workers/show`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+- `workerId`: worker ID.
+
+Returns details for a specific worker.
+
 ## Security and privacy notes
 
 - RPC is intended for a trusted local UI and can read/write files, run shell commands, update secrets, and use OAuth.

data/doc/session-management.md

@@ -23,6 +23,8 @@ cd ~/code/project
 kward
 ```
 
+To automatically resume the last active session for the current workspace on startup, enable `sessions.auto_resume` in your config — see [Configuration](configuration.md). When auto-resume is off (the default), Kward starts fresh each time and you can resume earlier work with `/sessions`.
+
 ## A normal session workflow
 
 Start a chat and give it a useful name:
@@ -31,6 +33,8 @@ Start a chat and give it a useful name:
 /rename oauth cleanup
 ```
 
+`/rename` requires a name. Use `/name` without an argument to clear the current session name.
+
 Work normally:
 
 ```text
@@ -71,10 +75,12 @@ Inside the picker you can:
 | `r` | rename the highlighted session. |
 | `c` | clone the highlighted session. |
 | `f` | fork the highlighted session from an earlier prompt. |
-| `d d` | delete the highlighted session after confirmation. |
+| `d` | start deleting the highlighted session. Press `d` again to confirm, or `Esc` to cancel. |
 
 Use names generously. A session named `oauth cleanup` or `release checklist` is much easier to find later than a timestamp.
 
+Deleted sessions are moved to your OS trash or recycle bin when a supported platform tool is available (Finder on macOS, `gio trash` or `trash-put` on Linux, Recycle Bin on Windows). If no trash tool is found, the session file is permanently deleted. You can recover accidentally deleted sessions from your trash.
+
 ## Clone a session
 
 Clone when you want an exact copy of the current conversation and then continue in a separate branch.
@@ -185,6 +191,17 @@ After compaction, Kward may need to re-read files before editing them again. Tha
 
 Compaction is also context management. It trades detailed old conversation for a concise working summary so Kward can spend tokens on the next task.
 
+## Copy session text to the clipboard
+
+Use `/copy` to copy conversation text without writing a file:
+
+```text
+/copy last         # copy the latest assistant response
+/copy transcript   # copy the full transcript as Markdown
+```
+
+With no argument, `/copy` defaults to `last`. Copying uses the terminal clipboard (OSC 52) when supported.
+
 ## Export a session
 
 Export when you want notes outside Kward:
@@ -193,20 +210,35 @@ Export when you want notes outside Kward:
 /export notes.md
 ```
 
+With no argument, `/export` writes a Markdown file beside the session file, derived from the session name with a `.md` extension.
+
 Exports are useful for handoff notes, review summaries, release records, or saving a human-readable transcript before deleting old sessions.
 
+## Check session status
+
+Use `/status` to see the active session name, file path, and auto-compaction reserve at a glance:
+
+```text
+/status
+```
+
+This is useful when you want to confirm which session you are in or check whether auto-compaction is active.
+
 ## Which command should I use?
 
 | Need | Use |
 | --- | --- |
 | Continue earlier work | `/sessions` or `/resume` |
 | Give the current session a better name | `/rename <name>` |
+| Clear the current session name | `/name` |
 | Keep the current state but try another future | `/clone` |
 | Start a separate session from before an earlier prompt | `/fork` |
 | Quickly retry an earlier prompt in this session | `/rewind` |
 | Inspect or navigate the full branch structure | `/tree` |
 | Reduce old context so a long session can continue | `/compact` |
+| Copy the last response or full transcript to clipboard | `/copy [last\|transcript]` |
 | Save a readable transcript | `/export <path>` |
+| Check the active session and compaction status | `/status` |
 
 ## Practical habits
 
@@ -218,3 +250,5 @@ Exports are useful for handoff notes, review summaries, release records, or savi
 - Compact when the conversation gets long, but keep the focus instruction specific.
 
 Sessions make Kward less like a single chat box and more like a workspace timeline. You can preserve context, branch it, compress it, and return to it when the work needs another pass.
+
+RPC clients have their own session API with equivalent create, resume, list, clone, fork, rename, and compaction methods. See the [RPC documentation](rpc.md) for details.

data/doc/shell.md

@@ -0,0 +1,332 @@
+# Embedded shell
+
+Use `/shell` when you want to run a sequence of local commands without leaving Kward's interactive TUI.
+
+`/shell` opens **ekwsh**, the embedded Kward shell. It is not a full terminal emulator. Kward keeps ownership of the composer, transcript, tab bar, and keybindings while each command runs through your normal shell one command at a time.
+
+This makes it good for:
+
+- checking Git state,
+- running focused tests,
+- inspecting files with command-line tools,
+- using project aliases,
+- keeping command output visible beside the current Kward session.
+
+Use `/pty <command>` when you intentionally want to hand the terminal to a full-screen interactive command such as `less`.
+
+## Start shell mode
+
+Inside interactive Kward:
+
+```text
+/shell
+```
+
+The composer prompt changes to show the shell's current directory:
+
+```text
+Shell ~/code/project $
+```
+
+Type commands as you would in a normal shell:
+
+```sh
+git status --short
+bundle exec ruby -Itest test/test_ekwsh.rb
+cd lib/kward
+pwd
+```
+
+Leave shell mode with:
+
+```sh
+exit
+```
+
+or press Ctrl+D on an empty shell prompt.
+
+## How commands run
+
+`ekwsh` is POSIX-oriented and runs each command through `/bin/sh` using the shell's `-c` mode by default. You can configure another POSIX-compatible shell in `ekwsh.yml`. The shell is intentionally not started as a login shell so Kward-managed environment values, such as configured PATH entries, are not overwritten by login startup files.
+
+The current directory and exported environment are tracked by Kward between commands, so this works as expected:
+
+```sh
+cd test
+pwd
+export FOO=bar
+printf '%s\n' "$FOO"
+unset FOO
+```
+
+`cd` changes only the embedded shell's current directory. It does not change Kward's workspace root or the process directory used by the rest of Kward.
+
+Shell output streams into the transcript area as commands run, but it is not added to the AI conversation history. Simple assignment-only commands such as `FOO=bar` persist into the embedded shell environment for later commands.
+
+Shell commands are persisted in a separate workspace-scoped shell history. They do not share the normal Kward prompt history used for chat prompts. The shell history limit is controlled by `history_limit` in `ekwsh.yml`.
+
+## Built-ins
+
+`ekwsh` handles a small set of built-ins itself:
+
+| Built-in | What it does |
+| --- | --- |
+| `cd [dir]` | Change the embedded shell directory. Supports `cd`, `cd -`, and normal relative paths. |
+| `pwd` | Print the embedded shell directory. |
+| `export KEY[=value]` | Set or mark an environment variable for later commands. `export` and `export -p` list variables. |
+| `unset KEY` | Remove an environment variable from later commands. |
+| `alias [name]` | List configured aliases, show specific configured aliases, or set `alias name=value`. |
+| `unalias name` / `unalias -a` | Remove configured aliases. |
+| `clear` | Clear Kward's visible transcript. |
+| `exit` / `logout` | Leave shell mode. |
+
+Built-ins take precedence over aliases and executables.
+
+## Tabs
+
+Shell mode is tracked per Kward tab.
+
+If you enter `/shell` in one tab, switch to another tab, and later switch back, that tab is still in shell mode. Its shell state and transcript snapshot are restored until you leave shell mode in that tab.
+
+This means each tab can have its own:
+
+- shell current directory,
+- exported environment,
+- visible shell transcript,
+- command prompt state.
+
+Kward's normal tab-switching shortcuts continue to work in shell mode. If you switch tabs while a shell command is running, Kward cancels that foreground command and requeues the tab action so the TUI can switch cleanly.
+
+## Tab completion
+
+Plain Tab completes shell input while in `ekwsh`.
+
+Completion includes:
+
+- built-in command names,
+- configured aliases,
+- executable names from `$PATH`,
+- file paths from the shell's current directory.
+
+Examples:
+
+```sh
+pw<Tab>          # pwd
+ll<Tab>          # configured alias, if present
+cat lib/kw<Tab>  # path completion
+cd doc<Tab>      # directory-only completion for cd
+```
+
+Directory completions get a trailing slash. File and command completions get a trailing space when there is a single match.
+
+Paths with spaces are shell-escaped:
+
+```sh
+cat my<Tab>
+# => cat my\ file.txt
+```
+
+Quoted path tokens are completed in the same quoting style:
+
+```sh
+cat "my<Tab>
+# => cat "my file.txt
+```
+
+If there are multiple candidates, Kward applies any common prefix. When there is no longer common prefix, it prints a compact candidate list in the transcript. Command-name completion caches `$PATH` executables and refreshes when `PATH` changes through shell assignment, `export`, or `unset`.
+
+## Colors and ANSI output
+
+`ekwsh` preserves safe ANSI SGR color/style sequences in command output, such as:
+
+- colors,
+- bold,
+- dim,
+- italic,
+- underline,
+- 256-color and truecolor SGR sequences.
+
+It strips terminal-control sequences that could corrupt Kward's TUI, such as cursor movement, clear-screen controls, OSC title changes, and alternate-screen controls.
+
+When rbenv is available, `ekwsh` also prepends the rbenv shims and bin directories to PATH and sets `RBENV_ROOT` when it was missing. This lets commands such as `ruby`, `bundle`, and `./exe/kward` use the same Ruby selected by rbenv without requiring `rbenv init` support in `ekwsh`.
+
+By default, `ekwsh` sets conservative color-friendly environment values:
+
+```sh
+CLICOLOR=1
+COLORTERM=truecolor
+TERM=xterm-256color  # only when TERM is missing or dumb
+```
+
+It does **not** force color by default. If a tool does not emit color because stdout is not a TTY, use a command-specific flag or configure forced color yourself:
+
+```sh
+git diff --color=always
+grep --color=always TODO lib/**/*.rb
+```
+
+## Global ekwsh config
+
+You can configure environment variables and aliases in:
+
+```text
+~/.kward/ekwsh.yml
+```
+
+If `KWARD_CONFIG_PATH` points to another config file, `ekwsh.yml` is read from that file's directory instead.
+
+Example:
+
+```yaml
+shell: /bin/sh
+# timeout_seconds: 300
+# max_output_bytes: 1048576
+# history_limit: 1000
+
+env:
+  FORCE_COLOR: "1"
+  CLICOLOR_FORCE: "1"
+  RAILS_ENV: "test"
+
+aliases:
+  ll: "ls -la"
+  gs: "git status --short"
+  gd: "git diff --color=always"
+  be: "bundle exec"
+  t: "bundle exec ruby -Itest"
+```
+
+### Runtime settings
+
+`ekwsh` accepts these top-level runtime settings:
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `shell` | `/bin/sh` | Absolute path to the POSIX-compatible shell used with `-c`. Invalid or relative paths fall back to `/bin/sh`. |
+| `timeout_seconds` | `300` | Maximum runtime for one command. |
+| `max_output_bytes` | `1048576` | Maximum captured output for one command. |
+| `history_limit` | `1000` | Maximum persisted shell history entries per workspace. |
+
+When a command exceeds `timeout_seconds`, `ekwsh` terminates it and reports the timeout. When command output exceeds `max_output_bytes`, `ekwsh` terminates the command, keeps bounded output, and reports the output limit. Press Ctrl+C while a command is running to terminate that command and return to the shell prompt without exiting Kward.
+
+### Environment variables
+
+`env` values are applied when shell mode starts, after Kward's conservative color defaults.
+
+Keys must look like environment variable names:
+
+```text
+A_Z, digits after the first character, and underscores
+```
+
+Invalid keys are ignored. Values are converted to strings. Nil values are ignored.
+
+Configured env is useful for local preferences such as:
+
+```yaml
+env:
+  FORCE_COLOR: "1"
+  BUNDLE_WITHOUT: "production"
+  RAILS_ENV: "test"
+```
+
+For one shell session, you can also use the built-in `export` command:
+
+```sh
+export FORCE_COLOR=1
+```
+
+### Aliases
+
+Aliases expand the first word of a command once.
+
+With this config:
+
+```yaml
+aliases:
+  ll: "ls -la"
+  t: "bundle exec ruby -Itest"
+```
+
+these commands run as:
+
+```sh
+ll lib
+# runs: ls -la lib
+
+t test/test_ekwsh.rb
+# runs: bundle exec ruby -Itest test/test_ekwsh.rb
+```
+
+Aliases are intentionally simple:
+
+- only the first word is expanded,
+- aliases do not recursively expand,
+- built-ins win over alias names,
+- aliases are not shell functions,
+- aliases are global for now.
+
+List configured aliases inside `ekwsh`:
+
+```sh
+alias
+```
+
+Show specific aliases:
+
+```sh
+alias ll gs
+```
+
+Aliases also appear in command-name Tab completion.
+
+## Interactive PTY passthrough
+
+Use `/pty <command>` for commands that need to own the terminal temporarily, such as pagers:
+
+```text
+/pty git log
+```
+
+Inside `/shell`, use the `pty` built-in so the command inherits the embedded shell's current directory and environment:
+
+```sh
+pty git log
+pty vim README.md
+```
+
+Kward runs the command in a PTY, forwards your keyboard input to the process, and streams the process output directly to the terminal. This lets tools such as `less` receive keys like Space, `/`, `n`, and `q` normally. When the command exits, Kward restores its prompt and records only a short session summary in the transcript instead of raw full-screen terminal control output.
+
+`/pty` and shell `pty` are explicit on purpose. Normal `/shell` commands remain captured and transcript-friendly; `pty` is for commands where the child process should temporarily own the terminal.
+
+## `/shell` versus `!command`
+
+Kward has two ways to run local commands yourself:
+
+```text
+!git status --short
+```
+
+runs one command directly from the normal composer.
+
+```text
+/shell
+```
+
+starts an embedded command mode for several commands with persistent shell state, aliases, completion, and per-tab shell context.
+
+Use `!command` for one-offs. Use `/shell` when you expect to run several commands in a row.
+
+## Limitations
+
+`ekwsh` is deliberately not a full interactive terminal.
+
+Current limitations:
+
+- no job control,
+- no persistent shell functions,
+- no shell startup file sourcing,
+- no native readline from your login shell,
+- normal `/shell` command output is transcript-sanitized rather than treated as a full terminal UI.
+
+External `/shell` commands run under a minimal PTY so terminal-aware tools can detect TTY output and terminal width. Full-screen interactive programs should still use explicit `/pty <command>` passthrough.