@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/qoderAdapter/backgroundTerminal.js

@@ -0,0 +1,262 @@
+/** 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.
+ */
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { BackgroundProcess } from './backgroundProcess.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))
+        return;
+    // Certified ~/.qoder/projects layout. Even a colliding directory name cannot cross session/cwd
+    // 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 {
+    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)
+            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.
+        }
+    }
+    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; });
+        }
+        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() {
+        // 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 {
+            const stat = await file.stat();
+            if (!stat.isFile() || this.closed)
+                return;
+            const identity = `${stat.dev}:${stat.ino}`;
+            if (identity !== this.fileIdentity || stat.size < this.offset) {
+                this.offset = 0;
+                this.pendingLine = Buffer.alloc(0);
+                this.skipLine = false;
+                this.fileIdentity = identity;
+            }
+            const end = Math.min(stat.size, this.offset + MAX_POLL);
+            const chunk = Buffer.alloc(CHUNK);
+            while (!this.closed && this.offset < end) {
+                const { bytesRead } = await file.read(chunk, 0, Math.min(CHUNK, end - this.offset), this.offset);
+                if (!bytesRead)
+                    break;
+                this.offset += bytesRead;
+                this.lines(chunk.subarray(0, bytesRead));
+            }
+            if (this.offset >= stat.size)
+                this.restoring = false;
+            if (!this.closed) {
+                await this.pollProcesses();
+                if (!this.closed)
+                    this.publish();
+            }
+        }
+        finally {
+            await file.close();
+        }
+    }
+    lines(chunk) {
+        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');
+                try {
+                    this.consume(object(JSON.parse(line)));
+                }
+                catch { /* partial/corrupt non-evidence */ }
+            }
+            this.pendingLine = Buffer.alloc(0);
+            this.skipLine = false;
+            start = end + 1;
+        }
+        const tail = chunk.subarray(start);
+        if (!this.skipLine && this.pendingLine.length + tail.length <= MAX_LINE) {
+            this.pendingLine = Buffer.concat([this.pendingLine, tail]);
+        }
+        else {
+            this.pendingLine = Buffer.alloc(0);
+            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] });
+            }
+        }
+    }
+    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() {
+        for (const [id, agentId] of this.launches) {
+            const call = this.calls.get(id);
+            if (this.closed || this.delivered.has(id) || !call?.process || call.nativeTerminal)
+                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); },
+                });
+                this.processes.set(id, process);
+            }
+            try {
+                if (await process.poll())
+                    this.pendingProcesses.delete(id);
+                else
+                    this.pendingProcesses.add(id);
+            }
+            catch {
+                this.pendingProcesses.delete(id); /* missing/corrupt transcript is not execution evidence */
+            }
+        }
+    }
+}

package/dist/workstation/qoderAdapter/completedContinuation.js

