@sagmans/dsh-tui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sagmans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# @sagmans/dsh-tui
+
+Interactive terminal (TUI) surface for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): use `dsh` in a terminal instead of a browser.
+
+Status: **v1 feature-complete, first release pending.** The surface owns the alternate screen, streams assistant text as markdown, renders every tool's own card, answers approvals and questions, restores and names stored conversations, switches model mid-session, runs any of the four shipped agent modes and switches between them before a session's first turn, reads a child agent's conversation in place, keeps the goal, plan mode, todo list, delegations, and background jobs above the editor with a status line below it, and hands the terminal back on every graceful exit. Publication is tag-driven with GitHub OIDC provenance and no stored npm token; see [RELEASE.md](RELEASE.md).
+
+## Install
+
+A profile keeps this plugin as one bundle layer. Install it from a checkout of this repository, or from the registry once a release is published. Both paths need Node.js >= 22.19 and `pnpm` on `PATH`. Both need a real terminal: stdin and stdout must be TTYs.
+
+### From a plugin checkout
+
+A linked profile loads the package's built entry point. Build the checkout before you add it:
+
+```sh
+cd "$PLUGIN_CHECKOUT"
+CI=true pnpm install && pnpm run build
+dsh plugin --profile tui add "$PWD"
+dsh --profile tui
+```
+
+The `add` command creates the `tui` profile on first use and records a link to the directory. Keep the checkout in place. If you move or delete it, the link breaks, and a later `plugin install` removes the bundle from the layer list (see Troubleshooting).
+
+### From the registry
+
+```sh
+dsh plugin --profile tui add @sagmans/dsh-tui@latest
+dsh --profile tui
+```
+
+This path needs a published release. No release is published yet, so use a checkout until then.
+
+### Confirm the plugin mounted
+
+The profile records its layers in `$DSH_HOME/profiles/tui/package.json` (`~/.dsh` by default). `@sagmans/dsh-tui` must appear in `dsh.profile.bundles`:
+
+```sh
+node -p "require((process.env.DSH_HOME ?? require('node:os').homedir() + '/.dsh') + '/profiles/tui/package.json').dsh.profile.bundles.join('\n')"
+# @deepseek-ai/dsh-base
+# @sagmans/dsh-tui
+```
+
+Then check that the surface is mounted. A pipe is not a terminal, so this command must refuse before it takes the screen over:
+
+```sh
+echo hi | dsh --profile tui
+# dsh-tui: both stdin and stdout must be TTYs; run this profile from a terminal or SSH session
+```
+
+### Update
+
+Rebuild a linked checkout, then start the next session. The link itself does not change:
+
+```sh
+cd "$PLUGIN_CHECKOUT" && git pull && CI=true pnpm install && pnpm run build
+```
+
+A registry install updates with `dsh plugin --profile tui update @sagmans/dsh-tui`.
+
+### Remove
+
+```sh
+dsh plugin --profile tui remove @sagmans/dsh-tui
+```
+
+The profile then keeps `@deepseek-ai/dsh-base` and no application, so `dsh --profile tui` waits with no output. Add the plugin again to use the profile.
+
+### Launching from a harness checkout
+
+`pnpm dsh --profile tui` is the sanctioned launcher, but pnpm verifies that dependencies are current before it runs any script, and a checkout whose `postinstall` refuses to take over a user-owned `core.hooksPath` fails that check — the process exits before the surface starts. Any of these reaches the surface:
+
+```sh
+pnpm --config.verify-deps-before-run=false dsh --profile tui   # from the checkout
+CI=true pnpm dsh --profile tui                                 # also suppresses the check
+node "$CHECKOUT/apps/cli/lib/bin.js" --profile tui             # needs neither pnpm nor the check
+```
+
+## Troubleshooting
+
+Two facts explain most failures.
+
+**A linked profile is a link, not a copy.** The profile points at a directory, so a checkout that moves or disappears breaks it.
+
+**`dsh plugin install` removes a bundle it cannot resolve, and says nothing.** The command reconciles `dsh.profile.bundles` against the installed dependencies. A bundle whose path does not resolve leaves the list, and the command still exits 0. The next launch composes `@deepseek-ai/dsh-base` alone. No application plugin mounts, so nothing reads the command line: `dsh --profile tui` then prints nothing and never exits, and `--help` waits with it.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `dsh: cannot resolve profile bundle "@sagmans/dsh-tui" ...` | the linked checkout moved or was deleted | `dsh plugin --profile tui add "$PLUGIN_CHECKOUT"` |
+| `dsh --profile tui` prints nothing and never exits | the bundle left `dsh.profile.bundles`, usually after a broken link and a `plugin install` | confirm the layer list, then run the `add` command again |
+| `dsh-tui: both stdin and stdout must be TTYs` | stdin or stdout is a pipe, a file, or a CI runner | run the command from a terminal |
+| Changes under `src/` have no effect | a linked profile loads `lib/`, not `src/` | `pnpm run build` in the plugin checkout |
+| `pnpm dsh --profile tui` exits before the surface appears | pnpm's dependency check fails on the harness checkout's own postinstall | see [Launching from a harness checkout](#launching-from-a-harness-checkout) |
+| `--preset <id>` is refused, because the session's agent preset is fixed | a session keeps the mode that composed it, and this session already took a turn | `/preset <id>` before the first turn, or resume without `--preset` |
+| `--resume <id>` starts a new session | the id is a bare UUID | pass the stored id, `tui-session-…` included; a bare `--resume` opens the picker |
+| `dsh: profile "tui" does not exist` | the profile is not created yet | the `add` command creates it |
+
+The full recovery from a broken link:
+
+```sh
+cd "$PLUGIN_CHECKOUT" && CI=true pnpm install && pnpm run build
+dsh plugin --profile tui add "$PWD"
+node -p "require((process.env.DSH_HOME ?? require('node:os').homedir() + '/.dsh') + '/profiles/tui/package.json').dsh.profile.bundles.join('\n')"
+# @deepseek-ai/dsh-base
+# @sagmans/dsh-tui
+```
+
+## Usage
+
+```sh
+dsh --profile tui                      # new session in the current directory
+dsh --profile tui --resume             # pick a stored session, titled by its first prompt
+dsh --profile tui --resume <session-id>
+dsh --profile tui --preset ptc             # start in one of the shipped agent modes
+dsh --profile tui --model deepseek-chat
+dsh --profile tui --no-color
+dsh --profile tui --no-bell            # do not ring when a long turn finishes
+```
+
+| Key | Action |
+|---|---|
+| Enter | submit the prompt |
+| Ctrl+C | interrupt the running turn, or leave when idle |
+| Ctrl+O | show every line of the tool cards instead of their preview |
+| Ctrl+T | show the reasoning behind an answer instead of its summary |
+| `y` / `n` / Esc | allow once, reject, or cancel a pending approval |
+| digits / space / ↑↓ / Enter / Esc | answer a question: pick or toggle, confirm, or skip one |
+| `/` then Tab | complete commands, including every command this session registered |
+| `@` or a path then Tab | complete workspace file references |
+| `ctrl+shift+f` | search the transcript (`enter` next, `shift+enter` previous, `esc` close) |
+| `home` / `end` | jump to the start or the end of the transcript |
+| `ctrl+down` | jump to the next prompt |
+| `ctrl+b` | leave a child's conversation and return to this session |
+| mouse wheel, drag | scroll, and copy a selection through OSC 52 |
+| `/help` | list registered and local commands |
+| `/status` | show the session id, model, permissions, context, and directory |
+| `/model` | show the route the next step will use, and the providers available |
+| `/model <provider>` | list that provider's advertised models |
+| `/model <provider>/<model>` | use that route from the next step on (session only, nothing is written to settings) |
+| `/preset` | pick the agent mode for this session from the roster |
+| `/preset <id>` | switch to that mode, while the session is still blank |
+| `/jobs` | list background jobs with their state and duration |
+| `/jobs read <id>` / `/jobs kill <id>` | show the tail of a job's output, or stop it |
+| `/subagents` | list the delegations this session started, with their provider and age |
+| `/subagents open <id\|last>` | read a child's own conversation in place; `ctrl+b` comes back |
+| `/subagents kill <id>` | stop a live child agent |
+| `/fork [title]` | branch this conversation after its last completed turn and continue in the branch |
+| `/rename <title>` | title this session; the picker shows it instead of the session id |
+| `/export [path]` | write the visible transcript as markdown (default `dsh-session-<id>.md`) |
+| `/resume` | open another stored session without leaving the terminal |
+| `/clear` | clear the visible transcript |
+| `/quit` | leave and print the resume command |
+
+Any other `/command` goes to the command registry, so `/plan`, `/compact`, `/goal`, and `/feedback` behave as they do on the other surfaces.
+
+## Modes
+
+A mode is an **agent preset**: the plugin composition an agent's own scope joins. It decides that agent's tools, prompt sections, skills, and planning rows, which is why a mode is fixed once a session has produced a turn — it is what composed the agent that answered.
+
+Four ship, under the ids a session log records:
+
+| `--preset` | Mode | What the agent gets |
+|---|---|---|
+| `standard` | standard | full agent: editing, shell, search, skills, planning, goals, subagents, workflows |
+| `ptc` | PTC | the same agent, reaching its tools through one TypeScript program |
+| `minimal` | minimal | one tool: a persistent shell |
+| `cordis` | creator | harness authoring: runtime inspection and composition guidance |
+
+A session takes its mode from the first of these that applies:
+
+1. `--preset <id>`, refused before the terminal is taken over when the roster does not ship that id.
+2. `/preset` while the session is still blank: a bare command opens the picker, `/preset <id>` switches directly, and the choice is written to the log.
+3. The roster's default, `standard`, when nobody names one.
+
+The mode is re-read rather than remembered: resuming mounts what that session's own log recorded, resuming with a `--preset` that disagrees with it is refused instead of silently ignored, and forking inherits the mode of the conversation being branched. The status line names the mode, and `/status` lists it with the rest.
+
+## How it works
+
+The package is a Cordis plugin bundle that stacks over `@deepseek-ai/dsh-base`:
+
+- `@sagmans/dsh-tui/startup` parses this app's own flags and publishes the launch identity.
+- `@deepseek-ai/dsh-agent-presets` is the roster of modes, holding the id a session starts in when nobody names one.
+- `@deepseek-ai/dsh-code-runtime-worker-thread` and `@deepseek-ai/dsh-cordis-host-runner` are the host machinery PTC mode and creator mode need; only the Web bundle shipped them, so a terminal profile has to mount them to offer those modes at all.
+- `@sagmans/dsh-tui` owns the terminal: it creates or resumes one agent through `ctx.agents`, folds `session/event` into transcript rows and work state, renders them with `@earendil-works/pi-tui`, and releases the terminal on exit, on a boot failure, and on a signal.
+
+The fold is durable-only: the live stream decorates the row that is still being written, and everything else — cards, reasoning, work state, compaction markers — comes from the log, so a resumed session renders what the live one did. Subagent start and finish are the exception: they arrive as service events, and the transcript shows them as decoration because the durable record of a delegation is the tool call that asked for it.
+
+The bundle also takes the base's global agent rows out of the composition, twenty-three of them. Every one is a row the shipped modes supply per session instead, so leaving it mounted registers the same tool names in two layers and doubles each prompt section it owns. What stays mounted is the host: sessions, storage, models, permissions, jobs, and the command registry.
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+```
+
+**A linked profile loads the built entry point**, so edits under `src/` are invisible to `dsh --profile tui` until `pnpm run build` runs. Drive the real surface end to end — it rebuilds first, allocates a PTY, sends a prompt, and prints what the screen showed:
+
+```sh
+node tools/pty-drive.mjs --prompt 'Reply with exactly: pong'
+node tools/pty-drive.mjs --prompt 'Run: echo hi' --approve 20   # answer the approval gate
+node tools/pty-drive.mjs --home /tmp/scratch-home --seconds 20  # no credentials: proves failures are visible
+```
+
+Keep verification off your real home: install the profile into a throwaway one and copy only the credentials it needs.
+
+```sh
+S=$(mktemp -d)
+cp ~/.dsh/.credentials.yaml ~/.dsh/settings.yaml "$S/" && chmod 600 "$S"/*.yaml
+DSH_HOME="$S" dsh plugin --profile tui add "$PWD"
+node tools/pty-drive.mjs --home "$S" --prompt 'Reply with exactly: pong'
+```
+
+Test specs import plugin sources through the `@/` alias. Under this test runner the spec file is resolved with a root-relative id, so parent-relative imports (`../src/...`) do not resolve; the alias and its matching `tsconfig.test.json` path mapping avoid that.
+
+## Manual acceptance
+
+The automated checks drive a real PTY, but they run on this machine's terminal. These are the checks only a terminal on your desk can answer; each line is what to do and what it should look like.
+
+| Check | Expected |
+|---|---|
+| `DSH_HOME=$(mktemp -d) dsh plugin --profile tui add "$PWD"` from a built checkout | the profile is created, `dsh.profile.bundles` lists the plugin, and `dsh --profile tui` reaches a prompt |
+| the same over SSH | the interface arrives intact; keys and mouse work on the host, with no local echo doubling |
+| inside tmux or screen | wheel scroll and `ctrl+shift+f` search work; dragging selects text |
+| a light terminal and a dark one | the interface follows the terminal's own palette; nothing becomes unreadable |
+| `NO_COLOR=1 dsh --profile tui` | no styling anywhere, layout unchanged |
+| `dsh --profile tui --no-bell` | a turn that runs for minutes still ends silently |
+| `dsh --profile tui --preset ptc`, then a turn | the status line names `ptc`, and the agent reaches its tools through one TypeScript program rather than one shell call at a time |
+| `/preset` on a fresh session | the picker lists four modes, marks the current one, and the switch survives a resume |
+| `/preset minimal` after a turn | refused, naming the reason; the session keeps the mode it composed with |
+| `--resume --preset <mode>` and then picking a session that runs another mode | the list stays open and says why that row cannot be taken; `esc` leaves the picker |
+| `dsh --profile tui --preset nope` | exits non-zero naming the modes that do exist, before the alternate screen appears |
+| arrow keys in a picker, or on a question's options, in a terminal that reports key events (Kitty, WezTerm, Ghostty, iTerm2) | one press moves one row, and holding a key still repeats; a terminal that sends only the legacy sequence behaves the same |
+| resize the window mid-turn | the transcript rewraps; the dock, editor, and status row stay put |
+| a 40-column terminal | rows end in `…` instead of wrapping into the next line |
+| `echo hi \| dsh --profile tui` | refuses with a non-zero exit and a message naming the TTY requirement |
+| `/quit`, Ctrl+C while idle, `kill -TERM <pid>` | the shell returns with cursor, echo, mouse, and title restored |
+
+## Releasing
+
+Published artefacts carry a provenance attestation, which only a CI provider can issue, so releases ship from the tag workflow rather than a laptop.
+
+1. Bump `version` in `package.json` and commit it.
+2. `git tag v<version> && git push origin v<version>`.
+3. `.github/workflows/release.yml` re-runs typecheck, tests, and the package smoke, then publishes with `--provenance`.
+
+The workflow needs an `NPM_TOKEN` repository secret with publish rights for the `@sagmans` scope. To publish by hand instead, run `pnpm publish --access public --provenance` from a clean checkout of the tag.
+
+## Limitations
+
+- Two different things are called a preset. The agent mode (`--preset`, `/preset`) is fixed once a session has produced a turn; the permission preset (`/permission <preset>`, named in the status line) can change at any time.
+- `/model` changes the route for the running session only. Catalog membership is advisory — an adapter may accept an id it does not advertise.
+- Scrolling is the mouse wheel, or the terminal's own scrollback keys where it offers them.
+- A turn that ran longer than ten seconds rings the terminal bell when it ends, because the reader may have walked away; `--no-bell` turns that off.
+- The dock shows the goal, plan mode, the todo list, and any background job still running; the transcript marks where older history was compacted away. `/plan` toggles plan mode; `/plan <message>` also steers that message, which is the base command's own behaviour.
+- Background jobs and subagent runs are live process state, not durable events: they disappear when the run ends, and a resumed session starts with an empty board and roster.
+- Reading a child's conversation does not move the terminal: commands, approvals, and the status line stay with the session you launched, and the transcript is the only thing that switches.
+- Delete is unimplemented: the session store exposes no delete, and the surface does not reach around that seam into its files. `/fork` covers the case that needs it — it branches into a new session and leaves the original alone.
+- Approvals and questions render inline and take the keyboard; a question batch is answered in order.
+- Styling uses the standard 16 ANSI colors and terminal defaults, so light and dark terminals follow their own theme.
+- Tool text, model text, and file content are escaped before rendering, so a hostile result cannot inject terminal control sequences; the cost is that a literal tab shows as \x09.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,123 @@
+# dsh-tui — the terminal agent plane, over dsh-base.
+#
+# Every row this bundle INSERTS is owned by the plugin: no row names a package
+# the plugin does not depend on. The rows it DISABLES are the base's global
+# agent rows, because from here on an agent's tools, prompt sections, skills,
+# and planning rows come from the agent preset its own session mounts — the
+# composition the Web bundle composes for the same reason. Leaving them mounted
+# would register the same tool names in two layers, double every prompt section
+# and command they own, and provide the same services twice, which fails.
+#
+# The ids are exactly the base rows the shipped presets supply: standard, ptc,
+# and cordis provide every one of them, while minimal supplies its own
+# persistent-terminal set instead, which is the point of that mode.
+- id: agent-instructions
+  disabled: true
+
+- id: command-compact
+  disabled: true
+
+- id: command-goal
+  disabled: true
+
+- id: compaction-basic
+  disabled: true
+
+- id: plan-mode
+  disabled: true
+
+- id: skill-filesystem
+  disabled: true
+
+- id: tool-bash
+  disabled: true
+
+- id: tool-fs
+  disabled: true
+
+- id: tool-fs-search
+  disabled: true
+
+- id: tool-goal
+  disabled: true
+
+- id: tool-jobs
+  disabled: true
+
+- id: tool-pwsh
+  disabled: true
+
+- id: tool-ralph
+  disabled: true
+
+- id: tool-result-pruner
+  disabled: true
+
+- id: tool-skill
+  disabled: true
+
+- id: tool-subagent
+  disabled: true
+
+- id: tool-subagent-control
+  disabled: true
+
+- id: tool-subagent-fork
+  disabled: true
+
+- id: tool-subagent-list-agents
+  disabled: true
+
+- id: tool-todo
+  disabled: true
+
+- id: tool-web
+  disabled: true
+
+- id: tool-workflow
+  disabled: true
+
+- id: workflow-worker-thread
+  disabled: true
+
+- insert:
+    - id: tui-startup
+      name: '@sagmans/dsh-tui/startup'
+
+    - id: tui
+      name: '@sagmans/dsh-tui'
+      inject: [tuiStartup]
+      config:
+        sessionId: !!js ctx.tuiStartup.sessionId
+        resume: !!js ctx.tuiStartup.resume
+        resumePicker: !!js ctx.tuiStartup.resumePicker
+        model: !!js ctx.tuiStartup.model
+        provider: !!js ctx.tuiStartup.provider
+        preset: !!js ctx.tuiStartup.preset
+        color: !!js ctx.tuiStartup.color
+        bell: !!js ctx.tuiStartup.bell
+
+    # The roster of agent compositions, and the mode a session starts in when
+    # nobody names one. A profile patch may override this row's config.
+    - id: agent-presets
+      name: '@deepseek-ai/dsh-agent-presets'
+      config:
+        default: standard
+
+    # A preset's subagent tool samples its delegation model from this host-owned
+    # settings row. It is host machinery rather than agent plane, which is why
+    # the Web bundle inserts it too instead of leaving it to the preset.
+    - id: subagent-model-selection-settings
+      name: '@deepseek-ai/dsh-tool-subagent/model-selection-settings'
+
+    # Creator mode inspects and re-composes the running harness, which needs the
+    # host half of the dynamic-plugin runner. Only the Web bundle ships this
+    # row, so a terminal profile has to mount it to offer that mode at all.
+    - id: cordis-host-runner
+      name: '@deepseek-ai/dsh-cordis-host-runner'
+
+    # PTC mode runs its programs against a code runtime. The Web bundle mounts
+    # this at host level for the same reason: the runtime is machinery, while
+    # the preset decides whether an agent uses it.
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker-thread'

package/lib/agent/fork.d.ts

@@ -0,0 +1,24 @@
+/** One durable event, as much of it as a fork decision needs. */
+export interface ForkEvent {
+    readonly type: string;
+    readonly data?: unknown;
+    readonly seq?: number;
+}
+/** Where a fork may branch, and how much of the log the child inherits. */
+export interface ForkPoint {
+    /** Events the child inherits, counted from the start of the log. */
+    readonly inheritedEvents: number;
+    /** Seq of the turn/end the cut is anchored to. */
+    readonly boundarySeq: number;
+}
+/**
+ * Where a session may be branched.
+ *
+ * A turn is the unit a conversation can be cut at: an open turn, an open step,
+ * or a tool call without its result would leave the child holding half an
+ * exchange. The cut is therefore anchored to the last completed turn and
+ * extended to the next `turn/start`, which keeps the trailing bookkeeping of
+ * that turn — this is the same boundary the host's own fork uses.
+ */
+export declare function forkPoint(events: readonly ForkEvent[]): ForkPoint | undefined;
+//# sourceMappingURL=fork.d.ts.map

package/lib/agent/fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/agent/fork.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,GAAG,SAAS,CAY7E"}

package/lib/agent/fork.js

@@ -0,0 +1,25 @@
+/**
+ * Where a session may be branched.
+ *
+ * A turn is the unit a conversation can be cut at: an open turn, an open step,
+ * or a tool call without its result would leave the child holding half an
+ * exchange. The cut is therefore anchored to the last completed turn and
+ * extended to the next `turn/start`, which keeps the trailing bookkeeping of
+ * that turn — this is the same boundary the host's own fork uses.
+ */
+export function forkPoint(events) {
+    let boundary = -1;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        if (events[index]?.type === 'turn/end') {
+            boundary = index;
+            break;
+        }
+    }
+    if (boundary < 0)
+        return undefined;
+    let cut = boundary + 1;
+    while (cut < events.length && events[cut]?.type !== 'turn/start')
+        cut += 1;
+    return { inheritedEvents: cut, boundarySeq: events[boundary]?.seq ?? boundary };
+}
+//# sourceMappingURL=fork.js.map

