zcode-acp-server 0.21.3 → 0.22.0

package/docs/REMOTE-CLIENTS.md

@@ -57,7 +57,7 @@ ACP editor ────── stdio ──────────┘
 | `POST /api/upgrade`                                    | required | Trigger the hub's own staleness check — see [Hub self-upgrade](#hub-self-upgrade).                                                                          |
 | `GET /api/projects`                                    | required | Known-project list (remote session-create whitelist) — see below.                                                                                           |
 | `GET /api/projects/sessions?workspacePath=`            | required | A project's full session store incl. closed ones — see [Resuming a closed session](#resuming-a-closed-session).                                             |
-| `POST /api/instances {workspacePath[, sessionId]}`     | required | Create a bridge for one known project — a visible terminal REPL (session-create) or one that boots into a closed session (resume, `sessionId`) — see below. |
+| `POST /api/instances {workspacePath[, sessionId]}`     | required | Create a bridge for one known project — a visible terminal TUI window (session-create) or one that boots into a closed session (resume, `sessionId`) — see below. |
 
 HTTP auth: `Authorization: Bearer <token>` or `?token=<token>`.
 
@@ -161,7 +161,7 @@ POST {hub}/api/instances  body {"workspacePath":"/Users/me/proj"}
   bound, not a security boundary: a token holder can already run any
   editor-bridge session in an arbitrary cwd; the trust boundary is the
   token itself.
-- On create the hub incubates a VISIBLE interactive REPL in the machine's
+- On create the hub incubates a VISIBLE interactive TUI (Martty) in the machine's
   terminal (ADR-0016, macOS): the project's owner gets a real local CLI
   window, and its bridge registers with the hub like any serve instance (it
   appears in `/api/instances` with `origin:"serve"` — allow up to ~20s for
@@ -190,7 +190,7 @@ POST {hub}/api/instances  body {"workspacePath":"/Users/me/proj"}
   spawn instead of racing a duplicate. A client that wants a HEADLESS attach
   should not POST at all — attach to the instance id the history listing
   already returns.
-- Lifetime depends on the surface: a terminal-REPL instance lives while its
+- Lifetime depends on the surface: a terminal-TUI instance lives while its
   window lives (the owner closing it retires the bridge — re-create on
   demand); the headless fallback exists for remote interest only and exits
   ~10 minutes after the last client detaches AND the last running turn
@@ -249,16 +249,20 @@ POST {hub}/api/instances  body {"workspacePath":"/Users/me/proj",
   replays and the conversation continues with `session/prompt`, entirely in
   the client. A cold project (no listing yet) lists first — the listing IS
   the headless incubator.
-- **Resume on the desktop (ADR-0017)**: `POST /api/instances` with the
-  `sessionId` too — the hub incubates a VISIBLE terminal REPL that boots
-  straight into that conversation (history replays in the window; the same
+- **Resume on the desktop (ADR-0017, amended by ADR-0020)**: `POST
+  /api/instances` with the `sessionId` too — the hub incubates a VISIBLE
+  terminal TUI window that boots straight into that conversation (the same
   terminal/`ZCODE_ACP_HUB_TERMINAL` selection and headless fallback as
-  session-create). This happens EVEN when a serve bridge is already live
+  session-create). The window lands on the right session — later prompts run
+  with the full history in the backend — but the TUI does not render the
+  previous transcript (a fresh boot is a session/new and `/resume` prefers
+  session/resume, which carries no history by protocol design; its status
+  line says `resumed <id> — previous transcript was not replayed`). This happens EVEN when a serve bridge is already live
   (the listing incubated one) — the answer is always the NEW instance, the
   bridge the window runs on; attach to it and `session/load` the same id to
   follow along in the client (both surfaces then share one bridge, one
-  backend process). A bogus id still opens the window: the REPL shows the
-  load failure and falls back to a fresh session. Resuming the same session
+  backend process). A bogus id still opens the window: the bridge logs the
+  load failure and starts a fresh session instead. Resuming the same session
   twice pops two windows; only identical concurrent requests share one
   incubation.
 - `sessionId` here is the backend store id (`sess_…`), which `session/load`

package/docs/REMOTE.md

@@ -73,7 +73,8 @@ directories filtered out), newest activity first. The list gates the POST —
 paths outside it get 403 (a convenience bound, not a security boundary: a
 token holder can already drive an editor-bridge session in any cwd; the
 trust boundary is the token). On create the hub incubates a VISIBLE
-interactive REPL in the machine's terminal (ADR-0016, macOS; headless/SSH or
+interactive TUI window in the machine's terminal (ADR-0016 as amended by
+ADR-0020, macOS; headless/SSH or
 `ZCODE_ACP_HUB_TERMINAL=0` falls back to the detached headless
 `zcode-acp serve`); its bridge registers back within seconds (budget ~20s)
 and is reachable like any other instance. The hub itself is a background
