Skip to content

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.

feat: add alwaysGenerate option to persist recaps without a device and update env configuration

0f00684331b06d3ea55f0c7c49bb
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 2d5ab1d2c..b8a405df6 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1930,6 +1930,7 @@ async function runForeground(session: AuthSession): Promise<void> {
},
dataDir: env.ADAPTER_DATA_DIR,
recapForce: env.RECAP_FORCE,
+ alwaysGenerate: env.RECAP_WITHOUT_DEVICE,
})
// Recaps are STORED under the engine session id — that is what lets `--resume` bring the last recap
// back under a brand-new agent — but they are ASKED FOR by agent id, which is the only id the device
diff --git a/cli/src/config/env.ts b/cli/src/config/env.ts
index 011e97b7b..70345e960 100644
--- a/cli/src/config/env.ts
+++ b/cli/src/config/env.ts
@@ -331,6 +331,7 @@ const envSchema = z.object({
// what it did, not as a fragment; costs the one-shot's latency per turn. `local`: no model in the loop,
// the answer's first sentence is excerpted — instant, but every recap stands alone.
SUMMARY_MODE: z.enum(['model', 'local']).default('model'),
+ RECAP_WITHOUT_DEVICE: z.string().default('true').transform((v) => v !== 'false'),
// Model for the voice router one-shot classifier (Overview voice → pick the agent). Small/fast by default.
VOICE_ROUTE_MODEL: z.string().default('haiku'),
// Test override: run the recap even with no device connected (mirrors node isRecapForced()).
diff --git a/cli/src/lib/commander.spec.ts b/cli/src/lib/commander.spec.ts
index 21246e613..d90db1e79 100644
--- a/cli/src/lib/commander.spec.ts
+++ b/cli/src/lib/commander.spec.ts
@@ -237,6 +237,53 @@ describe('CommanderMirror recap events', () => {
expect(webFrames.map((f) => f.type)).toEqual(['turn_summary_pending', 'turn_summary'])
})
+ it('with alwaysGenerate, persists a recap headless but streams NO cards to the absent device', async () => {
+ const deviceFrames: CommanderFrame[] = []
+ let summarizeCalls = 0
+ const mirror = new CommanderMirror({
+ send: (frame) => deviceFrames.push(frame),
+ sendWeb: () => {},
+ hasDevice: () => false, // no device connected
+ alwaysGenerate: true, // ...but generate + persist anyway
+ summarize: async () => { summarizeCalls++; return 'Scanned the LAN\n\nFound .143 root-equivalent.' },
+ dataDir,
+ })
+
+ mirror.ingest([
+ { type: 'turn_started', payload: { userMessage: 'scan the network' } },
+ { type: 'text_delta', payload: { content: 'Found .143 — orangepi/orangepi, passwordless sudo.' } },
+ { type: 'turn_ended', payload: {} },
+ ] as LiveEvent[], 'session-headless')
+
+ await vi.runAllTimersAsync()
+ await Promise.resolve()
+
+ // Generated + persisted → a programmatic client (agent.recent) sees it.
+ expect(summarizeCalls).toBe(1)
+ expect(mirror.recent('session-headless', 1)[0].recap).toBe('Scanned the LAN')
+ // But emit() stays device-gated: nothing rode the wire to a device that is not there.
+ expect(deviceFrames).toHaveLength(0)
+ })
+
+ it('without alwaysGenerate and no device, generates nothing (the original gate)', async () => {
+ let summarizeCalls = 0
+ const mirror = new CommanderMirror({
+ send: () => {}, sendWeb: () => {},
+ hasDevice: () => false,
+ summarize: async () => { summarizeCalls++; return 'x\n\ny' },
+ dataDir,
+ })
+ mirror.ingest([
+ { type: 'turn_started', payload: { userMessage: 'q' } },
+ { type: 'text_delta', payload: { content: 'a' } },
+ { type: 'turn_ended', payload: {} },
+ ] as LiveEvent[], 'session-off')
+ await vi.runAllTimersAsync()
+ await Promise.resolve()
+ expect(summarizeCalls).toBe(0)
+ expect(mirror.recent('session-off', 1)).toHaveLength(0)
+ })
+
it('runs the recap once when a turn closes twice (Stop hook + watcher race)', async () => {
const deviceFrames: CommanderFrame[] = []
let summarizeCalls = 0
diff --git a/cli/src/lib/commander.ts b/cli/src/lib/commander.ts
index cd16bfa0f..f16b0f685 100644
--- a/cli/src/lib/commander.ts
+++ b/cli/src/lib/commander.ts
@@ -61,6 +61,7 @@ export interface CommanderMirrorOpts {
agentIdFor?: (sessionId: string) => string | undefined
dataDir: string
recapForce?: boolean
+ alwaysGenerate?: boolean
}
interface SessionState {
@@ -558,10 +559,19 @@ export class CommanderMirror {
const sid = sessionId.slice(0, 8)
const device = this.opts.hasDevice()
- // Device-gated: only run the (costly) LLM recap while a device is connected (mirrors the hosted runtime's
- // isDeviceConnected()). No device → no card, and the summaries map is left untouched.
- if (!device && !this.opts.recapForce) {
- // Console-only: no device means no recap flow to watch.
+ // Whether to GENERATE at all. Two independent reasons to proceed without a device:
+ // • recapForce — the test override, which ALSO un-gates emit() (streaming cards ride to a device
+ // that is not there). Kept as-is for the scripted device tests.
+ // • alwaysGenerate — persist a recap on EVERY turn so `agent.recap`/`agents.list` are populated
+ // for a programmatic client (a local-ws app), with no device ever paired. Unlike recapForce it
+ // does NOT touch emit(): the persistence below runs, `emit()` stays device-gated on its own, so
+ // nothing rides the wire to an absent device. This is the fix for the back-fill gap — a device
+ // that pairs LATER restores real tiles from what was persisted here, instead of blank ones,
+ // because replayAll() only re-emits stored recaps and never regenerates a past turn.
+ // Cost: with SUMMARY_MODE=model this is one engine one-shot per turn, per agent, forever — the very
+ // cost the device gate used to avoid. SUMMARY_MODE=local makes it free (no model, same-tick excerpt).
+ if (!device && !this.opts.recapForce && !this.opts.alwaysGenerate) {
+ // Console-only: no device and generation is off, so there is no recap flow to watch.
console.log(`[recap] ${sid} turn-end · SKIP (no device connected) · textLen=${fallbackText.length}`)
return
}