@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/qoderAdapter/backgroundTerminal.js

@@ -1,24 +1,22 @@
 /** Qoder 1.1.61 drops native background task notifications from both live ACP and session/load.
  * This read-only compatibility boundary repairs only a known root Agent tool, never a session.
  * Lifecycle/removal contract: axom-patch/cli/qoder-background-terminal.md.
+ *
+ * The impure half (Task 17c): this file reads the side files; everything the repair decides is the
+ * pure fold in `backgroundTerminalFold.ts`. {@link BackgroundSideNotes} is the daemon side of the deterministic
+ * processor: a poll returns the facts as `qoder_side` note payloads for the raw log; the processor folds them only when it
+ * reads those notes, so a replay never touches the files. (The old live path's in-process driver, `BackgroundTerminalRepair`,
+ * was deleted with that path in Task 29.)
  */
 import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { BackgroundProcess } from './backgroundProcess.js';
+import { address, MAX_TASKS, object, rootRowFacts, sideNotes, } from './backgroundTerminalFold.js';
+export { TerminalRepairFold, newTerminalRepairData, sideNotes } from './backgroundTerminalFold.js';
 const CHUNK = 64 * 1024;
 const MAX_LINE = 2 * 1024 * 1024;
 const MAX_POLL = 4 * 1024 * 1024;
-const MAX_TASKS = 512;
-const MAX_RESULT = 128 * 1024;
-const MAX_RESULTS = 4 * 1024 * 1024;
-const TERMINALS = new Set(['completed', 'failed', 'cancelled']);
-function object(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
-}
-function address(value) {
-    return typeof value === 'string' && /^[a-zA-Z0-9_-]{1,160}$/.test(value) ? value : undefined;
-}
 export function nativeTerminalHistoryPath(identity, sessionId, cwd, historyHome) {
     if (identity?.name !== 'qoder-cli' || identity.version !== '1.1.61' ||
         !address(sessionId) || !isAbsolute(cwd) || !isAbsolute(historyHome))
@@ -27,89 +25,50 @@ export function nativeTerminalHistoryPath(identity, sessionId, cwd, historyHome)
     // identity: every accepted row is checked again against the exact native session and directory.
     return join(historyHome, '.qoder', 'projects', resolve(cwd).replace(/[^a-zA-Z0-9]/g, '-'), sessionId + '.jsonl');
 }