@@ -0,0 +1,139 @@
+import { capabilitiesFor, QODER_CERTIFICATIONS } from './profile.js';
+const MAX_ID_BYTES = 256;
+const MAX_MESSAGE_BYTES = 131072;
+const MAX_RECORDS = 4096;
+const states = new Set(['pending', 'paused', 'running', 'completed', 'stopped', 'failed', 'unknown']);
+const id = (value) => typeof value === 'string' && value.trim().length > 0 &&
+    Buffer.byteLength(value, 'utf8') <= MAX_ID_BYTES && !/[\x00-\x1f\x7f]/.test(value);
+const message = (value) => typeof value === 'string' &&
+    Buffer.byteLength(value, 'utf8') <= MAX_MESSAGE_BYTES;
+function exactIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const input = value;
+    return ['rootSessionId', 'runtimeGeneration', 'sourceTaskId', 'agentId', 'requestId', 'toolUseId']
+        .every((key) => id(input[key]));
+}
+function hasVendorResumeClaim(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    if (Object.prototype.hasOwnProperty.call(value, 'resumedAgentId'))
+        return true;
+    return Object.values(value).some((entry) => hasVendorResumeClaim(entry));
+}
+export function normalizeContinuationEvidence(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || hasVendorResumeClaim(value))
+        return undefined;
+    const input = value;
+    if (!exactIdentity(input.request) || !exactIdentity(input.sendMessage))
+        return undefined;
+    if (typeof input.sendMessage.success !== 'boolean')
+        return undefined;
+    const joined = input.joinedTask;
+    if (joined === undefined)
+        return {
+            request: { ...input.request },
+            sendMessage: { ...input.sendMessage,
+                success: input.sendMessage.success },
+        };
+    if (!joined || typeof joined !== 'object' || Array.isArray(joined))
+        return undefined;
+    const task = joined;
+    const joinedTask = task;
+    if (!exactIdentity(task) || !id(joinedTask.taskId) || joinedTask.taskId === joinedTask.sourceTaskId ||
+        !states.has(joinedTask.state) || !['pending', 'running', 'completed'].includes(joinedTask.state) ||
+        typeof joinedTask.live !== 'boolean' || typeof joinedTask.stale !== 'boolean')
+        return undefined;
+    return {
+        request: { ...input.request },
+        sendMessage: { ...input.sendMessage,
+            success: input.sendMessage.success },
+        joinedTask: { ...joinedTask },
+    };
+}
+function sameIdentity(a, b) {
+    return a.rootSessionId === b.rootSessionId && a.runtimeGeneration === b.runtimeGeneration &&
+        a.sourceTaskId === b.sourceTaskId && a.agentId === b.agentId && a.requestId === b.requestId &&
+        a.toolUseId === b.toolUseId;
+}
+/** Confirm only an observed, exact new execution. Natural-language claims are intentionally ignored. */
+export function confirmContinuation(expectedAgentId, value) {
+    if (!id(expectedAgentId))
+        return 'rejected';
+    const evidence = normalizeContinuationEvidence(value);
+    if (!evidence || !evidence.joinedTask || !evidence.sendMessage.success ||
+        evidence.request.agentId !== expectedAgentId || !sameIdentity(evidence.request, evidence.sendMessage) ||
+        !sameIdentity(evidence.request, evidence.joinedTask) || evidence.joinedTask.agentId !== expectedAgentId ||
+        evidence.joinedTask.stale || !evidence.joinedTask.taskId ||
+        evidence.joinedTask.taskId === evidence.request.sourceTaskId)
+        return 'rejected';
+    return 'confirmed';
+}
+function key(identity) {
+    return [identity.rootSessionId, identity.runtimeGeneration, identity.requestId].join('\u0000');
+}
+/** A bounded, request-scoped ledger prevents duplicate confirmations and keeps late proof unknown. */
+export class ContinuationLedger {
+    requests = new Map();
+    statuses = new Map();
+    joinedTaskIds = new Set();
+    evidence = new Map();
+    request(identity) {
+        if (!exactIdentity(identity) || this.requests.size >= MAX_RECORDS)
+            return 'rejected';
+        const requestKey = key(identity);
+        if (this.requests.has(requestKey))
+            return 'rejected';
+        this.requests.set(requestKey, { ...identity });
+        this.statuses.set(requestKey, 'requested');
+        return 'requested';
+    }
+    confirm(expectedAgentId, value) {
+        const evidence = normalizeContinuationEvidence(value);
+        if (!evidence)
+            return 'rejected';
+        const requestKey = key(evidence.request);
+        const original = this.requests.get(requestKey);
+        if (!original || !sameIdentity(original, evidence.request))
+            return 'unknown';
+        if (!evidence.joinedTask)
+            return 'unknown';
+        if (this.statuses.get(requestKey) === 'confirmed' || this.joinedTaskIds.has(evidence.joinedTask.taskId)) {
+            return 'rejected';
+        }
+        const result = confirmContinuation(expectedAgentId, evidence);
+        if (result === 'confirmed') {
+            this.joinedTaskIds.add(evidence.joinedTask.taskId);
+            this.statuses.set(requestKey, 'confirmed');
+            this.evidence.set(requestKey, evidence);
+        }
+        else
+            this.statuses.set(requestKey, 'rejected');
+        return result;
+    }
+    snapshot() {
+        return [...this.evidence.values()].map((entry) => ({
+            request: { ...entry.request }, sendMessage: { ...entry.sendMessage },
+            ...(entry.joinedTask ? { joinedTask: { ...entry.joinedTask } } : {}),
+        }));
+    }
+}
+export async function requestCompletedContinuation(rootSessionId, agentId, text, requestId, options) {
+    const rejected = () => ({ status: 'rejected', rootSessionId, agentId, requestId });
+    if (!options)
+        return rejected();
+    const profile = options.profile, task = options.task;
+    if (!id(rootSessionId) || !id(agentId) || !id(requestId) || !message(text) || options.enabled !== true ||
+        options.busy === true || !profile || !task ||
+        task.origin.rootSessionId !== rootSessionId || task.origin.agentId !== agentId ||
+        task.origin.runtimeGeneration !== profile.runtimeGeneration ||
+        !capabilitiesFor(profile, task, options.certifications ?? QODER_CERTIFICATIONS, options.binding).continueCompleted)
+        return rejected();
+    try {
+        await options.prompt(text);
+        return { status: 'requested', rootSessionId, agentId, requestId };
+    }
+    catch {
+        return rejected();
+    }
+}

