The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat(autonomous-device): keep the answer the recap throws away (#26)
Leo37e90d1cb41b
diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 1068c29ec..13892ad08 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -3849,6 +3849,7 @@ async function runForeground(session: AuthSession): Promise<void> {stop: id => cancelAgent(id, true),answer: (agentId, requestId, answers) => questions.answer({ agentId, requestId, answers, allowPermissions: false }),recent: (id, n) => mirror.recent(registry.byAgent(id)?.sessionId ?? id, n),+ fullText: id => mirror.lastFullText(registry.byAgent(id)?.sessionId ?? id),emit: frame => backend.emitAutonomousDeviceEvent(frame),})backend.setAutonomousDeviceService(autonomousDeviceService)diff --git a/cli/src/lib/autonomous-device/service.spec.ts b/cli/src/lib/autonomous-device/service.spec.tsindex 7ad53faba..b6c983435 100644--- a/cli/src/lib/autonomous-device/service.spec.ts+++ b/cli/src/lib/autonomous-device/service.spec.ts@@ -2,11 +2,11 @@ import { describe, expect, it, vi } from 'vitest'import { randomUUID } from 'node:crypto'import { AutonomousDeviceService, type AutonomousDeviceFrame } from './service.js'-function fixture(now?: () => number) {+function fixture(now?: () => number, fullAnswer?: string) {const submit = vi.fn(), stop = vi.fn(async () => true), answer = vi.fn(async () => true)const events: AutonomousDeviceFrame[] = []const service = new AutonomousDeviceService({ now, machineId: 'machine', agents: () => [{ agentId: 'agent', name: 'Project', engine: 'claude', state: 'idle' }],- submit, stop, answer, cancelDelivery: vi.fn(() => true), recent: () => [], emit: f => events.push(f) })+ submit, stop, answer, cancelDelivery: vi.fn(() => true), recent: () => [], fullText: () => fullAnswer, emit: f => events.push(f) })const send = (fields: Record<string, unknown> = {}) => ({ type: 'turn.send', requestId: randomUUID(), machineId: 'machine', agentId: 'agent', text: 'hello', idempotencyKey: 'intent1', ...fields })return { service, submit, stop, answer, events, send }}@@ -109,3 +109,26 @@ describe('Autonomous device receipt result contract and bounded cache', () => {expect(f.submit).toHaveBeenCalledTimes(512)})})++describe('Autonomous device turn.summary carries the complete answer', () => {+ const card = { type: 'commander_event', agentId: 'agent', payload: { kind: 'summary', text: 'clipped preview…', recap: 'Five US events' } }++ it('adds fullText to the summary event without touching the card the dial reads', () => {+ const f = fixture(undefined, 'Full answer listing all five events.')+ f.service.commander(card)+ const summary = f.events.find(e => e.kind === 'turn.summary')!+ const payload = summary.payload as Record<string, unknown>+ expect(payload.fullText).toBe('Full answer listing all five events.')+ // The originals travel unchanged — Desktop and the dial read these two and nothing else.+ expect(payload.text).toBe('clipped preview…')+ expect(payload.recap).toBe('Five US events')+ // The incoming card was NOT widened; only the event this service emits carries the new field.+ expect(card.payload).not.toHaveProperty('fullText')+ })++ it('omits the field entirely when no answer was recorded', () => {+ const f = fixture(undefined, undefined)+ f.service.commander(card)+ expect(f.events.find(e => e.kind === 'turn.summary')!.payload).not.toHaveProperty('fullText')+ })+})diff --git a/cli/src/lib/autonomous-device/service.ts b/cli/src/lib/autonomous-device/service.tsindex 3329ded97..9ced63888 100644--- a/cli/src/lib/autonomous-device/service.ts+++ b/cli/src/lib/autonomous-device/service.ts@@ -17,6 +17,15 @@ export interface AutonomousDeviceServiceOptions {stop: (agentId: string) => Promise<boolean>answer: (agentId: string, questionRequestId: string, answers: Record<string, string>) => Promise<boolean>recent: (agentId: string, n: number) => unknown[]+ /**+ * The newest turn's COMPLETE final answer for an agent, or undefined.+ *+ * Read here rather than taken off the `commander_event` payload on purpose. That frame is broadcast to+ * every device on the account, and the USB dial's own encoder throws above an 8 KiB payload+ * (cable/cableFrame.ts) — widening the shared card to serve one consumer would put a limit nobody+ * looks at between the dial and its turn cards.+ */+ fullText?: (agentId: string) => string | undefinedemit?: (frame: AutonomousDeviceFrame) => void}interface Entry { deviceId: string; digest: string; receipt: AutonomousDeviceReceipt }@@ -142,7 +151,8 @@ export class AutonomousDeviceService {if (this.questions.get(agentId)?.requestId === p.requestId) this.questions.delete(agentId)this.event('question.close', agentId, { questionRequestId: p.requestId })} else if (frame.type === 'commander_event' && agentId && ['summary', 'tool', 'error'].includes(String(p.kind))) {- this.event(p.kind === 'summary' ? 'turn.summary' : p.kind === 'tool' ? 'turn.tool' : 'agent.error', agentId, p)+ const full = p.kind === 'summary' ? this.options.fullText?.(agentId) : undefined+ this.event(p.kind === 'summary' ? 'turn.summary' : p.kind === 'tool' ? 'turn.tool' : 'agent.error', agentId, full ? { ...p, fullText: full } : p)}}async request(deviceId: string, req: Record<string, unknown>): Promise<AutonomousDeviceFrame> {diff --git a/cli/src/lib/commander.spec.ts b/cli/src/lib/commander.spec.tsindex fdacd62e5..bc38b32e2 100644--- a/cli/src/lib/commander.spec.ts+++ b/cli/src/lib/commander.spec.ts@@ -4,6 +4,7 @@ import { tmpdir } from 'os'import { join } from 'path'import { CommanderMirror, type CommanderFrame } from './commander.js'import type { LiveEvent } from './normalize.js'+import { BODY_MAX_CHARS, RECAP_MAX_CHARS, deriveTurnSummary } from './summarize.js'let dataDir = ''@@ -398,3 +399,92 @@ describe('recap lookup spans both ids', () => {expect(mirror.recent(resolve('agent-uuid'))[0].recap).toBe('Short recap')})})++describe('CommanderMirror keeps the complete final answer beside the clipped one', () => {+ // The answer that exposed this: a five-row event table whose intro line is the only part that survives+ // deriveTurnSummary. A device reading it aloud stopped dead at "official sites:" and never reached a+ // single event, because the stored body is flattened to one line and cut at 250 characters.+ const ANSWER = [+ 'Here are five notable US events coming up in September–October 2026, with dates checked against official sites:',+ '',+ '| Event | Dates | Location |',+ '| --- | --- | --- |',+ '| US Open finals weekend | Sept. 12–13 | Queens, New York |',+ '| State Fair of Texas | Sept. 25–Oct. 18 | Dallas, Texas |',+ '| Austin City Limits Music Festival | Oct. 2–4 and 9–11 | Zilker Park, Austin, Texas |',+ '| Albuquerque International Balloon Fiesta | Oct. 3–11 | Albuquerque, New Mexico |',+ '| Great American Beer Festival | Oct. 10–11 | Denver, Colorado |',+ ].join('\n')++ let dir = ''+ beforeEach(() => { vi.useFakeTimers(); dir = mkdtempSync(join(tmpdir(), 'adapter-commander-full-')) })+ afterEach(() => { vi.useRealTimers(); rmSync(dir, { recursive: true, force: true }) })++ async function runTurn(mirror: CommanderMirror, sessionId: string, text: string): Promise<void> {+ mirror.ingest([{ type: 'turn_started', payload: { userMessage: 'what is on' } }] as LiveEvent[], sessionId)+ mirror.ingest([{ type: 'text_delta', payload: { content: text } }] as LiveEvent[], sessionId)+ mirror.ingest([{ type: 'turn_ended', payload: {} }] as LiveEvent[], sessionId)+ await vi.runOnlyPendingTimersAsync()+ await vi.runOnlyPendingTimersAsync()+ }++ function build(dataDir: string): CommanderMirror {+ return new CommanderMirror({+ send: () => {},+ sendWeb: () => {},+ hasDevice: () => true,+ // The shipped wiring: a local derivation, no model in the loop (cli.ts sets summarizeIsLocal).+ summarize: async (text) => deriveTurnSummary(text),+ summarizeIsLocal: true,+ dataDir,+ })+ }++ it('clips text to a preview while fullText keeps every event', async () => {+ const mirror = build(dir)+ await runTurn(mirror, 'session-full', ANSWER)++ const [turn] = mirror.recent('session-full', 1) as Array<{ text: string; recap?: string; fullText?: string }>+ expect(turn).toBeTruthy()++ // What ships today, unchanged: one line, cut at the documented cap.+ expect(turn.text.length).toBeLessThanOrEqual(BODY_MAX_CHARS)+ expect(turn.text).not.toContain('Great American Beer Festival')+ expect(turn.recap!.length).toBeLessThanOrEqual(RECAP_MAX_CHARS)++ // What the new field adds: the answer as the person would read it on screen.+ for (const event of ['US Open finals weekend', 'State Fair of Texas', 'Austin City Limits Music Festival',+ 'Albuquerque International Balloon Fiesta', 'Great American Beer Festival']) {+ expect(turn.fullText).toContain(event)+ }+ // Structure survives too — the table is still a table, not one flattened run.+ expect(turn.fullText).toContain('\n')+ expect(mirror.lastFullText('session-full')).toBe(turn.fullText)+ })++ it('pairs each turn with its own answer, and survives a restart', async () => {+ const mirror = build(dir)+ await runTurn(mirror, 'session-two', 'First answer about the balloon fiesta.')+ await runTurn(mirror, 'session-two', ANSWER)++ const reloaded = build(dir)+ const turns = reloaded.recent('session-two', 3) as Array<{ text: string; fullText?: string }>+ expect(turns).toHaveLength(2)+ // Newest first, and each row carries ITS OWN answer — the alignment bug this ordering invites.+ expect(turns[0].fullText).toContain('Great American Beer Festival')+ expect(turns[1].fullText).toBe('First answer about the balloon fiesta.')+ })++ it('truncates an oversized answer on a character boundary, not a byte one', async () => {+ const mirror = build(dir)+ // Every character is 3 bytes of UTF-8, so a byte-counted cut lands mid-sequence unless it is guarded.+ await runTurn(mirror, 'session-big', 'Sự '.repeat(6000))++ const full = mirror.lastFullText('session-big')!+ expect(Buffer.byteLength(full, 'utf8')).toBeLessThanOrEqual(8192)+ expect(full.endsWith('…')).toBe(true)+ expect(full).not.toContain('�')+ // A round trip through UTF-8 is lossless only if nothing was severed.+ expect(Buffer.from(full, 'utf8').toString('utf8')).toBe(full)+ })+})diff --git a/cli/src/lib/commander.ts b/cli/src/lib/commander.tsindex 806310115..d7adf9b24 100644--- a/cli/src/lib/commander.ts+++ b/cli/src/lib/commander.ts@@ -197,6 +197,31 @@ function splitSummary(summary: string): { recap: string; body: string } {* agent's subject from another's, few enough that one chatty agent cannot crowd the others out. */const RECENT_TURNS = 3+/**+ * The cap on ONE stored final answer, in bytes of UTF-8.+ *+ * Not a taste judgement — it is arithmetic against the narrowest transport that carries this. The+ * Autonomous device link opens its socket with `maxPayload: 65536` (lib/autonomous-device/direct.ts),+ * a `recap` may ask for five turns at once, and every payload is sealed and base64'd on the way out+ * (wrapPayload → roughly +37%). Five of these is 40 KiB, which lands near 55 KiB on the wire and still+ * fits. Raising it without redoing that multiplication is how frames start disappearing with no error+ * anywhere: an oversized one is dropped by the socket, not rejected by anything that logs.+ */+const FULL_TEXT_MAX_BYTES = 8192++/**+ * Truncate to a byte budget without splitting a character.+ *+ * `slice()` counts UTF-16 units, so cutting Vietnamese or emoji by a byte figure lands mid-sequence and+ * ships a broken string. Decoding the truncated buffer non-fatally turns whatever was severed into+ * U+FFFD, which is then dropped along with a trailing lone surrogate.+ */+function clipBytes(text: string, max: number): string {+ if (Buffer.byteLength(text, 'utf8') <= max) return text+ const decoded = new TextDecoder('utf-8').decode(Buffer.from(text, 'utf8').subarray(0, max - 3))+ return `${decoded.replace(/\uFFFD+$/, '').replace(/[\uD800-\uDBFF]$/, '')}\u2026`+}+export class CommanderMirror {private states = new Map<string, SessionState>()private summaries = new Map<string, string>() // sessionId → "recap\n\nbody" (the LATEST turn)@@ -210,13 +235,27 @@ export class CommanderMirror {* history lives beside it where an older reader simply never looks.*/private history = new Map<string, string[]>()+ /**+ * The same turns' COMPLETE final answers, newest first and index-aligned with `history`.+ *+ * A third file for the reason the second one exists (see above): the two beside it keep their exact+ * shape, so a rollback reads them unchanged and simply never looks here.+ *+ * It is kept at all because `history` cannot answer for it. What is stored there has already been+ * flattened to one line and clipped to 250 characters by deriveTurnSummary — enough for a dial that+ * is cabled to the screen already showing the answer, and not enough for anything reading the answer+ * aloud in another room.+ */+ private fullTexts = new Map<string, string[]>()private file: stringprivate historyFile: string+ private fullTextFile: stringprivate saveTimer: NodeJS.Timeout | null = nullconstructor(private opts: CommanderMirrorOpts) {this.file = join(opts.dataDir, 'summaries.json')this.historyFile = join(opts.dataDir, 'summaries-history.json')+ this.fullTextFile = join(opts.dataDir, 'summaries-fulltext.json')this.load()}@@ -552,6 +591,9 @@ export class CommanderMirror {if (summary) {this.summaries.set(sessionId, summary)this.remember(sessionId, summary)+ // Recorded in the SAME branch as the summary, so the two arrays cannot drift out of step —+ // a turn that produced no summary produces no row in either.+ this.rememberFullText(sessionId, text)this.saveSoon()const { recap, body } = splitSummary(summary)this.trace(sessionId, `${sid} done in ${ms}ms · recap="${recap}" · bodyLen=${body.length}`)@@ -624,27 +666,44 @@ export class CommanderMirror {* Falls back to the single latest summary when the history is empty, so the recaps already on disk from* before this existed are usable on the first run rather than after three more turns.*/- recent(sessionId: string, n = 2): Array<{ kind: string; text: string; recap?: string }> {+ recent(sessionId: string, n = 2): Array<{ kind: string; text: string; recap?: string; fullText?: string }> {const want = Math.max(1, n)const stored = this.history.get(sessionId) ?? []const latest = this.summaries.get(sessionId)// The latest lives in both places once a turn has run under this build; dedupe so it is not read twice.- const all = stored.length ? stored : latest ? [latest] : []+ const usingHistory = stored.length > 0+ const all = usingHistory ? stored : latest ? [latest] : []+ const fulls = this.fullTexts.get(sessionId) ?? []return all.slice(0, want)- .filter((summary) => summary && summary.trim())- .map((summary) => {+ // PAIRED BEFORE FILTERING, not after. The filter below drops empty summaries, and dropping them+ // from one array while reading the other by position is how a turn ends up carrying the previous+ // turn's answer — wrong in the one way nobody would think to check.+ .map((summary, at) => ({ summary, full: fulls[usingHistory ? at : 0] }))+ .filter(({ summary }) => summary && summary.trim())+ .map(({ summary, full }) => {const { recap, body } = splitSummary(summary)- return { kind: 'summary', text: body || recap, recap }+ return { kind: 'summary', text: body || recap, recap, ...(full ? { fullText: full } : {}) }})}+ /** The newest turn's complete final answer, for a consumer that reads rather than glances. */+ lastFullText(sessionId: string): string | undefined {+ return this.fullTexts.get(sessionId)?.[0]+ }+/** Keep the last few turns for this session, newest first. */private remember(sessionId: string, summary: string): void {const kept = [summary, ...(this.history.get(sessionId) ?? [])].slice(0, RECENT_TURNS)this.history.set(sessionId, kept)}+ /** The same, for the unclipped answer. Always called with `remember`, so the two stay aligned. */+ private rememberFullText(sessionId: string, text: string): void {+ const kept = [clipBytes(text.trim(), FULL_TEXT_MAX_BYTES), ...(this.fullTexts.get(sessionId) ?? [])].slice(0, RECENT_TURNS)+ this.fullTexts.set(sessionId, kept)+ }+/** Turn cancelled (web/device C-c). The claude turn is killed with no end_turn line, so no turn_ended* fires and the recap flow never closes the device's busy tile — it would spin "Working…" forever. Abort* any in-flight recap (so a killed turn can't emit a late summary + beep) and send a bare `done`, which@@ -679,6 +738,10 @@ export class CommanderMirror {// is exactly what this method exists to prevent, and the router reads the history, not the latest.const past = this.history.get(fromSessionId)if (past?.length && !this.history.get(toSessionId)?.length) this.history.set(toSessionId, past)+ // Moved with it, or the rotated session would answer `recap` with summaries whose full answers are+ // missing — index-aligned arrays where only one side survived is worse than neither surviving.+ const pastFull = this.fullTexts.get(fromSessionId)+ if (pastFull?.length && !this.fullTexts.get(toSessionId)?.length) this.fullTexts.set(toSessionId, pastFull)this.save()}@@ -708,6 +771,14 @@ export class CommanderMirror {if (Array.isArray(v)) this.history.set(k, v.filter((x): x is string => typeof x === 'string').slice(0, RECENT_TURNS))}} catch { /* no history yet — recent() falls back to the latest summary */ }+ try {+ const obj = JSON.parse(readFileSync(this.fullTextFile, 'utf-8')) as Record<string, unknown>+ for (const [k, v] of Object.entries(obj)) {+ // Re-clipped on the way in: the cap may have been lowered since this was written, and a stored+ // row is not evidence that it still fits the wire.+ if (Array.isArray(v)) this.fullTexts.set(k, v.filter((x): x is string => typeof x === 'string').slice(0, RECENT_TURNS).map(t => clipBytes(t, FULL_TEXT_MAX_BYTES)))+ }+ } catch { /* no full answers yet — recap simply omits the field */ }}private saveSoon(): void {@@ -720,6 +791,7 @@ export class CommanderMirror {mkdirSync(this.opts.dataDir, { recursive: true, mode: 0o700 })writeFileSync(this.file, JSON.stringify(Object.fromEntries(this.summaries), null, 2))writeFileSync(this.historyFile, JSON.stringify(Object.fromEntries(this.history), null, 2))+ writeFileSync(this.fullTextFile, JSON.stringify(Object.fromEntries(this.fullTexts), null, 2))} catch (err) {console.error('[commander] save summaries failed:', err)}diff --git a/docs/autonomous-device-integration.md b/docs/autonomous-device-integration.mdindex 0d7770582..3ef60a47c 100644--- a/docs/autonomous-device-integration.md+++ b/docs/autonomous-device-integration.md@@ -122,7 +122,7 @@ a duplicate may return any retained receipt state. Supported operations:|---|---|---|| `agents.list` | none | `machineId,agents:[{machineId,agentId,name,engine,state}]` || `status` | `machineId,agentId` | `machineId,agentId,state,openQuestion:null\|{requestId,questions}` |-| `recap` | `machineId,agentId,n?` (default 3, integer 1–5) | `machineId,agentId,turns:[{kind,text,recap?}]` |+| `recap` | `machineId,agentId,n?` (default 3, integer 1–5) | `machineId,agentId,turns:[{kind,text,recap?,fullText?}]` || `turn.send` | `machineId,agentId,idempotencyKey,text` | `status,receipt` || `turn.stop` | `machineId,agentId,idempotencyKey` | `status,receipt` || `question.answer` | `machineId,agentId,idempotencyKey,questionRequestId,answers` | `status,receipt` |@@ -168,7 +168,26 @@ Events are encrypted full objects:```Kinds include `receipt.updated`, `turn.started`, `turn.done`, `turn.error`, `turn.summary`,-`turn.tool`, `agent.error`, `question.open`, `question.close`. Question-open payload is+`turn.tool`, `agent.error`, `question.open`, `question.close`.++`turn.summary` payload and `recap` turn entries carry three views of one answer, and a consumer should+prefer `turns[].fullText`, then `turn.summary.fullText`, then `text`:++| Field | Limit | What it is |+|---|---|---|+| `recap` | 60 chars | the first prose sentence — a tile headline |+| `text` | 250 chars | the answer flattened to one line and clipped — a glance |+| `fullText` | 8192 bytes UTF-8 | the assistant's final message as shown on screen, markdown and line breaks intact |++`fullText` is optional and absent when no answer was recorded, so read it defensively. It holds only the+final user-facing response — never tool transcripts, hidden reasoning or terminal output — and it costs+no extra model call: it is the same text the local summarizer already receives.++The 8192-byte cap is arithmetic, not taste: the direct socket accepts 65536 bytes, `recap` may return+five turns at once, and sealed payloads grow by roughly 37% through AEAD and base64. Oversized truncation+is UTF-8 safe and marked with a trailing `…`. `text` and `recap` are unchanged byte-for-byte, and the+shared `commander_event` card is not widened — the USB dial's encoder throws above an 8 KiB frame, so the+field is added only to the events this service emits. Question-open payload is`{questionRequestId,questions}`. Status uses `openQuestion.requestId` for that same identifier.Only device-origin turns with known correlation include `idempotencyKey`/`turnId`.Ring capacity 500; cursor is `(serverInstanceId,eventId)`. Matching retained cursor replays newerdiff --git a/docs/vi/autonomous-device-integration_vi.md b/docs/vi/autonomous-device-integration_vi.mdindex 035ec3b2f..c2ba56d97 100644--- a/docs/vi/autonomous-device-integration_vi.md+++ b/docs/vi/autonomous-device-integration_vi.md@@ -41,6 +41,25 @@ crypto, không kết nối backend. Request agents.list/status/recap/turn.send/treceipt.get giữ target rõ và receipt/dedupe. Không replay mutation khi mất kết nối; unknown khôngcó nghĩa chưa gửi. Cache512/ring500 và schema đầy đủ ở [bản EN](../autonomous-device-integration.md).+`turn.summary` và mỗi phần tử `recap.turns[]` mang ba mức của cùng một câu trả lời; bên tiêu thụ nên+ưu tiên `turns[].fullText`, rồi `turn.summary.fullText`, rồi `text`:++| Trường | Giới hạn | Là gì |+|---|---|---|+| `recap` | 60 ký tự | câu văn xuôi đầu tiên — tiêu đề ô tile |+| `text` | 250 ký tự | câu trả lời bị làm phẳng một dòng rồi cắt — để liếc |+| `fullText` | 8192 byte UTF-8 | tin nhắn cuối của agent đúng như hiện trên màn hình, giữ markdown và xuống dòng |++`fullText` là tuỳ chọn, vắng mặt khi chưa ghi được câu trả lời nào, nên phải đọc phòng thủ. Nó chỉ chứa+phản hồi cuối hướng tới người dùng — không có transcript tool, suy luận ẩn hay output terminal — và+không tốn thêm lần gọi model: đó chính là văn bản mà bộ tóm tắt cục bộ vốn đã nhận.++Trần 8192 byte là phép tính chứ không phải khẩu vị: socket direct nhận 65536 byte, `recap` có thể trả+năm lượt một lần, và payload đã seal phình khoảng 37% qua AEAD và base64. Cắt vượt trần là cắt an toàn+UTF-8, kèm `…` ở cuối. `text` và `recap` giữ nguyên từng byte, và card `commander_event` dùng chung+không bị nới — encoder của dial USB ném lỗi khi frame vượt 8 KiB, nên trường này chỉ thêm vào event do+service này phát ra.+Typecheck/focused test đã đạt gồm chỉ chọn discovery, retry socket mới, chờ authenticated identityvà từ chối reconnect giả mạo. Real mDNS/direct Go OS ↔ CLI đã đạt khi backend chưa từng kết nối: discovery SRV, sai mã/retry,PAKE/session, encrypted list/send/dedupe, restart/reconnect và revoke/unpair. Status chỉ đếm direct