package/lib/agent/fork.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.js","sourceRoot":"","sources":["../../src/agent/fork.ts"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,MAA4B;IACpD,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAA;IACjB,KAAK,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3D,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,UAAU,EAAE,CAAC;YACvC,QAAQ,GAAG,KAAK,CAAA;YAChB,MAAK;QACP,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAClC,IAAI,GAAG,GAAG,QAAQ,GAAG,CAAC,CAAA;IACtB,OAAO,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,KAAK,YAAY;QAAE,GAAG,IAAI,CAAC,CAAA;IAC1E,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,QAAQ,EAAE,CAAA;AACjF,CAAC"}

package/lib/agent/history.d.ts

@@ -0,0 +1,78 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** One stored session as the picker shows it. */
+export interface StoredSession {
+    readonly id: string;
+    readonly cwd: string | undefined;
+    readonly createdAt: number;
+    readonly eventCount: number | undefined;
+}
+/** The persisted header fields this surface reads besides the list columns. */
+export interface StoredHeader {
+    readonly id: string;
+    /** Preset the session STARTED with; a later selection is a log event. */
+    readonly agentPreset: string | undefined;
+    readonly eventCount: number | undefined;
+}
+/** One stored event, reduced to what the transcript fold reads. */
+export interface StoredEvent {
+    readonly type: string;
+    readonly data?: unknown;
+}
+/** The part of the persistence seam this surface uses, described structurally. */
+export interface SessionHistory {
+    /** Newest sessions first, at most `limit` of them. */
+    list(limit: number): Promise<readonly StoredSession[]>;
+    /** Read a slice of a session's log; `limit` bounds a title read. */
+    read(id: string, options?: {
+        readonly offset?: number;
+        readonly limit?: number;
+    }): Promise<readonly StoredEvent[]>;
+    /** One session's stored header, or undefined when nothing is stored under that id. */
+    header(id: string): Promise<StoredHeader | undefined>;
+}
+/** Sessions the picker offers before a menu stops being a menu. */
+export declare const PICKER_LIMIT = 30;
+/** Events read to title one session: enough to reach its title or first prompt. */
+export declare const TITLE_EVENT_LIMIT = 40;
+/** Longest session title the picker shows, before the row can no longer hold it. */
+export declare const TITLE_CHAR_LIMIT = 72;
+/** Events read to resolve a session's preset: a selection sits in its blank prefix. */
+export declare const PRESET_EVENT_LIMIT = 40;
+/**
+ * Name a session, preferring the title the harness derived or the reader set.
+ *
+ * The durable `session/title` wins because it is what every other surface
+ * shows; a session that has none yet falls back to its first human prompt.
+ * Injected context and plugin notices also arrive as user-role messages, so
+ * only a direct prompt may name a session.
+ */
+export declare function sessionTitle(events: readonly StoredEvent[], limit?: number): string | undefined;
+/**
+ * Title one stored session.
+ *
+ * The tail is read first because a title is latest-wins and usually written
+ * after the first turn; the head is the fallback for a session that has a
+ * prompt but no title yet.
+ */
+export declare function readSessionTitle(history: SessionHistory, session: StoredSession): Promise<string | undefined>;
+/**
+ * The agent preset a stored session runs.
+ *
+ * The creation header names the preset the session STARTED with, and a
+ * selection recorded while it was still blank replaced it. The projection's own
+ * rule is that the last selection wins over the header, so the tail is read
+ * first and the head second: the harness refuses a switch once a turn has run,
+ * which puts any selection in the blank prefix. Reading both keeps this correct
+ * if that rule ever loosens, and the event count bounds the work either way.
+ */
+export declare function presetOfStoredSession(history: SessionHistory, id: string): Promise<string | undefined>;
+/**
+ * Wrap the persistence service in the little of it a terminal needs.
+ *
+ * The seam itself is optional here: a composition without durable storage can
+ * still run the surface, it just cannot list or replay stored sessions. A read
+ * handle is always closed, because an unclosed one keeps backend resources
+ * alive for the rest of the process.
+ */
+export declare function createSessionHistory(ctx: Context): SessionHistory | undefined;
+//# sourceMappingURL=history.d.ts.map

package/lib/agent/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/agent/history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAA;IACtD,oEAAoE;IACpE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IAClH,sFAAsF;IACtF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAA;CACtD;AAED,mEAAmE;AACnE,eAAO,MAAM,YAAY,KAAK,CAAA;AAE9B,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAElC,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,KAAK,CAAA;AA0BpC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,SAAmB,GAAG,MAAM,GAAG,SAAS,CAwBzG;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQnH;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS5G;AAmBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAsD7E"}