package/dist/workstation/qoderAdapter/contract.js

@@ -0,0 +1,78 @@
+import { spawn } from 'node:child_process';
+import { parseQoderProfile } from './profile.js';
+/**
+ * Native SDK/Hooks capabilities are opt-in until one real process has produced
+ * a complete, attributable contract record.  The fake fixture must never add a
+ * profile to QODER_CERTIFICATIONS by itself.
+ */
+export const QODER_NATIVE_FALLBACKS = Object.freeze({
+    model: 'Model changes are negotiated by the base ACP session only.',
+    mode: 'Mode changes are negotiated by the base ACP session only.',
+    media: 'Prompt media and resources are unsupported by the SDK adapter.',
+    forms: 'Form elicitation is unsupported until an equivalent public SDK callback is certified.',
+    load: 'Load requires an exact native session proof; it never creates a replacement session.',
+    fork: 'Fork is unsupported until an exact new native execution can be proved.',
+});
+export function nativeFallback(feature) {
+    return { supported: false, reason: QODER_NATIVE_FALLBACKS[feature] };
+}
+/**
+ * Parses the deliberately small output contract of an opt-in native runner.
+ * This is validation only: callers still decide whether to persist evidence or
+ * open a capability, and the shipping certification allowlist remains closed.
+ */
+export function parseNativeContractEvidence(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const input = value;
+    const profile = parseQoderProfile(input.profile);
+    if (input.certified !== true || !profile || input.tasks !== true || input.hooks !== true ||
+        input.approvals !== true || input.terminalControl !== true || input.replayFree !== true ||
+        profile.cliVersion !== '1.1.64' || profile.sdkVersion !== '1.0.50' || profile.mode !== 'sdk-adapter' ||
+        profile.transport !== 'process' || profile.initialized !== true || profile.rootConfirmed !== true ||
+        profile.observerHealthy !== true || !profile.capabilities.includes('background_tasks_v1'))
+        return undefined;
+    return { certified: true, profile, tasks: true, hooks: true, approvals: true,
+        terminalControl: true, replayFree: true };
+}
+const MAX_OUTPUT_BYTES = 128 * 1024;
+const TIMEOUT_MS = 120_000;
+/**
+ * Runs an external certification command only when explicitly configured. The
+ * command is an executable path (no shell), receives no credentials from this
+ * helper, and must print NativeContractEvidence JSON to stdout.
+ */
+export async function runOptInNativeContract(command = process.env.AXOM_QODER_SDK_CONTRACT_COMMAND) {
+    if (!command)
+        return { status: 'not-run', stdout: '', stderr: '' };
+    if (command.includes('\0') || command.trim() !== command || command.length > 4096)
+        throw new Error('Invalid native contract command');
+    return await new Promise((resolve) => {
+        const child = spawn(command, [], { shell: false, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } });
+        let stdout = '', stderr = '', oversized = false, settled = false;
+        const append = (target, chunk) => {
+            if (Buffer.byteLength(target === 'stdout' ? stdout : stderr, 'utf8') + chunk.byteLength > MAX_OUTPUT_BYTES) {
+                oversized = true;
+                child.kill('SIGTERM');
+                return;
+            }
+            if (target === 'stdout')
+                stdout += chunk.toString('utf8');
+            else
+                stderr += chunk.toString('utf8');
+        };
+        child.stdout.on('data', (chunk) => append('stdout', chunk));
+        child.stderr.on('data', (chunk) => append('stderr', chunk));
+        const timer = setTimeout(() => child.kill('SIGTERM'), TIMEOUT_MS);
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        child.once('error', (error) => finish({ status: 'failed', command, stdout, stderr: `${stderr}${error.message}` }));
+        child.once('close', (code) => finish({ status: oversized ? 'failed' : code === 0 ? 'completed' : 'failed',
+            command, exitCode: code, stdout, stderr }));
+    });
+}

