commandmate 0.27.1 → 0.28.0

package/dist/server/src/lib/session/current-output-builder.js

@@ -14,13 +14,20 @@ const db_1 = require("../../lib/db");
 const unclassified_frame_tracker_1 = require("../../lib/detection/unclassified-frame-tracker");
 const composer_text_1 = require("../../lib/detection/composer-text");
 const upstream_faults_1 = require("../../lib/detection/upstream-faults");
+const opencode_pane_obstruction_1 = require("../../lib/detection/opencode-pane-obstruction");
 const models_1 = require("../../types/models");
 const logger_1 = require("../../lib/logger");
 const manager_1 = require("../../lib/cli-tools/manager");
 const types_1 = require("../../lib/cli-tools/types");
 const registry_1 = require("../../lib/hooks/sources/registry");
+const define_source_1 = require("../../lib/hooks/sources/define-source");
+const subscription_1 = require("../../lib/hooks/sources/opencode/subscription");
 const permission_decision_state_1 = require("../../lib/hooks/permission-decision-state");
 const tool_input_normalization_state_1 = require("../../lib/hooks/tool-input-normalization-state");
+const agent_session_telemetry_1 = require("../../lib/hooks/agent-session-telemetry");
+const pending_decision_kind_1 = require("../../lib/hooks/pending-decision-kind");
+const diff_1 = require("../../lib/hooks/sources/opencode/diff");
+const structured_decision_response_1 = require("../../lib/hooks/structured-decision-response");
 const cli_session_1 = require("../../lib/session/cli-session");
 const status_detector_1 = require("../../lib/detection/status-detector");
 const auto_yes_manager_1 = require("../../lib/polling/auto-yes-manager");
@@ -66,13 +73,38 @@ const logger = (0, logger_1.createLogger)('current-output-builder');
  * waiting on. The tracker has already marked the run as recorded, so a failure
  * costs this one row, not a retry storm.
  */