@@ -83,9 +84,10 @@ resolves as `ZCODE_ACP_HUB_TERMINAL_COMMAND` → `ZCODE_ACP_HUB_TERMINAL_APP`
 Ghostty; other names pass through to `open -a`) → plain Terminal.app. Warp
 cannot execute scripts or commands programmatically (warpdotdev/warp#1917,
 #3959) and is deliberately unsupported — it degrades to the headless bridge.
-A live serve-origin instance for
-the same workspace is reused instead of re-spawned (`reused:true`). A
-terminal-REPL instance lives while its window lives; the headless fallback
+Create NEVER reuses a live serve-origin instance (ADR-0016 as amended) —
+every create incubates its own window, and identical concurrent requests
+join the same in-flight spawn. A
+terminal-TUI instance lives while its window lives; the headless fallback
 exits ~10 minutes after the last client detaches and the last turn
 finishes. Session roots are pinned to the project cwd in both surfaces
 regardless of what a client sends.
@@ -109,15 +111,11 @@ editor uses — attaching by id joins the conversation's live notification
 stream, and the hub dedupes sessions shared by several bridges of the same
 project.
 
-**The local REPL is a hub client too** (ADR-0018). Bare `zcode-acp` in a
-shell with the hub env (`ZCODE_ACP_REMOTE_TOKEN` + `ZCODE_ACP_HUB_PORT`)
-merges sessions that are live on hub instances into its `/sessions` picker
-(marked `live`, `●` while a turn runs) and attaches to them through the hub's
-WS proxy as a second ACP client — replay on attach, then live updates, so a
-conversation being driven from the phone advances on the desktop in real
-time. Without a hub configured or reachable, the picker and resumes behave
-exactly as before. Attaching never touches the owning bridge: leaving the
-REPL (or `/new`) only detaches this client.
+**The local TUI used to be a hub client too** (ADR-0018, removed with the
+in-house REPL by ADR-0020). The Martty TUI boots its own bridge per window
+and does not merge hub-live sessions into its picker; watching a session
+driven from another client stays a remote-App capability (the hub's WS proxy
+and the `/api` surface are unchanged).
 
 Auth is `Authorization: Bearer <token>` or `?token=` (browsers cannot set WS
 headers); `/api/*` sends `Access-Control-Allow-Origin: *` — the token is the

package/docs/TROUBLESHOOTING.md

@@ -405,7 +405,33 @@ requests themselves.
 `~/.zcode/v2/config.json` marks it `enabled`). The bridge answers the captcha
 request with `headersApplied:false` and the backend surfaces a clear error;
 full Start Plan support headless would require solving the Aliyun captcha