package/dist/workstation/qoderAdapter/foregroundOutput.js

@@ -0,0 +1,30 @@
+export function certifiedRuntime(identity) {
+    return identity?.name === 'qoder-cli' && identity.version === '1.1.61';
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export class ForegroundOutputBoundary {
+    nativeSessionId;
+    pending = new Set();
+    constructor(nativeSessionId) {
+        this.nativeSessionId = nativeSessionId;
+    }
+    accept(event) {
+        if (event.acpSessionId && event.acpSessionId !== this.nativeSessionId)
+            return true;
+        const p = event.payload, input = record(p.rawInput);
+        if (event.eventName === 'tool_call' && p.kind === 'think' && record(record(p._meta).qoder).toolName === 'Agent' &&
+            typeof p.toolCallId === 'string' && typeof input.prompt === 'string' &&
+            (input.run_in_background === undefined || input.run_in_background === false))
+            this.pending.add(p.toolCallId);
+        if (event.eventName === 'tool_call_update' && typeof p.toolCallId === 'string' &&
+            ['completed', 'failed', 'cancelled'].includes(String(p.status)))
+            this.pending.delete(p.toolCallId);
+        // Identified/draft child streams and controls keep their existing handling. Never assign an
+        // unaddressed chunk to whichever child happens to finish first.
+        return !this.pending.size || !['agent_message_chunk', 'agent_thought_chunk'].includes(event.eventName) ||
+            typeof p.messageId === 'string' || p._meta != null;
+    }
+    endTurn() { this.pending.clear(); }
+}

package/dist/workstation/qoderAdapter/history.js

@@ -0,0 +1,87 @@
+import { getSubagentMessages, listSubagents } from '@qoder-ai/qoder-agent-sdk';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+const MAX_OFFSET = 100_000;
+const MAX_IDS = 4096;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+const MAX_BYTES = 8 * 1024 * 1024;
+const sdkReader = { listSubagents, getSubagentMessages };
+const safeIdentity = (value) => typeof value === 'string' &&
+    value.length > 0 && value.length <= 256 && !/[\x00-\x1f\x7f\\/]/.test(value) &&
+    /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value);
+function validDirectory(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 4096 &&
+        value.startsWith('/') && !/[\x00-\x1f\x7f]/.test(value) &&
+        !value.replaceAll('\\', '/').split('/').includes('..');
+}
+function unknownResult(rootSessionId, agentId, offset = 0, limit = DEFAULT_LIMIT, reason = 'sdk-error') {
+    return { status: 'unknown', entries: [], rootSessionId, agentId, offset, limit,
+        hasMore: false, snapshotStable: false, reason };
+}
+async function bounded(operation, timeoutMs) {
+    return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('history read timed out')), timeoutMs);
+        operation.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
+function normalizeMessage(rootSessionId, agentId, message) {
+    const kind = message.type === 'user' || message.type === 'assistant' || message.type === 'system'
+        ? message.type : 'unknown';
+    const parent = safeIdentity(message.parent_agent_id) ? message.parent_agent_id : undefined;
+    return {
+        kind, id: safeIdentity(message.uuid) ? message.uuid : 'unknown', rootSessionId, agentId,
+        source: 'qoder-sdk', readOnly: true, actions: [], message: message.message,
+        ...(typeof message.timestamp === 'string' ? { timestamp: message.timestamp } : {}),
+        ...(parent ? { parentAgentId: parent } : {}),
+        parentAgentIdStatus: parent ? 'verified' : 'unknown',
+    };
+}
+/**
+ * Reads a bounded, read-only child transcript using only Qoder's public SDK APIs.
+ * `offset` is a page offset, never a durable tail cursor. The SDK may read the full
+ * transcript before applying it; maxBytes bounds returned data, not bytes read on disk.
+ */
+export async function readChildHistory(rootSessionId, agentId, page, reader = sdkReader) {
+    const offset = page?.offset ?? 0;
+    const limit = page?.limit ?? DEFAULT_LIMIT;
+    const timeoutMs = page?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBytes = page?.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (!safeIdentity(rootSessionId) || !safeIdentity(agentId))
+        return unknownResult(rootSessionId, agentId, 0, DEFAULT_LIMIT, 'invalid-identity');
+    if (!validDirectory(page?.dir) || !Number.isSafeInteger(offset) || offset < 0 || offset > MAX_OFFSET ||
+        !Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT ||
+        !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS ||
+        !Number.isSafeInteger(maxBytes) || maxBytes < 1024 || maxBytes > MAX_BYTES)
+        return unknownResult(rootSessionId, agentId, Number.isSafeInteger(offset) && offset >= 0 ? offset : 0, Number.isSafeInteger(limit) && limit > 0 ? limit : DEFAULT_LIMIT, 'invalid-page');
+    const rosterOptions = { dir: page.dir };
+    const messageOptions = { dir: page.dir, offset, limit };
+    try {
+        const listed = await bounded(reader.listSubagents(rootSessionId, rosterOptions), timeoutMs);
+        if (!Array.isArray(listed) || listed.length > MAX_IDS ||
+            listed.some((id) => !safeIdentity(id)))
+            return unknownResult(rootSessionId, agentId, offset, limit, 'malformed-result');
+        if (!listed.includes(agentId))
+            return unknownResult(rootSessionId, agentId, offset, limit, 'child-not-listed');
+        const messages = await bounded(reader.getSubagentMessages(rootSessionId, agentId, messageOptions), timeoutMs);
+        if (!Array.isArray(messages) || messages.length > limit || messages.length > MAX_IDS)
+            return unknownResult(rootSessionId, agentId, offset, limit, 'malformed-result');
+        if (messages.some((message) => !message || typeof message !== 'object' ||
+            message.session_id !== rootSessionId || !safeIdentity(message.uuid)))
+            return unknownResult(rootSessionId, agentId, offset, limit, 'malformed-result');
+        const entries = messages.map((message) => normalizeMessage(rootSessionId, agentId, message));
+        const serialized = JSON.stringify(entries);
+        if (serialized === undefined || Buffer.byteLength(serialized, 'utf8') > maxBytes)
+            return unknownResult(rootSessionId, agentId, offset, limit, 'oversized-result');
+        // Recheck membership after the read so a changing child roster cannot be presented as stable.
+        const after = await bounded(reader.listSubagents(rootSessionId, rosterOptions), timeoutMs);
+        if (!Array.isArray(after) || !after.includes(agentId))
+            return unknownResult(rootSessionId, agentId, offset, limit, 'snapshot-changed');
+        return { status: 'verified', entries, rootSessionId, agentId, offset, limit,
+            hasMore: messages.length === limit, snapshotStable: true };
+    }
+    catch {
+        return unknownResult(rootSessionId, agentId, offset, limit, 'sdk-error');
+    }
+}