-export class BackgroundTerminalRepair {
+/**
+ * Reads the root transcript and the background children's transcripts incrementally (≤ 4 MiB per
+ * poll and file, lines ≤ 2 MiB, `O_NOFOLLOW`, never written) and hands each derived {@link SideFact}
+ * to the sink, in transcript order: root facts, then each followed child's rows and catch-up status,
+ * then `poll_end` — only when the root read completed. Its offsets are its own (not checkpointed): a
+ * new reader starts at 0 and the fold drops what it already has.
+ */
+export class BackgroundSideReader {
     options;
-    calls = new Map();
     launches = new Map();
-    terminals = new Map();
-    delivered = new Set();
     processes = new Map();
-    pendingProcesses = new Set();
     offset = 0;
     fileIdentity = '';
     pendingLine = Buffer.alloc(0);
     skipLine = false;
     closed = false;
-    timer;
-    inFlight;
     warned = false;
-    resultBytes = 0;
     restoring;
     constructor(options) {
         this.options = options;
         this.restoring = options.restoreCalls === true;
     }
-    start() {
-        if (this.closed || this.timer)
-            return;
-        this.timer = setInterval(() => { void this.poll(); }, 1000);
-        this.timer.unref();
-    }
-    observe(event) {
-        if (this.closed || (event.acpSessionId && event.acpSessionId !== this.options.nativeSessionId) ||
-            !['tool_call', 'tool_call_update'].includes(event.eventName))
-            return;
-        const payload = event.payload;
-        const id = address(payload.toolCallId);
-        if (!id)
-            return;
-        let call = this.calls.get(id);
-        const input = object(payload.rawInput);
-        if (!call && input.run_in_background === true && typeof input.prompt === 'string' &&
-            (input.subagent_type == null || typeof input.subagent_type === 'string') && payload.kind === 'think' &&
-            object(object(payload._meta).qoder).toolName === 'Agent' && this.calls.size < MAX_TASKS) {
-            const meta = object(object(payload._meta).qoder);
-            call = { input, invocationComplete: false, nativeTerminal: false,
-                process: this.options.includeProcess === true && meta.version === 1 && meta.source === 'native-acp-patch' };
-            this.calls.set(id, call);
-        }
-        if (!call)
+    /** One poll. Never rejects: a missing, replaced or unreadable file is not evidence. */
+    async read(demand, sink) {
+        if (this.closed || (!this.restoring && !demand.active()))
             return;
-        if (payload.status === 'completed')
-            call.invocationComplete = true;
-        const output = object(payload.rawOutput);
-        if (output.kind === 'agent-result' && (TERMINALS.has(String(output.state)) || output.state === 'error')) {
-            call.nativeTerminal = true; // Upstream's structured evidence always wins.
+        try {
+            await this.readIncrement(demand, sink);
         }
-    }
-    poll() {
-        if (this.closed || (!this.restoring && ![...this.calls].some(([id, call]) => !this.delivered.has(id) && !call.nativeTerminal)))
-            return Promise.resolve();
-        if (!this.inFlight) {
-            this.inFlight = this.readIncrement().catch(error => {
-                const code = object(error).code;
-                if (!['ENOENT', 'ELOOP', 'ENOTDIR', 'EACCES'].includes(String(code)) && !this.warned) {
-                    this.warned = true;
-                    console.warn('[acp:qoder] background terminal repair unavailable; retaining native ACP state');
-                }
-            }).finally(() => { this.inFlight = undefined; });
+        catch (error) {
+            const code = object(error).code;
+            if (!['ENOENT', 'ELOOP', 'ENOTDIR', 'EACCES'].includes(String(code)) && !this.warned) {
+                this.warned = true;
+                console.warn('[acp:qoder] background terminal repair unavailable; retaining native ACP state');
+            }
         }
-        return this.inFlight;
     }
     close() {
         this.closed = true;
-        if (this.timer)
-            clearInterval(this.timer);
-        this.timer = undefined;
-        this.calls.clear();
         this.launches.clear();
-        this.terminals.clear();
-        this.delivered.clear();
         this.processes.clear();
-        this.pendingProcesses.clear();
         this.pendingLine = Buffer.alloc(0);
     }
-    async readIncrement() {
+    async readIncrement(demand, sink) {
         // O_NOFOLLOW avoids importing a transcript through a replaced symlink. File is never written.
         const file = await open(this.options.path, constants.O_RDONLY | constants.O_NOFOLLOW);
         try {
@@ -130,29 +89,32 @@ export class BackgroundTerminalRepair {
                 if (!bytesRead)
                     break;
                 this.offset += bytesRead;
-                this.lines(chunk.subarray(0, bytesRead));
+                this.lines(chunk.subarray(0, bytesRead), sink);
             }
             if (this.offset >= stat.size)
                 this.restoring = false;
             if (!this.closed) {
-                await this.pollProcesses();
+                await this.pollProcesses(demand, sink);
                 if (!this.closed)
-                    this.publish();
+                    sink({ kind: 'poll_end' });
             }
         }
         finally {
             await file.close();
         }
     }
-    lines(chunk) {
+    lines(chunk, sink) {
         let start = 0;
         for (let end = chunk.indexOf(10); end !== -1; end = chunk.indexOf(10, start)) {
             if (!this.skipLine && this.pendingLine.length + end - start <= MAX_LINE) {
                 const line = Buffer.concat([this.pendingLine, chunk.subarray(start, end)]).toString('utf8');
+                let row;
                 try {
-                    this.consume(object(JSON.parse(line)));
+                    row = object(JSON.parse(line));
                 }
                 catch { /* partial/corrupt non-evidence */ }
+                if (row)
+                    this.consume(row, sink);
             }
             this.pendingLine = Buffer.alloc(0);
             this.skipLine = false;
@@ -167,96 +129,65 @@ export class BackgroundTerminalRepair {
             this.skipLine = true;
         }
     }
-    consume(row) {
-        if (row.sessionId !== this.options.nativeSessionId || row.cwd !== this.options.cwd ||
-            row.isSidechain !== false)
-            return;
-        const content = object(row.message).content;
-        if (!Array.isArray(content))
-            return;
-        // resume deliberately sends no historical ACP openings. Recover only certified root Agent
-        // background inputs; no opening is emitted and the existing exact-ID notification rules apply.
-        if (this.options.restoreCalls && row.type === 'assistant') {
-            for (const block of content.map(object)) {
-                const input = object(block.input), id = address(block.id);
-                if (block.type === 'tool_use' && block.name === 'Agent' && id && input.run_in_background === true &&
-                    typeof input.prompt === 'string' && (input.subagent_type == null || typeof input.subagent_type === 'string') &&
-                    !this.calls.has(id) && this.calls.size < MAX_TASKS) {
-                    this.calls.set(id, { input, invocationComplete: false, nativeTerminal: false, process: false });
-                }
-            }
-            return;
-        }
-        if (row.type !== 'user')
-            return;
-        const output = object(row.toolUseResult);
-        if (output.isAsync === true && output.status === 'async_launched') {
-            const results = content.map(object).filter(c => c.type === 'tool_result');
-            const id = results.length === 1 ? address(results[0].tool_use_id) : undefined;
-            const agent = address(output.agentId);
-            if (this.options.restoreCalls && id && this.calls.has(id))
-                this.calls.get(id).invocationComplete = true;
-            if (id && agent && this.launches.size < MAX_TASKS && !this.launches.has(id))
-                this.launches.set(id, agent);
-            return;
-        }
-        if (row.isMeta !== true || object(row.origin).kind !== 'task-notification')
-            return;
-        for (const block of content.map(object)) {
-            if (block.type !== 'text' || typeof block.text !== 'string' ||
-                !block.text.startsWith('[SYSTEM NOTIFICATION - NOT USER INPUT]\n'))
-                continue;
-            // Match the authoritative envelope before result text; tags inside a result cannot change IDs.
-            const match = block.text.match(/<task-notification>\n<task-id>([a-zA-Z0-9_-]{1,160})<\/task-id>\n<tool-use-id>([a-zA-Z0-9_-]{1,160})<\/tool-use-id>\n(?:<output-file>[^\n]*<\/output-file>\n)?<status>(completed|failed|cancelled)<\/status>\n<summary>[^\n]*<\/summary>\n<result>([\s\S]*)<\/result>\n(?:<usage>[^\n]*<\/usage>\n)?<\/task-notification>\s*$/);
-            const bytes = match ? Buffer.byteLength(match[4]) : 0;
-            if (match && bytes <= MAX_RESULT && this.resultBytes + bytes <= MAX_RESULTS &&
-                this.terminals.size < MAX_TASKS && !this.terminals.has(match[2])) {
-                this.resultBytes += bytes;
-                this.terminals.set(match[2], { taskId: match[1], state: match[3], result: match[4] });
+    consume(row, sink) {
+        const { nativeSessionId, cwd } = this.options;
+        for (const fact of rootRowFacts(row, { nativeSessionId, cwd, restoreCalls: this.options.restoreCalls === true })) {
+            // The reader's own copy of the receipts (same rule as the fold's): which child transcripts exist.
+            if (fact.kind === 'launch' && fact.agentId && this.launches.size < MAX_TASKS && !this.launches.has(fact.toolUseId)) {
+                this.launches.set(fact.toolUseId, fact.agentId);
             }
+            sink(fact);
         }
     }
-    publish() {
-        for (const [id, terminal] of this.terminals) {
-            const call = this.calls.get(id), agentId = this.launches.get(id);
-            if (this.delivered.has(id) || this.pendingProcesses.has(id) || !call?.invocationComplete || call.nativeTerminal || !agentId)
-                continue;
-            this.delivered.add(id);
-            this.options.emit({ eventName: 'tool_call_update', payload: {
-                    name: 'Agent', kind: 'think', toolCallId: id, rawInput: call.input, status: 'completed',
-                    rawOutput: { kind: 'agent-result', state: terminal.state, agentId, result: terminal.result },
-                    content: [{ type: 'content', content: { type: 'text', text: terminal.result } }],
-                    _meta: { qoder: { toolName: 'Agent' }, axomNativeTerminalRepair: {
-                            patch: 'qoder-background-terminal', nativeSessionId: this.options.nativeSessionId,
-                            taskId: terminal.taskId, source: 'native-task-notification',
-                        } },
-                } });
-        }
-    }
-    async pollProcesses() {
+    async pollProcesses(demand, sink) {
         for (const [id, agentId] of this.launches) {
-            const call = this.calls.get(id);
-            if (this.closed || this.delivered.has(id) || !call?.process || call.nativeTerminal)
+            if (this.closed || !demand.wantsProcess(id))
                 continue;
             let process = this.processes.get(id);
             if (!process) {
                 process = new BackgroundProcess({
                     path: join(dirname(this.options.path), this.options.nativeSessionId, 'subagents', `agent-${agentId}.jsonl`),
                     sessionId: this.options.nativeSessionId, cwd: this.options.cwd, agentId, parentToolUseId: id,
-                    emit: event => { if (!this.closed)
-                        this.options.emit(event); },
+                    emit: () => { },
+                    onRow: (uuid, events) => { if (!this.closed)
+                        sink({ kind: 'child', toolUseId: id, uuid, events }); },
                 });
                 this.processes.set(id, process);
             }
+            let caughtUp;
             try {
-                if (await process.poll())
-                    this.pendingProcesses.delete(id);
-                else
-                    this.pendingProcesses.add(id);
+                caughtUp = await process.poll();
             }
             catch {
-                this.pendingProcesses.delete(id); /* missing/corrupt transcript is not execution evidence */
+                caughtUp = true; /* missing/corrupt transcript is not execution evidence */
             }
+            sink({ kind: 'child_status', toolUseId: id, caughtUp });
         }
     }
 }
+/**
+ * The daemon side of the processor (T19 runs it on its own timer, for a session whose processor
+ * folded a `qoder_terminal_repair` note): one {@link poll} reads what is new and returns the note
+ * payloads to append to the raw log, in order. `demand` is asked of the processor's current state
+ * (`acp/processor/sideChannel.ts` `sideDemand`); what it answered is recorded only through the facts,
+ * so the processor's fold never depends on when the daemon polled.
+ */
+export class BackgroundSideNotes {
+    reader;
+    /** Facts over `MAX_SIDE_FACT_BYTES` that could not be recorded (diagnostics). */
+    droppedFacts = 0;
+    constructor(options) {
+        this.reader = new BackgroundSideReader(options);
+    }
+    async poll(demand) {
+        const notes = [];
+        await this.reader.read(demand, (fact) => {
+            const encoded = sideNotes(fact);
+            if (encoded.length === 0)
+                this.droppedFacts += 1;
+            notes.push(...encoded);
+        });
+        return notes;
+    }
+    close() { this.reader.close(); }
+}