+/**
+ * The sentence that turns "nothing could read this frame" into "here is what is
+ * on it, and here is the key that removes it" (Issue #2095).
+ *
+ * Empty string when there is no obstruction, so every caller can concatenate it
+ * unconditionally and the #1708 wording is byte-identical on a frame that has
+ * none.
+ *
+ * English, like the rest of {@link recordUnclassifiedFrame}'s row and unlike the
+ * UI banner this pairs with. The row is read in `capture --prompts` as often as
+ * in the history pane, and `commandmate` has no locale to read it in.
+ */
+function describePaneObstruction(obstruction) {
+    if (!obstruction)
+        return '';
+    return (` Cause: opencode's sidebar is sharing rows with the transcript ` +
+        `(paneObstruction=${obstruction.id}, second column reads ` +
+        `${JSON.stringify(obstruction.matchedText)}), which covers the marker that ends a ` +
+        `turn. Press \`${opencode_pane_obstruction_1.OPENCODE_SIDEBAR_RECOVERY_CHORD}\` in the pane to close it.`);
+}
 function recordUnclassifiedFrame(db, params) {
     const dwellSeconds = Math.round(params.dwellMs / 1000);
     const statusReason = `${params.sessionStatus}/${params.sessionStatusReason}`;
     const question = `Unclassified interactive frame (${statusReason}) held for ${dwellSeconds}s. ` +
         `The detection layer could not parse it, so no prompt was published and ` +
         `nothing could answer it. Inspect the raw pane with ` +
-        `\`commandmate capture ${params.worktreeId} --pane\`.`;
+        `\`commandmate capture ${params.worktreeId} --pane\`.` +
+        // Issue #2095: appended rather than substituted. Everything above is still
+        // true — the frame really was unreadable — and a caller matching on the
+        // #1708 wording keeps matching. What follows turns "we could not read it"
+        // into "here is why, and here is the key that fixes it".
+        describePaneObstruction(params.obstruction);
     const record = {
         type: models_1.UNCLASSIFIED_PROMPT_TYPE,
         status: 'unclassified',
@@ -367,6 +399,15 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     const eventSource = (0, registry_1.getAgentEventSource)(cliToolId);
     const now = Date.now();
     const pendingDecisions = (0, agent_event_state_1.getPendingDecisions)(worktreeId, cliToolId, instanceId, now);
+    // Issue #1726's episode, read once at the same `now` the decisions were read
+    // at. Issue #2040 needs it up here — a question's choices are published on the
+    // decision entry — and the degraded prompt below re-uses this read rather than
+    // taking a second one, so the two cannot describe different instants.
+    const askUserQuestion = (0, agent_event_state_1.getAskUserQuestion)(worktreeId, cliToolId, instanceId, now);
+    // Issue #2040, read once: #2042's context measurement is keyed on this
+    // record's `at`, so reading it twice would risk keying the derived block to a
+    // different instant than the one it is published beside.
+    const agentSession = (0, agent_session_telemetry_1.getAgentSessionTelemetry)(worktreeId, cliToolId, instanceId);
     const structuredEvents = {
         lastEventType: lastEvent?.event ?? null,
         lastEventAt: lastEvent?.at ?? null,
@@ -379,15 +420,31 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
         // source's declared `decisionTimeoutSeconds`. `agent-event-state` cannot
         // reach the registry — its module graph pulls in `better-sqlite3` — which
         // is why every capability arrives there as a value a caller hands over.
-        pendingDecisions: pendingDecisions.map((decision) => ({
-            id: decision.decisionId,
-            at: decision.at,
-            source: decision.source,
-            toolName: decision.toolName,
-            confirmedAt: decision.confirmedAt,
-            scraperCorroborated: decision.scraperCorroborated,
-            deliveryExpired: (0, provisional_turn_1.isDeliveryExpired)(decision, eventSource.capabilities.decisionTimeoutSeconds, now),
-        })),
+        pendingDecisions: pendingDecisions.map((decision) => {
+            // Issue #2040. Recovered rather than stored — see `pending-decision-kind`.
+            const kind = (0, pending_decision_kind_1.pendingDecisionKind)(decision.toolName);
+            return {
+                id: decision.decisionId,
+                at: decision.at,
+                source: decision.source,
+                toolName: decision.toolName,
+                confirmedAt: decision.confirmedAt,
+                scraperCorroborated: decision.scraperCorroborated,
+                deliveryExpired: (0, provisional_turn_1.isDeliveryExpired)(decision, eventSource.capabilities.decisionTimeoutSeconds, now),
+                kind,
+                // Issue #2040: the agent's own list, numbered the way `respond` numbers
+                // it — the same `questionDecisionOptions` the reply path resolves an
+                // answer against (#2039), so what is printed here and what a number
+                // means cannot come apart. Null for an approval and for a question whose
+                // payload is no longer held; never a screen's numbering.
+                questionOptions: kind === 'question' && askUserQuestion
+                    ? (0, structured_decision_response_1.questionDecisionOptions)(askUserQuestion.spec).map((option) => ({
+                        number: option.number,
+                        label: option.label,
+                    }))
+                    : null,
+            };
+        }),
         dedupDropped: (0, agent_event_state_1.getAgentEventDropCounts)(worktreeId, cliToolId, instanceId),
         dialogPendingMaxMs: { ...provisional_turn_1.DIALOG_PENDING_MAX_MS },
         promptWaitingSince: null,
@@ -403,7 +460,39 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
         source: {
             cliToolId: eventSource.cliToolId,
             capabilities: eventSource.capabilities,
+            // Issue #2054. Read through the source interface — `liveness(target)` —
+            // rather than through opencode's subscription map, so this layer keeps
+            // naming no tool: every push source answers `{ state: 'unknown' }` from
+            // `definePushHookSource` at no cost, and the fold that turns that into a
+            // published `kind` is the same one `worktree-status-helper` calls.
+            ...(0, define_source_1.describeAgentEventSource)(eventSource, eventSource.liveness({ worktreeId, cliToolId, instanceId: resolvedInstanceId }), now),
+            // Issue #2054: opencode-only by construction, and read from the module
+            // that owns the attach. `./opencode/diff` is imported here for the same
+            // reason (#2043) — the alternative is a field that exists on the wire and
+            // is filled in by nothing.
+            probedActivity: (0, subscription_1.getOpencodeProbedActivity)({
+                worktreeId,
+                cliToolId,
+                instanceId: resolvedInstanceId,
+            }),
         },
+        // Issue #2040. Read here, before the `isRunning` branch, so both return
+        // paths carry the key — but the record itself is dropped when the
+        // subscription closes, so a pane that is not running answers null without
+        // this layer needing a rule of its own.
+        session: agentSession,
+        // Issue #2042. `ensure…` never awaits: it answers from the cache and starts
+        // a refresh only when the session record has moved since the last one, so
+        // the two HTTP round trips it needs happen once per *turn* rather than once
+        // per poll and never in front of this payload. See
+        // `ensureAgentSessionContextUsage` for why that trade is the right way
+        // round here.
+        sessionContext: (0, agent_session_telemetry_1.ensureAgentSessionContextUsage)({ worktreeId, cliToolId, instanceId }, agentSession),
+        // Issue #2043, on exactly #2042's terms: `ensure...` answers from the store
+        // and starts at most one `GET /session/:id/diff` per *turn*, never in front
+        // of this payload. It answers null for every tool but opencode, so no other
+        // tool's status poll grows a field or a request.
+        sessionDiff: (0, diff_1.ensureOpencodeSessionDiff)({ worktreeId, cliToolId, instanceId }),
     };
     const running = await cliTool.isRunning(worktreeId, instanceId);
     if (!running) {
@@ -447,6 +536,9 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
             // is a claim about what is on screen right now, and a dead session has no
             // screen.
             upstreamFault: null,
+            // Issue #2095: same reasoning — a session that is not running has no pane
+            // to lay out in two columns.
+            paneObstruction: null,
             // Issue #1879: same reasoning as `upstreamFault` — there is no input box
             // on a session that is not running, so there is nothing to report and
             // nothing the UI could act on.
@@ -586,7 +678,9 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     // all while an AskUserQuestion picker is up (§5.6) and a record that asserted
     // `waiting` from the invocation would go on asserting it long after a human
     // answered in the terminal.
-    const askUserQuestion = (0, agent_event_state_1.getAskUserQuestion)(worktreeId, cliToolId, instanceId);
+    // Issue #2040 moved the read to the top of this function (the decision entries
+    // publish the same episode's choices) and this line now re-uses it, so the two
+    // surfaces cannot describe different instants.
     const scraperPromptData = statusResult.promptDetection.promptData;
     const correctedPromptData = scraperPromptData && askUserQuestion
         ? (0, ask_user_question_prompt_1.applyAskUserQuestion)(scraperPromptData, askUserQuestion.spec)
@@ -603,17 +697,63 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     // it to a dialog the agent actually reported — a `permission-request` record
     // is a prediction, and a question is answered with a choice rather than with
     // one of these three verdicts.
-    const decisionOptions = promptWaiting !== null &&
+    //
+    // Issue #2031 adds the fourth conjunct and folds the whole gate into ONE
+    // value. The three verdicts and the id they are delivered to are now derived
+    // from the same expression, so they cannot be published apart — and "apart"
+    // is not hypothetical, it is the state #1932 shipped: options were published
+    // on the capability alone while `decisionId` was published nowhere at all, so
+    // the panel drew no buttons and the only way out of an opencode approval in a
+    // browser was the arrow-key safety net. Options WITHOUT an id is the worse
+    // half of that pair — the numbers would reach the keystroke path, where a
+    // bare "1" selects whatever the picker happens to be highlighting (#1681).
+    const addressableDecisionId = promptWaiting !== null &&
         promptWaiting.source === 'notification' &&
-        eventSource.capabilities.eventIdentity === 'permission-id'
-        ? structured_prompt_1.STRUCTURED_DECISION_OPTIONS
+        eventSource.capabilities.eventIdentity === 'permission-id' &&
+        (0, structured_prompt_1.isAddressableDecision)(promptWaiting.decisionId)
+        ? promptWaiting.decisionId
         : null;
+    // Issue #2100 splits the two halves of #2031's single expression, because an
+    // addressable decision is now of two KINDS. The id is published for both — it
+    // is what `POST /respond` names, and a question needs it exactly as much as an
+    // approval does — but the three verdicts belong to an approval alone.
+    //
+    // Publishing both for a question is not a cosmetic error: it is precisely what
+    // #2039's third gate refuses. `readPromptQuestionChoices` returns null the
+    // moment `decisionOptions` is non-empty, so a question carrying them would
+    // draw `Allow once / Allow always / Reject` over the agent's own choices, and
+    // a verdict sent to a question is refused at the source
+    // (`question-needs-answer-verdict`). The kind is recovered from the record the
+    // same way `structuredEvents.pendingDecisions[].kind` is, through the one
+    // reader in `pending-decision-kind`.
+    const addressesQuestion = promptWaiting !== null && (0, pending_decision_kind_1.pendingDecisionKind)(promptWaiting.toolName) === 'question';
+    const decisionOptions = addressableDecisionId !== null && !addressesQuestion ? structured_prompt_1.STRUCTURED_DECISION_OPTIONS : null;
     const structuredFacts = promptWaiting === null
         ? null
         : {
             ...promptWaiting,
             askUserQuestion: summarizeAskUserQuestion(askUserQuestion),
             decisionOptions,
+            // Explicit, though the spread above already carries a `decisionId`
+            // off the record: the spread's copy is the raw one, and what may be
+            // published is the GATED one. Letting the record's value through
+            // would put an id on a payload whose verdicts were withheld, which is
+            // the biconditional this Issue exists to hold.
+            decisionId: addressableDecisionId,
+            // Gated on the same value, for a reason of its own: `patterns` is
+            // what the `Allow always` BUTTON grants, so publishing it where no
+            // button is drawn adds a rule list to a panel that is telling the
+            // user to go and answer in the terminal. Every source but opencode
+            // therefore keeps the exact payload it had before this Issue, plus
+            // the one `decisionId: null`.
+            //
+            // Issue #2100 moves the gate onto `decisionOptions` rather than the
+            // id, which is the same value for every approval and the honest one
+            // for a question: a question draws no `Allow always`, so it may not
+            // carry the rules one would have saved. (`reportQuestionPending`
+            // records `patterns: null` anyway; the two agree by construction now
+            // instead of by coincidence.)
+            patterns: decisionOptions !== null ? promptWaiting.patterns : null,
         };
     const promptData = scraperPromptWaiting
         ? correctedPromptData ??
@@ -643,6 +783,19 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
             applied: merged.structuredApplied,
         });
     }
