Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(mobile-chat): carry the resolved session id on the chat.page reply

review3ee1620a192b
diff --git a/docs/mobile-chat-view.md b/docs/mobile-chat-view.md
index 9230e0314..bc9f4854e 100644
--- a/docs/mobile-chat-view.md
+++ b/docs/mobile-chat-view.md
@@ -62,6 +62,7 @@ ChatPage {
unmatchedResults: {id, result}[]
model?: string // from the latest assistant record
effort?: string // from the latest assistant record (`effort` field)
+ sessionId?: string // the session id the host READ this page with; absent = none resolved
}
ChatStatus {
version: 1
@@ -102,7 +103,7 @@ as `hostBridge.chat` in `main/index.ts`, forwarded by both phone hosts).
| verb | params | reply | does |
|---|---|---|---|
-| `chat.page` | `{nodeId, before?, maxBytes?}` | `{page: ChatPage}` | Only for agents with a chat view — `canChat(capabilityAgentId(agent))` (claude, grok, and custom agents whose base harness is one of them); anything else is refused before any read. `readChatTranscript` with the ⌘M panel's own deps (paged ALWAYS — an absent page is the default 256 KB tail; grok unpaged) + `model`/`effort`, `version: 1`. Session id: the RENDERER's agent-status id first (what ⌘M reads — after a desktop restart a hook-fed id lives only there), then the mirror's, then the node's minted id; the fallbacks apply only when the renderer does not answer within 3 s or knows none. **Remote (SSH-project) nodes are read REMOTE-ONLY** (`remoteOnly`): over the live pty's ControlMaster, else the node's PROJECT's master (an idle tab / any node after a restart has no pty), and never from this machine's disk — a remote node with no reachable master, or a host that did not answer, is `Could not read the transcript.`, not an empty page. The cwd rides ONLY for a remote node with a known id (the host-side locate needs it); locally a known-but-dead id must not fall back to the cwd's newest transcript (another node's), and with no id at all ⇒ `found:false`. `found:false` therefore always means "looked, and there is no transcript". |
+| `chat.page` | `{nodeId, before?, maxBytes?}` | `{page: ChatPage}` | Only for agents with a chat view — `canChat(capabilityAgentId(agent))` (claude, grok, and custom agents whose base harness is one of them); anything else is refused before any read. `readChatTranscript` with the ⌘M panel's own deps (paged ALWAYS — an absent page is the default 256 KB tail; grok unpaged) + `model`/`effort`, `version: 1`. Session id: the RENDERER's agent-status id first (what ⌘M reads — after a desktop restart a hook-fed id lives only there), then the mirror's, then the node's minted id; the fallbacks apply only when the renderer does not answer within 3 s or knows none. **Remote (SSH-project) nodes are read REMOTE-ONLY** (`remoteOnly`): over the live pty's ControlMaster, else the node's PROJECT's master (an idle tab / any node after a restart has no pty), and never from this machine's disk — a remote node with no reachable master, or a host that did not answer, is `Could not read the transcript.`, not an empty page. The cwd rides ONLY for a remote node with a known id (the host-side locate needs it); locally a known-but-dead id must not fall back to the cwd's newest transcript (another node's), and with no id at all ⇒ `found:false`. `found:false` therefore always means "looked, and there is no transcript". The reply's `page.sessionId` is exactly the id that read used (absent when none was resolved); the phone should PREFER it over the mirror's `sessionId` as the page's thread identity — the mirror is polled every 4 s, so right after `/clear` or a resume it still names the old session while the page already comes from the new transcript, and merging by byte `key` across the two would splice threads. Additive field: `version` stays 1, and an older desktop simply omits it (fall back to the mirror). |
| `chat.status` | `{nodeId}` | `{status: ChatStatus}` | the renderer's agent-status entry (`state` null = unknown, `held`, hibernated/paused/dropped/sessionEnded) + `structuredAnswers` = the held ticket is in main's structured-ticket ledger (script revision ≥ 5) + the host mirror's `hostRefuses`/`refusal` + `version: 1`. |
| `chat.send` | `{nodeId, text}` | `ChatSendOutcome` = `{result, reason?}` | text capped at 64000 UTF-16 units RAW, then ESC + C0/C1 stripped (`\n`, `\t` kept; `sanitizeChatText`); refused FIRST (`reason` `working`/`dialog`) when the host's mirror says the agent is working / waiting / blocked or holds a question or approval ticket (renderer state is transient after a reload); refused `busy` while another send to the same node is still in flight (held until that send SETTLES, capped at 30 s); then the renderer runs the ⌘M composer's gate at send time (`chatSendRefusal` = `agentProcessInPane` + state ∈ {done, unknown} → its own kind as `reason`) plus "no held request" (`dialog`), then `pty.sendText`. `'sent'` only for `sendText === true`; a paste the pane refused is `refused`/`failed`. |
| `agent.answer` | `{nodeId, pendingId, answer}` | `{ok: boolean}` | `answerHeldPermission` with the node's own I/O (local fs, or the SSH project's ControlMaster — the same `heldPermissionIoFor` the desktop answer path uses): validated against the pending request file, structured-ticket gated, no `setMode auto`. The `pendingId` must belong to THIS node — one of the mirror's approval tickets for it, or the renderer's `held.pendingId` (plans / questions) — else `{ok:false}` with no I/O and no answered event. Success emits the same optimistic "answered" event. |
diff --git a/src/main/remote/host-chat.test.ts b/src/main/remote/host-chat.test.ts
index 4843a19c5..e1221089b 100644
--- a/src/main/remote/host-chat.test.ts
+++ b/src/main/remote/host-chat.test.ts
@@ -46,7 +46,7 @@ describe('host-chat page', () => {
it('resolves the node host-side, reads paged and stamps version 1 (local node: no cwd)', async () => {
const d = deps()
const page = await createHostChat(d).page('n1', { before: 10, maxBytes: 65536 })
- expect(page).toEqual({ ...RESULT, version: 1 })
+ expect(page).toEqual({ ...RESULT, version: 1, sessionId: 'sid-1' })
// A LOCAL node reads by session id only: with a cwd, a known-but-dead id would fall back to the
// newest transcript in that cwd — another node's session.
expect(d.readTranscript).toHaveBeenCalledWith(
@@ -95,8 +95,10 @@ describe('host-chat page', () => {
lookupNode: () => ({ cwd: '/srv/app', agentId: 'claude', sessionId: 'stale-minted' }),
renderer: { status: vi.fn(), send: vi.fn(), session: vi.fn(async () => ({ sessionId: 'hook-fed' })) }
})
- await createHostChat(d).page('n1', {})
+ const page = await createHostChat(d).page('n1', {})
expect(d.readTranscript).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'hook-fed' }), {})
+ // The reply names the id it actually read, so the phone keys its merge on the right thread.
+ expect(page).toMatchObject({ sessionId: 'hook-fed' })
expect(d.renderer.session).toHaveBeenCalledWith({ nodeId: 'n1' })
})
it('falls back to the host records when the renderer does not answer in time, or knows none', async () => {
@@ -105,8 +107,9 @@ describe('host-chat page', () => {
lookupNode: () => ({ agentId: 'claude', sessionId: 'mirror-id' }),
renderer: { status: vi.fn(), send: vi.fn(), session: session as never }
})
- await createHostChat(d).page('n1', {})
+ const page = await createHostChat(d).page('n1', {})
expect(d.readTranscript).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'mirror-id' }), {})
+ expect(page).toMatchObject({ sessionId: 'mirror-id' })
}
})
it('no known session id anywhere ⇒ no cwd either, so no cwd fallback onto a stranger\'s transcript', async () => {
@@ -114,11 +117,14 @@ describe('host-chat page', () => {
lookupNode: () => ({ cwd: '/srv/app', agentId: 'claude', remote: true }),
renderer: { status: vi.fn(), send: vi.fn(), session: vi.fn(async () => ({})) }
})
- await createHostChat(d).page('n1', {})
+ const page = await createHostChat(d).page('n1', {})
expect(d.readTranscript).toHaveBeenCalledWith(
{ sessionId: undefined, cwd: undefined, accountId: undefined, nodeId: 'n1', agentId: 'claude', remoteOnly: true },
{}
)
+ // No id resolved ⇒ the field is ABSENT (not undefined-valued, not ''), so the phone falls back
+ // to its own identity source instead of keying on an empty string.
+ expect(page).not.toHaveProperty('sessionId')
})
})
diff --git a/src/main/remote/host-chat.ts b/src/main/remote/host-chat.ts
index ead64b644..442fd1a1c 100644
--- a/src/main/remote/host-chat.ts
+++ b/src/main/remote/host-chat.ts
@@ -157,7 +157,10 @@ export function createHostChat(deps: HostChatDeps): HostChatOps {
const result = await deps.readTranscript(q, rawPage ?? {})
// A read that FAILED (a remote host that did not answer) is an error, never "no transcript".
if (result.unreadable) throw new Error('Could not read the transcript.')
- return { ...result, version: 1 }
+ // The id this page was READ with rides the reply, so the phone keys its byte-offset merge on
+ // the thread it came from (after `/clear` or a resume a new transcript's tail must not merge
+ // into the old one). Absent when none was resolved — never an empty string.
+ return { ...result, version: 1, ...(sessionId ? { sessionId } : {}) }
},
async status(nodeId) {
diff --git a/src/shared/mobile-chat.ts b/src/shared/mobile-chat.ts
index de10eafa9..4ab2b682e 100644
--- a/src/shared/mobile-chat.ts
+++ b/src/shared/mobile-chat.ts
@@ -8,7 +8,15 @@ import type { ChatTranscriptResult } from './types'
/** One page of a node's transcript as the phone receives it. `version` lets the phone refuse a
* newer shape honestly instead of misreading it. */
-export type ChatPage = ChatTranscriptResult & { version: 1 }
+export type ChatPage = ChatTranscriptResult & {
+ version: 1
+ /** The session id the host resolved and READ this page with (the renderer's agent-status id, else
+ * the mirror's, else the node's minted id). Absent when none was resolved. The phone keys its
+ * merge on this rather than its mirror poll: after `/clear` or a resume the mirror lags by up to
+ * one poll, and a new transcript's tail must not merge into the old thread. Additive — `version`
+ * stays 1. */
+ sessionId?: string
+}
/** Why the HOST's own record refuses a send: the agent is mid-turn, or a dialog (a permission,
* plan or question) holds the pane — whose Enter would ANSWER it. */