@aiwayds/dsh-opentui 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-11-04
+
+### Added
+
+- **Client-mode foundations (ADR-0005 P1/P5).** The TUI-as-thin-client path gets its four base layers. `src/client/cookie-mint.ts` mints the Host API cookie from the persisted `client-connection/browser-session` grant in `$DSH_HOME/.credentials.yaml`, reproducing the Host's own recipe byte-for-byte (BrowserAuth/dsh-credentials: cookie name `dsh-auth-` + base64url(sha256(authority)); value `v1.<body>.<base64url(HMAC-SHA256(secret, body))>`), fail-closed on non-owner-only credentials and with no secret/cookie material in any thrown error. `src/client/mux-frame.ts` + `events-source.ts` + `transport.ts` give a `ClientConnection` carrier over one authenticated `/api/remote.mux` WebSocket (`ws`, cookie on the upgrade — the global WebSocket cannot send headers): unary RPC via `POST /api`, and the `$events` mux pump behind `dsh-client-connection`'s `ConnectionGenerationSource` — the pump is deliberately chosen over the gateway-native `ClientRemoteEvents` client because waterfall frames must reach the consumer's `onEvent` (v1 answers them in-process), while the gateway source intercepts waterfall frames and auto-answers them itself with a stub typert service. `src/client/lifecycle.ts` is the host lifecycle manager `ensureHost`: first-TUI spawn, single-instance lock with stale-lock takeover, refcounted attach/detach, idle exit after `idleExitSec` (default 60s, `0` = resident), respawn crash cap. `scripts/provision-opentui-profile.mjs` idempotently bootstraps the fixed `opentui` host profile via `dsh opentui --from-default-profile web --dump-config` (compose-and-exit, no boot; touches only that one profile). 64 green tests in `packages/shell`; design background in `docs/adr/0005-client-mode.md` and `docs/client-mode-protocol-audit.md`.
+
+- **Client-mode session core + workspace config overlay (ADR-0005 P2 wave 1 / P4).** `src/client/remote-host-session.ts` is `RemoteHostSession` — the HostSession-shaped session facade the rendering layer consumes, driven over P1's `ClientConnection` (unary Remote RPC + raw `$events` pump). Wave-1 audit rows: turn lifecycle (`session/create` + `session/prompt`, `mode:'queue'` for fresh sends and `mode:'steer'` mirroring `agent.steer`; the message queue stays client-side), `session/follow({assistantStream:true})` consumption (`remote-follow.ts`: text/thinking deltas, usage, tool call/result frames with image-path extraction parity, durable turn/end + error mapping, `todo/write`), `session/cancel` abort, and generation re-attach — the follow stream re-opens on reconnect, the opening snapshot replays missed transcript rows through `onReattachedMissed` and an active turn's compact stream replays as deltas under a "reconnecting…" label. Waterfalls (`remote-waterfall.ts`): forwarded `$events` `approval/request` + `user-questions/request` frames are claimed by `frame.agentId === sessionId` and answered through the unary `$events/result` RPC with the host verdict payloads — `"allowed-once"` / `"rejected"` (+ `"unavailable"` fail-closed with no callbacks) for approvals, `{answers:[{id, selected[], custom?}]}` (declined envelope on UI throw) for questions — the waterfall route rather than `userQuestions/answer` + `attachWait`, since the TUI modal has no detach window and the waterfall is the exact-parity answerer chain the in-process TUI joins today. `src/client/workspace-config.ts` is the workspace-local config overlay (bucket d, decision 4): `./.dsh/config.yml` holds only theme + model preferences, precedence environment (`DSH_OPENTUI_THEME` / `DSH_OPENTUI_MODEL`) > workspace > global base, model subfields merge partially, unknown keys ignored on load and preserved verbatim on save, credential-shaped keys rejected on load AND save (denylist, fail closed), 0600/0700 atomic same-dir rename writes, and a strict no-dependency YAML subset that refuses to rewrite a file it cannot fully parse. `remote-host-session` plugs into the same `TurnCallbacks` seam as the in-process `HostSession`, so the UI swap is zero-change. Rest of the audit surface (rows 12–28, 30–33, 35–37) ships as HostSession-shaped wave-2/3 stubs. 116 green tests in `packages/shell` (116 pass / 1 env-gated live smoke skip); contract background in `docs/adr/0005-client-mode.md` and `docs/client-mode-protocol-audit.md`.
+
+- **Model route provisioning for the `opentui` profile.** The shipped web template mounts no provider route, so a freshly provisioned `opentui` profile could not complete a real model turn. `scripts/provision-opentui-profile.mjs` now writes/merges the route into the profile's `cordis.patch.yml` after (re)creation: `--provider` / `--model` / `--reasoning-effort` flags (defaults `zai-coding-cn` / `glm-5.3-flash` / `high`, matching `scripts/install-profile.mjs`), same patch-body shape (an `llm-pi-ai` provider entry whose `apiKeyEnv` is derived the dsh way — uppercased, non-alnum → underscore, `+_API_KEY` — plus an `agent-default-model` row). Merge is per-entry idempotent following the installer's convention: an entry already present in the patch layer is left untouched (a re-run never duplicates and never downgrades a model the user edited), missing entries are appended after a backup (`*.bak-<ts>`) so template/user entries survive, and an entry-less document (the template's bare `[]`) is replaced instead of appended to — appending after the `[]` document terminator yields an invalid two-document YAML stream the host rejects at boot. The hard guard stands: only the one `opentui` profile is ever touched. The env-gated remote live smoke gained a `DSH_SMOKE_PROFILE` knob (default `web`); against the provisioned `opentui` profile it now completes a REAL assistant turn (`MODEL_CALL ok`, text `"ok"`, `turnEnd prompt=13734 completion=19` in ~4s) instead of settling on the provider auth error — the provider key needs no environment plumbing: the host resolves `ZAI_CODING_CN_API_KEY` through its credentials service (`$DSH_HOME/.credentials.yaml` refs), shared by every profile.
+
+- **Client-mode RemoteHostSession wave 2 — session ops + peripheral clusters (ADR-0005 bucket (b) P2 wave 2; audit rows 12–28 + 17 + 22).** `RemoteHostSession` grows from the wave-1 turn core to nearly the full HostSession surface via three new modules. `src/client/remote-session-ops.ts` is the session ops cluster: `listSessions` (`session/list` + the client-side retention filter of host-session.ts:208-240 parity — subagent rows out, retention-days cutoff by updatedAt, newest first, capped), `storedTranscript` (the `session/follow` opening snapshot replayed on a SECOND facade, with backwards `session/page` fills), `renameSession` (`session/rename`), `forkAtTurn` (`session/fork {atSeq?}` — omission = latest completed-turn prefix — plus facade switch onto the host-minted fork id), `searchSessions` (`session/search` → items {sessionId, snippet} + hasMore; OPT-IN on the wire and disabled on this deployment — the index is `openAt: never`, so the facade degrades to the exact HostSession `[]` parity), `listSkills`/`refreshSkills` (`skills/list`, the session-composed human-invocable catalog, non-activating), `listHostCommands`/`executeHostCommand` (`commands/list` / `commands/execute`, agent-scoped), and `RemoteTailSession` — the read-only foreign-id tail (row 17) riding a non-activating `session/follow` with `session/page` gap repair, plus the client-side turn grouping (`historyTurns`) from the follow record ledger. `src/client/remote-model.ts` is the model cluster: `modelCatalog` (`session/modelCatalog` — provider groups with models/reasoning efforts, failures, and `default`, which IS the row-22 cold-boot label source; the in-process `agentDefaultModel.currentSelection()` one-shot has no 1:1 remote), `selectModel` (`session/selectModel` round-trip — the host-resolved selection is durable per SESSION and applies to its NEXT request; the facade applies it to the live session when one exists, else stages it onto the session the next turn creates, unlike in-process `switchModel` which only affected the NEXT session), and the provider catalog (`llm/listConfigurableProviders` / `llm/listProviders`). `src/client/remote-settings.ts` is settings + credentials (rows 24–25): `settingsDescribe`/`settingsMutate`/`settingsUpdate`/`settingsReplace` — `settings/describe` returns the DOCUMENT view ({writable, hasDocument, namespaces[]}) on the wire and is shaped client-side to the flat rows the /login route-registration double-write and the /settings browser consume; `mutate`/`update`/`replace` take the revision seen at read time as `expectedRevision` (a stale editor is refused, not silently overwritten); credentials cross the wire value-free (`credentials/describe(refs)` → {configured, source?, writable}, writes via `credentials/set`/`unset`; the /login registration double-write stays client-side), exposed as `credentialStatus`/`login`/`logout`; presets round it out (`agentPresets/list|read|select`). Facade polish on the wave-1 core: the mid-turn compact-stream replay now dedupes at the dense index already streamed (clean replay after reconnect, no doubled deltas), a journal gap the snapshot window cannot reach is repaired from `session/page` before the live frames resume, a fuller `status` surface ({connection, turn: idle|starting|running|reconnecting, sessionAttached, tailActive}), and wire-verified usage assignment semantics (row 5): every usage chunk ASSIGNS the fields it reports, completion accumulates over the session, and the context size is prompt + cacheRead + cacheWrite on cache-splitting adapters (their `prompt` is uncached input only). `$events` push frames route to facade listeners: `settings/document-updated` (ns, revision), `commands/change`, `plugin-manager/changed` (auto-refreshes the plugins cache), `credentials/reference-updated`; `listPlugins`/`refreshPlugins` ride `pluginManager/listPlugins` (+`listBundles` versions, built-ins out). Idle-release (row 16) is HOST-NATIVE — the host owns the writer lock and the follow read needs none, so there is no client-side lease machinery. Tests: `test/remote-session-ops.test.ts` + `test/remote-model-settings.test.ts` over the shared `test/client-fakes.ts` fakes, plus the extended env-gated live smoke (wave-2 capability sweep: list/replay/rename/fork/search/model/presets/commands/skills/plugins/tail, 2/2 with real model calls); 152 green tests in `packages/shell` (2 env-gated live-smoke skips); contract background in `docs/adr/0005-client-mode.md` and `docs/client-mode-protocol-audit.md`.
+
+- **Client-mode entry — `--client` boots the end-to-end bun TUI client (ADR-0005 P3, bucket (c)).** `src/client-entry.tsx` chains the boot behind injectable seams (`bootClient()`, faked in `test/client-entry.test.ts`): `ensureHost({profile:'opentui', idleExitSec:60})` → `ClientConnection({authority, cookieHeader})` → `RemoteHostSession` → `bootRuntime` render of ShellHost — with ZERO ShellHost edits: the remote session rides the HostSession type under the compile-time `ShellSessionSurface` conformance guard (`src/client/shell-session.ts`, fails tsc on surface drift instead of surfacing as a boot crash), and the turn-end hand-off is wrapped client-side (`aggregateTurnContext`) so the 🧠 status-bar context percent reads `prompt + cacheRead + cacheWrite` (the wave-2 row-5 wire finding) while the plugin bundle stays byte-identical (dist-host zero-diff gate). Workspace is the launch cwd (decision 1 — session/create cwd, welcome banner, powerline git probe, workspace overlay all key off it); theme comes from `configLoad().theme` read AFTER `session.start()` (overlay cache warm; `DSH_OPENTUI_THEME` still wins in ShellHost); the render waits (bounded) for the cold-boot model label so the powerline paints the real provider/model from first paint. Every exit path (`/quit`, Ctrl+C, renderer exit, SIGINT/SIGTERM/SIGHUP) funnels through `dispose()` → `host.release()` — never `host.dispose()` — and a LAST-REF release spawns the DETACHED idle reaper (`scripts/idle-reaper.mjs`): the lifecycle's idle timer is `unref()`ed and would die with the quitting client, orphaning the resident host forever; the reaper idles the host out after the grace window (SIGTERM→SIGKILL) and clears the lockfile, unless a fresh boot replaced the host or a client re-attached inside the window (established connections to the host port = the adoption liveness marker; behavioral tests in `test/idle-reaper.test.ts`). The jsx preload lesson: bun transpiles the whole import graph before executing, so a runtime-only transform registration is too late for kit's .tsx modules — the `@opentui/solid/preload` import stays FIRST in the entry AND the launcher passes `bun --preload …/preload.js` explicitly (bunfig.toml only applies from packages/shell's cwd, while the client launches from arbitrary workspaces). Launcher `./dsh-opentui --client`: the DEFAULT stays plugin mode until P6 (E2E topology gates) flips it. Evidence (tmux captures): boot shows the provisioned profile's real model label (`zai-coding-cn/glm-5.3-flash`), workspace prompt and themed welcome from the first paint; a real turn ("say ok" → "ok") lands with the aggregated `🧠 13.7k(11%)` context segment plus `⎇ main` / `💬 2` on the status bar. 205 pass / 3 env-gated live-smoke skips in `packages/shell` (kit 12, runtime 5); contract background in `docs/adr/0005-client-mode.md` and `docs/client-mode-protocol-audit.md`.
+
+### Changed
+
+- **License switched from MIT to Apache-2.0.** The repo ports component-level code from MIT-licensed projects (opencode, `@opentui/solid`); their original MIT statements are preserved in the root `NOTICE` file, which also ships inside the npm package. Previously published versions remain MIT-licensed as released.
+
+- **Client-mode RemoteHostSession wave 3 — full parity, no degradations (stub promotion).** The audit rows the wave-1 facade shipped as HostSession-shaped stubs (30–33, 35–37) are now real implementations, and the facade's config seam is no longer a passthrough: `configLoad()` reports the merged view (profile config.json base ⊕ workspace config.yml ⊕ environment) instead of the bare profile file, and `configSave()` splits the patch — overlay-managed keys (`theme`, `model`) route into the workspace `./.dsh/config.yml` (frozen `saveWorkspaceConfig` API: atomic 0600, credential guard), plugin keys (`retentionDays`, favorites, …) persist into the profile config.json — HostSession persistence parity on the same files plugin mode used (single machine). The v1-full-parity consequence stands: every in-process HostSession consumer seam behaves identically over the wire, with the only degradations being the audit-documented ones (search opt-out, exec-mode default not wire-visible), each with its client-side parity answer.
+
+- **Client-mode RemoteHostSession wave 3 — full parity, no degradations (ADR-0005 bucket (b) P2 wave 3; audit rows 29–30, 35–39, 41 + gaps 2/4).** Five new modules close the last audit rows; the clusters: `src/client/remote-local-fs.ts` gives /agents read/write + the /repair scan over `<dshHome>/agents/*.md` client-locally (single-machine topology, no Remote FS namespace), with ONE deliberate divergence from host-session.ts: the host copy's "insert into existing frontmatter" branch is dead (its regex never matches), so adding a field to a file that already had frontmatter prepended a SECOND frontmatter block — the client copy fixes the regex and documents the bug in its header. `src/client/remote-restart.ts` is /reload (audit row 29 + gap 2 — no remote live-plugin reload exists): per the ADR-0005 user decision the host restarts in place on the SAME authority — lifecycle lockfile (pid + port), SIGTERM with SIGKILL escalation, stale-lockfile removal, detached respawn `--no-open --port <same>`, a port-quiet gate (the old listener must actually release before the wait-for-listener probe), then cookie re-mint with the first-boot retry window; P1's carrier keeps retrying its authority forever and wave-2's re-attach replays the missed durable rows, so the restart is invisible beyond the reconnect label. The narrow SIGTERM→fresh-listener port-reuse race window is documented and accepted for v1; the full lifecycle-managed restart lives behind the `restartHost` override seam (P3 rendering-decouple path). `src/client/remote-btw.ts` is /btw: no one-shot throwaway-agent RPC exists on the wire, so the client mints a real throwaway session (durable marker title prefix, main session's context untouched) and REUSES the previous throwaway id for back-to-back questions — a one-session pollution cap instead of one session per question — with client-side filtering keeping throwaways out of session lists. `src/client/remote-subagents.ts` is the subagent panel aggregation: adoption of in-flight children, child follow, and steer/interrupt, with a typed `subagent/not-resumable` error surface (one-shot/non-continuable children refuse remote resume instead of failing opaquely). `src/client/remote-attachments.ts` is /attach + tool-result images (audit rows 35–36): the audit offered receipts OR inline image parts, and the receipt route is rejected on live-verified evidence — a `{type:'file', receiptId}` prompt part answers `session/attachment-invalid` (ATTACHMENT_NOT_REFERENCED) on read-back because `session/attachment` serves admitted IMAGE references only, and a staged receipt goes stale across /new/abort; the chosen route is the inline image part (`{type:'image', mediaType, data}` admitted by the host BEFORE message creation into the durable ImageAttachmentRef, extension allowlist + leaf display name parity), with admitted ids read from the follow journal for the round-trip surface; tool-result image bytes ride the authenticated `GET /api/file?path=…` (cookie-authed, 20 MiB cap → 413). Plus two seams: `src/client/remote-exec-mode.ts` (audit row 37) drives executionMode from the preset document — the deployment default is NOT wire-queryable (audit §4 candidate), and the plugin-inventory route carries no config; `src/client/remote-git.ts` (audit row 39 + gap 4) keeps the powerline git segment on its client-local `git branch --show-current` probe (ShellHost.tsx:277-295 semantics: workspace cwd, 3s timeout, silent "" on non-repos). Tests: `test/remote-wave3-local.test.ts` + `test/remote-btw-restart.test.ts` + `test/remote-subagents.test.ts` over the shared fakes, plus the wave-3 live-smoke sweep (agents/repair/attach/btw/reload/git on a scratch DSH_HOME — 3/3 previously run); 192 green tests in `packages/shell` (3 env-gated live-smoke skips); contract background in `docs/adr/0005-client-mode.md` and `docs/client-mode-protocol-audit.md`.
+
+### Fixed
+
+- **solid-js client build pinned install-proof.** Under the host's node runtime solid-js's `node` export condition resolves to `dist/server.js` (SSR, no reactive scheduling): the TUI rendered one frame and went dead — most visible in the rich-markdown path (a markdown table froze the screen). The fix rewrites the installed package's exports to the client build, but plain `pnpm install` wiped it. Now registered as a pnpm `patchedDependencies` patch (`patches/solid-js@1.9.12.patch`) in the profile, so every install re-applies the pin; the direct rewrite stays as belt-and-braces. Also adds `packages/shell/scripts/sync-profile.mjs` (`npm run sync`) — the local deploy loop (build → rsync dist-host into the profile → keep the pin) that used to be manual shell work. Verified: two forced `pnpm install` rounds keep the pin and the dist-host overlay, 19/19 e2e, parity gate green, real-host markdown-table scenario renders a full bordered table.
+
+## [0.4.0] - 2026-10-30
+
+### Added
+
+- **Idle lock release (the lock half of the cross-surface takeover contract).** A dsh-opentui TUI used to hold its session's kernel write lease forever, so the phone's `/resume` against any open TUI session degraded to a read-only watch that nothing (short of quitting the TUI) ever released. After `idleReleaseSec` without input or a running turn (plugin config, default 600s, `0` disables) the write handle is disposed — the kernel lease frees with it and the transcript stays on screen. The next send re-attaches the SAME session id and folds in the durable user/assistant rows other surfaces (phone, second TUI) wrote while released (`onReattachedMissed`, spliced ahead of the prompt row); a lease meanwhile won by another surface fails the wake with an actionable error and keeps the id for a retry. `abort()` keeps its `/new` semantics (fresh id on the next send); an explicit resume still wins over the reattach. Verified: 6 new HostSession contract tests (release, same-id wake, missed-rows fold, owned-refusal, abort/resume precedence, disable switch), monorepo `bun test` green, both packages typecheck clean, and the packed-tarball real-host boot smoke.
+
+## [0.1.0] - 2026-10-29
+
+First public release of `@aiwayds/dsh-opentui`.
+
+### Added
+
+- Host profile mode: first launch of the `dsh-opentui` bin idempotently installs a dsh profile (`~/.dsh/profiles/dsh-opentui`, bundles `dsh-base` + this package) and pins the model via a cordis patch (`llm-pi-ai` provider routing + `agent-default-model`, default `zai-coding-cn/glm-5.3-flash/high`); `--provider` / `--model` / `--reasoning-effort` override at install time. The plugin runs inside the real dsh host process (OpenTUI + Solid; node >= 26.4 with `--experimental-ffi`, auto-injected by the bin).
+- Slash command panel (`/help`, `/model`, `/usage`, `/clear`, `/quit`).
+- Themeable UI with theme tokens shared through `@dsh-opentui/kit`.
+- Runtime model switching (`/model provider/id`).
+- Markdown rendering for replies.
+- Custom line editor (input history, cursor editing).
+- Standalone compiled binary distribution (direct mode, bypassing the host).
+- Declarative surface protocol (`ctx.surface.declare(...)`) for zero-build plugin integration.
+- `starter/` copyable plugin template.
+
+### Changed
+
+- Plugin sources are distributed and mounted through the npm package / installed profile instead of repo-local `link:` mounts.
+
+### Fixed
+
+- Kitty keyboard protocol: Ctrl+C no longer kills the TUI unexpectedly; it is handled as the abort/quit key.
+
+[0.1.0]: https://github.com/fan56/dsh-opentui/releases/tag/v0.1.0
+[0.5.0]: https://github.com/fan56/dsh-opentui/releases/tag/v0.5.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 fan56
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,63 @@
+dsh-opentui
+Copyright 2026 fan56
+
+This product includes software developed by fan56 as part of the
+DeepSeek Harness (dsh) project.
+
+This product contains code ported at the component level from the
+following third-party projects. Their original MIT license statements
+are preserved below as required by those licenses.
+
+--------------------------------------------------------------------------------
+
+opencode
+https://github.com/sst/opencode
+
+MIT License
+
+Copyright (c) 2025 opencode
+
+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.
+
+--------------------------------------------------------------------------------
+
+@opentui/solid (OpenTUI)
+https://github.com/anomalyco/opentui
+
+MIT License
+
+Copyright (c) 2025 opentui
+
+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,132 @@
+# dsh-opentui
+
+A next-generation TUI **platform** for [dsh](https://github.com/deepseek-ai/dsh) —
+new architecture, not a reskin of dsh-tui-pi. Built on
+[OpenTUI](https://github.com/anomalyco/opentui) + [Solid](https://solidjs.com),
+running on Bun.
+
+The repo's product is the **architecture**; the shipped Shell is a working
+chat agent TUI on top of it:
+
+| Package | What it is |
+|---|---|
+| `@dsh-opentui/runtime` | Engine lifecycle, cordis `surface` service, stdout capture, protocol types |
+| `@dsh-opentui/kit` | Shared components: theme tokens, `t()` i18n seam, status bar, panel, line |
+| `@dsh-opentui/shell` | **Usable chat TUI**: ask → thinking stream → tool approval → reply |
+| `starter/` | Copyable plugin template; consumes the surface protocol with zero build step |
+
+See [CONTEXT.md](CONTEXT.md) for the glossary and [docs/adr/](docs/adr/)
+for decisions: Solid (0001), two integration channels with no compat shim
+(0002), Bun + compiled binary distribution (0003), host profile route (0004).
+
+## Install
+
+Prerequisites:
+
+- The dsh host: `npm i -g @deepseek-ai/dsh` (or your official channel)
+- Node >= 26.4 (OpenTUI's native core needs `--experimental-ffi`, injected for you)
+- pnpm
+
+```bash
+npm i -g @aiwayds/dsh-opentui
+dsh-opentui
+```
+
+The first launch idempotently installs a dsh profile at
+`~/.dsh/profiles/dsh-opentui` (bundles: `dsh-base` + this package) and pins
+the default model through a cordis patch (`llm-pi-ai` provider routing +
+`agent-default-model`: `zai-coding-cn/glm-5.3-flash/high`). Afterwards
+`dsh-opentui` is equivalent to `dsh --profile dsh-opentui`.
+
+To change the model, re-run the installer with flags
+(`--provider` / `--model` / `--reasoning-effort`) or edit the profile's
+`cordis.patch.yml` directly.
+
+Prefer to run without the host? See
+[Direct mode (development)](#direct-mode-development).
+
+## Run as a dsh profile (host mode)
+
+The Shell runs inside the real dsh host as a profile. The `dsh-opentui`
+bin handles everything: on first launch it installs the profile, then it
+execs the host with the profile flag and injects `--experimental-ffi` for
+you. After the first run, `dsh-opentui` is equivalent to:
+
+```bash
+NODE_OPTIONS=--experimental-ffi dsh --profile dsh-opentui   # manual fallback
+```
+
+| What | Where |
+|---|---|
+| Profile | `~/.dsh/profiles/dsh-opentui` (bundles: `dsh-base` + `@aiwayds/dsh-opentui`; model pinned via `cordis.patch.yml`) |
+| Runtime | node >= 26.4 with `--experimental-ffi` inside the host (auto-injected by the bin) |
+| Model & keys | reused from the host's own config; override the pinned default via installer flags or the patch file |
+
+## Direct mode (development)
+
+Without the host, useful for hacking on the Shell itself:
+
+```bash
+cd ~/repo/dsh-opentui/packages/shell
+bun src/main.tsx                      # dev run
+bun src/main.tsx --model zai-coding-cn/glm-5.2   # explicit model
+bun build.ts && ../../build/dsh-opentui-darwin-arm64   # standalone binary
+```
+
+**Config reuse**: the Shell reads your existing dsh config — model default
+comes from `~/.dsh/model-profiles.json` (current profile's workhorse
+agent), provider baseUrls from `~/.dsh/models-store.json`, API keys from
+`~/.dsh/.credentials.yaml`. Override with `--model provider/id` or
+`DSH_OPENTUI_MODEL` / `DSH_OPENTUI_API_KEY`.
+
+**In the TUI**: type a question, Enter to send. The model's thinking
+streams dim; tool calls (bash / read_file / write_file) pop an approval
+card — `y` allow, `n` decline; `esc` aborts a running turn. Commands:
+`/help` `/model [provider/id]` `/usage` `/clear` `/quit` (or Ctrl+C).
+
+## Plugin integration, 30 seconds
+
+**Layer 2 (declarative, zero build)** — inject the surface service:
+
+```ts
+import type { Context } from "@deepseek-ai/cordis"
+import { hasSurface } from "@dsh-opentui/runtime"
+
+export function apply(ctx: Context) {
+  if (!hasSurface(ctx)) return // headless: no surface host mounted
+  ctx.surface.declare({
+    kind: "widget", slot: "status", id: "myplugin.state",
+    parts: [{ text: "myplugin", dim: true }, { text: " ok", color: "#50fa7b" }],
+  })
+}
+```
+
+**Layer 1 (Solid components)** — depend on `@dsh-opentui/kit` and write
+components; add vite + babel-preset-solid to your build.
+
+## Develop
+
+```bash
+npx pnpm@10.18.3 install
+cd packages/shell && bun src/main.tsx   # run the shell
+bun test                                # tests (repo root)
+npx pnpm@10.18.3 -r typecheck
+```
+
+To test host mode against local sources, point the installed profile at the
+repo via `link:` mounts, then rebuild after changing plugin sources:
+
+```bash
+cd packages/shell && bun build-host.ts
+```
+
+Requires Bun >= 1.3.14 (`bun upgrade`). Note: each package carries its own
+`bunfig.toml` (the @opentui/solid preload) — bun only reads the CWD's
+bunfig; a root-level one breaks compiled binaries ("preload not found").
+
+## Status
+
+v0.1.0: published as `@aiwayds/dsh-opentui` (host profile mode via the
+`dsh-opentui` bin, direct-mode binary). Roadmap: host seams
+(approval waterfall, ask, attachments, sessions via the real dsh host) ·
+full Kit + starter polish · linux binary release pipeline.