+    // Issue #1839 defined this window and Issue #2095 reuses it, so it is computed
+    // once, here, above the first reader. The 100 rows are also what the payload
+    // publishes, which is the property both fields rest on: what they claim can be
+    // checked against the rows printed next to them in `capture --json`.
+    const realtimeSnippet = lines.slice(-100).join('\n');
+    // Issue #2095: gated on the tool because the anchors are opencode's own box
+    // drawing. Every other CLI's detection is untouched by construction — nothing
+    // here even looks at its frame. Computed before the unclassified-frame writer
+    // below because that row is where a user first meets this: the sidebar is
+    // exactly the reason the frame could not be classified, and a "detection
+    // failed" row that does not say so sends the reader to the raw pane to work it
+    // out again.
+    const paneObstruction = cliToolId === 'opencode' ? (0, opencode_pane_obstruction_1.detectOpenCodePaneObstruction)(realtimeSnippet) : null;
     // Issue #1708: a frame nothing could classify left no trace anywhere. Both
     // prompt-history writers (response-checker's pending row and
     // recordAnsweredPrompt) are gated on `promptDetection.isPrompt === true`, so
@@ -667,6 +820,9 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
             dwellMs: unclassifiedVerdict.dwellMs,
             sessionStatus: merged.status,
             sessionStatusReason: merged.reason,