-outside a browser, which this bridge does not do.
+outside a browser, which this bridge does not do. That boundary is
+deliberate: unofficial clients or proxies that impersonate the desktop app or
+bypass the captcha check won't be shipped or supported here — if the provider
+ever offers an official headless credential path, this bridge will adopt it
+(see #123).
+
+### Interactive TUI / `script` / `expect` fails with `Operation not permitted` under the sandbox
+
+**Symptom:** inside an armed Seatbelt sandbox, pseudo-terminal allocation
+fails (`script: openpty: Operation not permitted`, or a TUI binary dying at
+terminal init with `os error 1`); the same binaries run fine headless.
+
+**Cause:** `openpty` opens `/dev/ptmx` and the granted `/dev/ttysNNN` pair
+`O_RDWR`, and the write half used to collide with the profile's blanket
+`file-write*` deny. Since the fix, the profile allows exactly those two write
+targets — the slave allow is gated on the sandbox pty extension, mirroring
+Apple's own `application.sb`/`com.apple.neagent.sb` profiles, so only slaves
+cloned through the sandbox's own `ptmx` opens are writable. Upgrade the bridge
+if you still see this.
+
+**Diagnosis tip:** a syscall-level sandbox denial has **no ask popup** (the
+dynamic-allow flow only triggers on write-path denials) and surfaces in the
+child as a bare `EPERM`, which tools may misreport as their own bug. When the
+backend runs sandboxed, the bridge logs a one-shot warning the first time a
+tool output contains `Operation not permitted` — that warning is your signal
+to suspect the sandbox. Path grants for legitimate writes go in
+`.zcode/acp/sandbox.json`.
 
 ## Log Debugging
 

package/docs/adr/0007-unified-cli-entry-and-bin-pruning.md

@@ -1,5 +1,7 @@
 # Unified CLI entry and bin pruning
 
+> Amended by ADR-0020 (`.zcode/docs/adr/`): bare invocation now launches the Martty TUI — the in-house Ink REPL is deleted; the subcommand surface is unchanged.
+
 The package grew three separate bins (`zcode-acp-server`, `zcode-acp-hub`,
 `zcode-quota`) plus a planned terminal chat surface. Installing four sibling
 commands for one tool is noisy, and each new surface would add another. We

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.21.3",
+  "version": "0.22.0",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,15 +43,12 @@
     "format": "prettier --write src",
     "lint": "eslint .",
     "smoke": "node dist/index.js < /dev/null",
+    "smoke:tui": "node dist/cli.js tui --check",
     "prepublishOnly": "pnpm run build && pnpm run test"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.3.0",
-    "chalk": "^6.0.0",
-    "ink": "^7.1.1",
-    "ink-spinner": "^5.0.0",
-    "react": "^19.2.8",
-    "string-width": "^8.2.2",
+    "martty": "^0.2.34",
     "ws": "^8.21.3"
   },
   "peerDependencies": {
@@ -60,7 +57,6 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@types/node": "^22.0.0",
-    "@types/react": "^19.2.18",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",

package/dist/repl/App.d.ts

@@ -1,108 +0,0 @@
-/**
- * Ink UI for the interactive REPL (bare `zcode-acp`).
- *
- * Rendering model: the whole app draws in a fixed-height frame managed by
- * run.ts (full-screen mode) — the transcript is an in-app viewport, and the
- * live turn (streaming text, thinking buffer, tool rows), prompt line, and
- * pickers render inside it. A pending permission request takes over the
- * input area with an arrow-key picker.
- */
-import { type ReactElement } from "react";
-import { type ReplEntry, type ReplStatus, type SessionSummary, type TurnState } from "./model.js";
-import { type LineEditor } from "./input-buffer.js";
-/** A permission request awaiting the user's choice. */
-export interface PermissionPrompt {
-    /** Box heading ("permission requested" / "plan approval"). */
-    heading: string;
-    title: string;
-    /** Long body shown under the title (e.g. the plan text for ExitPlanMode). */
-    detail?: string;
-    options: Array<{
-        id: string;
-        name: string;
-    }>;
-}
-/** A question awaiting the user's answer (AskUserQuestion via elicitation). */
-export interface QuestionPrompt {
-    title: string;
-    multiSelect: boolean;
-    options: Array<{
-        value: string;
-        label: string;
-    }>;
-}
-/** The interactive `/sessions` picker: resumable project sessions. */
-export interface SessionPick {
-    items: SessionSummary[];
-}
-/** A picked question answer: chosen option values plus an optional custom text. */
-export interface QuestionAnswer {
-    picked: string[];
-    custom: string;
-}
-/** Display state of the question picker (selection, toggles, custom typing). */
-export interface PickerState {
-    index: number;
-    /** null = option list active; string = custom-answer input in progress. */
-    custom: string | null;
-    toggled: string[];
-}
-export interface AppProps {
-    /** Completed transcript entries — printed once into native scrollback. */
-    entries: ReplEntry[];
-    /** Live turn in progress, null when idle. */
-    turn: TurnState | null;
-    /** Pending permission request, null when none. */
-    permission: PermissionPrompt | null;
-    /** Pending AskUserQuestion, null when none (renders instead of the input). */
-    question: QuestionPrompt | null;
-    /** Pending /sessions picker, null when closed. */
-    sessionPick: SessionPick | null;
-    /** Prompts accepted but waiting for the running turn to finish. */
-    queued: string[];
-    /** Session status: command menu + model/mode/thought selects. */
-    status: ReplStatus;
-    /** True while the bridge/session is starting up. */
-    busy: boolean;
-    /**
-     * True while a /sessions resume is replaying history. Replayed updates
-     * fold silently into run.ts's buffers — rendering per message made big
-     * sessions freeze the UI, so App just shows this one-line progress hint.
-     */
-    replaying: boolean;
-    /**
-     * The prompt line's editor state (text + caret), owned by run.ts's
-     * external store so submit paths can reset it and rerender snapshots
-     * stay pure functions of that state.
-     */
-    editor: LineEditor;
-    /** Apply one pure editor op to the prompt line and repaint. */
-    applyEdit: (op: (e: LineEditor) => LineEditor) => void;
-    /** Compact plan-quota suffix for the status row (null = not fetched yet). */
-    quotaLine: string | null;
-    /**
-     * Live completion-menu visibility. InputLine mirrors it out of its React
-     * state on every render (same external-store rationale as the editor), so
-     * the app-level key handler can give the menu first claim on esc.
-     */
-    isMenuOpen: () => boolean;
-    /** InputLine → external store: publish the current menu visibility. */
-    onMenuOpenChange: (open: boolean) => void;
-    onSubmit: (text: string) => void;
-    onCancelTurn: () => void;
-    onAnswerPermission: (optionId: string | null) => void;
-    onAnswerQuestion: (answer: QuestionAnswer | null) => void;
-    /** null = dismiss the picker without resuming. */
-    onPickSession: (sessionId: string | null) => void;
-    /** Prompt-history recall (ADR-0008); run.ts no-ops when nothing to walk. */
-    onHistoryUp: () => void;
-    onHistoryDown: () => void;
-    onExit: () => void;
-}
-/**
- * Colorize markdown code fences: lines between ``` fences render cyan. Line
- * level state machine — exported for unit tests.
- */
-export declare function colorizeCodeFences(text: string): string;
-export declare function App(props: AppProps): ReactElement;
-//# sourceMappingURL=App.d.ts.map

package/dist/repl/App.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../../src/repl/App.tsx"],"names":[],"mappings":"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"}