+            // Issue #2095: the cause, when the frame carries one. Null leaves the row
+            // exactly as #1708 wrote it.
+            obstruction: paneObstruction,
         });
     }
     // Issue #1725: the structured layer saw a dialog the scraper did not. That
@@ -685,7 +841,6 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     // rather than inside a status branch — the bar it feeds must appear on the
     // strength of what is in the box, never on the strength of a status verdict.
     const composer = (0, composer_text_1.extractComposerText)(output, cliToolId);
-    const realtimeSnippet = lines.slice(-100).join('\n');
     // Issue #1839: judged on exactly what is published as `realtimeSnippet`, not
     // on `output`. The wider capture keeps a banner from an hour ago in scope, and
     // a fault the operator cannot see in the payload next to it is unverifiable.
@@ -770,6 +925,18 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
                 at: Date.now(),
             }
             : null,
+        // Issue #2095: the same three keys as `upstreamFault`, read from the same
+        // rows, so an operator comparing the two is comparing like with like. The
+        // detector's `boxRight` / `rows` stay off the wire — they are how the rule
+        // decided, not what a caller acts on, and the payload is already a published
+        // contract wide enough to be hard to change.
+        paneObstruction: paneObstruction
+            ? {
+                id: paneObstruction.id,
+                matchedText: paneObstruction.matchedText,
+                at: Date.now(),
+            }
+            : null,
         // Issue #1879: read from `output` — the RAW capture, still carrying the SGR
         // attributes `capture-pane -e` fetched. Everything else in this function
         // works on stripped text; this one deliberately does not, because dim is the

package/dist/server/src/lib/session/opencode-session-api.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * The session-level calls CommandMate makes to one opencode instance's own
+ * server (Issue #2038).
+ *
+ * `../hooks/sources/opencode/client` holds the calls the *event pipeline*
+ * makes — health, pending approvals, the SSE stream. These are the calls the
+ * *operator* makes: read one session back, open the TUI's session picker, start
+ * a new session, fork the current one. They live here rather than there because
+ * #2038 is not allowed to change that module (two other Issues are editing it
+ * in parallel), and because the two sets have different callers: nothing in the
+ * ingest path needs a fork button.
+ *
+ * The transport rules are imported rather than re-decided —
+ * `OPENCODE_FETCH_REDIRECT`, `OPENCODE_REQUEST_TIMEOUT_MS`,
+ * `OPENCODE_JSON_CONTENT_TYPE`, `opencodeBaseUrl` are the same constants the
+ * event client uses — so a change to "how CommandMate talks to opencode" still
+ * has one home. What is duplicated is the six-line wrapper around them, because
+ * that wrapper is not exported.
+ *
+ * ## Measured against opencode 1.18.22 (headless `opencode serve`, isolated HOME)
+ *
+ * - `GET /session/<id>` → 200 with `{ id, directory, title, time, … }`;
+ *   `parentID` is present **only** on a sub-agent's session. 404
+ *   `{"name":"NotFoundError"}` for an id that does not exist.
+ * - `POST /session/<id>/fork` → 200 with a whole new `Session`, titled
+ *   `"<original> (fork #1)"`. The fork carries **no `parentID`** — it is a
+ *   sibling, not a child, which is why forking does not make the resumed
+ *   session look like a sub-agent to `./opencode-session-recall`.
+ * - `POST /tui/open-sessions` and `POST /tui/execute-command` → `true` / 200
+ *   **even with no TUI attached at all**. The body means "the command was
+ *   accepted onto the TUI control channel", never "the dialog is on screen", so
+ *   callers must not report success to a human as though the picker opened.
+ * - `GET /session` (no query) returned sessions belonging to *other
+ *   directories* — a server started in directory A listed directory B's
+ *   sessions, both `projectID: "global"`. That is #1758 §5.6.3 re-measured, and
+ *   it is why there is no "list this instance's sessions" call in this module:
+ *   the answer would be the whole HOME. The TUI's own picker
+ *   ({@link openOpencodeSessionPicker}) is the session list opencode is willing
+ *   to scope for itself.
+ *
+ * Every function answers null / false instead of throwing. A pane whose server
+ * has gone is the ordinary case, and none of these calls is load-bearing for a
+ * session that is already running.
+ *
+ * @module lib/session/opencode-session-api
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_TUI_NEW_SESSION_COMMAND = void 0;
+exports.toOpencodeSessionInfo = toOpencodeSessionInfo;
+exports.fetchOpencodeSession = fetchOpencodeSession;
+exports.forkOpencodeSession = forkOpencodeSession;
+exports.openOpencodeSessionPicker = openOpencodeSessionPicker;
+exports.executeOpencodeTuiCommand = executeOpencodeTuiCommand;
+exports.selectOpencodeSession = selectOpencodeSession;
+const logger_1 = require("../../lib/logger");
+const client_1 = require("../../lib/hooks/sources/opencode/client");
+const opencode_session_store_1 = require("./opencode-session-store");
+const logger = (0, logger_1.createLogger)('lib/session/opencode-session-api');
+/**
+ * The TUI command that starts a fresh session (Issue #2038).
+ *
+ * `/tui/execute-command` takes opencode's own command id rather than the
+ * slash-command text, and this is the id behind the TUI's "New session". The
+ * Issue named `/new` as the alternative; typing a slash command into the
+ * composer is not available here — CommandMate would have to send keystrokes
+ * into the pane and read them back, which is exactly the scraping this endpoint
+ * replaces.
+ */
+exports.OPENCODE_TUI_NEW_SESSION_COMMAND = 'session_new';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/** Whether a response says it is the media type this call can read. */
+function hasJsonContentType(response) {
+    const header = response.headers?.get?.('content-type');
+    if (typeof header !== 'string')
+        return false;
+    return header.split(';', 1)[0]?.trim().toLowerCase() === client_1.OPENCODE_JSON_CONTENT_TYPE;
+}
+/**
+ * One JSON request to the instance's own server, answering null on any failure.
+ *
+ * Mirrors `client.ts`'s unexported `requestJson`, including the two guards that
+ * are not obvious: redirects are refused (a 3xx lands here rather than at its
+ * target) and a 200 whose body is not JSON is discarded — an unknown route on a
+ * real opencode server answers `200 text/html` with the web UI's SPA shell,
+ * so "the request succeeded" is not the same question as "opencode answered".
+ */
+async function requestJson(url, init) {
+    try {
+        const response = await fetch(url, {
+            ...init,
+            redirect: client_1.OPENCODE_FETCH_REDIRECT,
+            signal: AbortSignal.timeout(client_1.OPENCODE_REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        if (!hasJsonContentType(response)) {
+            logger.debug('opencode-session-request-content-type', {
+                url,
+                contentType: response.headers?.get?.('content-type') ?? null,
+            });
+            return null;
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        // Includes the ordinary case: nothing is listening because the pane exited.
+        logger.debug('opencode-session-request-failed', {
+            url,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/** Parse a `Session` body, or null when it is not one. */
+function toOpencodeSessionInfo(body) {
+    if (!isPlainObject(body))
+        return null;
+    const id = readString(body, 'id');
+    if (!(0, opencode_session_store_1.isOpencodeSessionId)(id))
+        return null;
+    const title = readString(body, 'title');
+    return {
+        id,
+        title: title === null ? null : title.slice(0, opencode_session_store_1.MAX_OPENCODE_SESSION_TITLE_LENGTH),
+        directory: readString(body, 'directory'),
+        parentId: readString(body, 'parentID'),
+    };
+}
+/**
+ * Read one session back from the instance's server.
+ *
+ * The single-session read, never `GET /session`: the list is HOME-wide (see the
+ * module comment), the read is by id.
+ *
+ * @param port - The port this instance's TUI was launched on
+ * @param sessionId - The session to describe
+ * @returns The session, or null when it is gone / the server is gone
+ */
+async function fetchOpencodeSession(port, sessionId) {
+    if (!(0, opencode_session_store_1.isOpencodeSessionId)(sessionId))
+        return null;
+    const body = await requestJson(`${(0, client_1.opencodeBaseUrl)(port)}/session/${encodeURIComponent(sessionId)}`);
+    return toOpencodeSessionInfo(body);
+}
+/**
+ * Branch a session, leaving the original untouched.
+ *
+ * @param port - The port this instance's TUI was launched on
+ * @param sessionId - The session to fork
+ * @returns The new session, or null when the fork did not happen
+ */
+async function forkOpencodeSession(port, sessionId) {
+    if (!(0, opencode_session_store_1.isOpencodeSessionId)(sessionId))
+        return null;
+    const body = await requestJson(`${(0, client_1.opencodeBaseUrl)(port)}/session/${encodeURIComponent(sessionId)}/fork`, {
+        method: 'POST',
+        headers: { 'content-type': client_1.OPENCODE_JSON_CONTENT_TYPE },
+        body: '{}',
+    });
+    return toOpencodeSessionInfo(body);
+}
+/**
+ * Ask the TUI to open its session picker.
+ *
+ * Returns whether the command was *accepted*. It is not evidence the dialog is
+ * up — measured, a headless server with no TUI at all answers `true` — and the
+ * caller is expected to say so to the operator rather than claim the list
+ * opened.
+ */
+async function openOpencodeSessionPicker(port) {
+    const body = await requestJson(`${(0, client_1.opencodeBaseUrl)(port)}/tui/open-sessions`, {
+        method: 'POST',
+        headers: { 'content-type': client_1.OPENCODE_JSON_CONTENT_TYPE },
+        body: '{}',
+    });
+    return body === true;
+}
+/**
+ * Run one of the TUI's own commands.
+ *
+ * Same "accepted, not performed" caveat as {@link openOpencodeSessionPicker}.
+ */
+async function executeOpencodeTuiCommand(port, command) {
+    const body = await requestJson(`${(0, client_1.opencodeBaseUrl)(port)}/tui/execute-command`, {
+        method: 'POST',
+        headers: { 'content-type': client_1.OPENCODE_JSON_CONTENT_TYPE },
+        body: JSON.stringify({ command }),
+    });
+    return body === true;
+}
+/**
+ * Navigate the TUI to a session it is not currently showing.
+ *
+ * Sent after a fork, because forking alone leaves the pane on the original
+ * conversation — the operator pressed "fork" and would otherwise see nothing
+ * happen. Same "accepted, not performed" caveat as the two above.
+ */
+async function selectOpencodeSession(port, sessionId) {
+    if (!(0, opencode_session_store_1.isOpencodeSessionId)(sessionId))
+        return false;
+    const body = await requestJson(`${(0, client_1.opencodeBaseUrl)(port)}/tui/select-session`, {
+        method: 'POST',
+        headers: { 'content-type': client_1.OPENCODE_JSON_CONTENT_TYPE },
+        body: JSON.stringify({ sessionID: sessionId }),
+    });
+    return body === true;
+}