@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/runtime/command_panes.js

@@ -0,0 +1,398 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, open, lstat, rm, rename, chmod, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getSessionPathForCwd } from '../../session.js';
+import { writeFileAtomic } from '../../utils/atomic_write.js';
+import { withPathLock } from '../../utils/path_lock.js';
+import { buildUserSubprocessEnv } from '../../utils/subprocess_env.js';
+import { startCommandJob, readCommandJob, stopCommandJob } from './command_jobs.js';
+const namePattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const states = new Set(['suspended', 'running', 'completed', 'failed', 'unknown']);
+function alive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+function validateEnvironment(env) {
+    if (!env || Array.isArray(env) || typeof env !== 'object' || Object.keys(env).length > 64
+        || Buffer.byteLength(JSON.stringify(env)) > 65536
+        || Object.entries(env).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)
+            || /^(ZTC_|ZERG_)/.test(key) || typeof value !== 'string' || value.includes('\0')))
+        throw new Error('Environment must contain at most 64 valid application variables (64 KiB total), without ZTC_/ZERG_ control variables.');
+}
+function stateOf(receipt) {
+    if (receipt.status === 'running')
+        return 'running';
+    if (receipt.status === 'completed' && receipt.exit_code === 0)
+        return 'completed';
+    if (receipt.status === 'interrupted')
+        return 'unknown';
+    return 'failed';
+}
+/** Durable definitions and command receipts are authoritative; panes are projections. */
+export class CommandPaneManager {
+    sessionId;
+    shellOptions;
+    file;
+    sessionDirectory;
+    listeners = new Set();
+    localJobs = new Set();
+    admittedJobs = new Map();
+    timer;
+    refreshTask;
+    closed = false;
+    lastPublished;
+    constructor(sessionId, sessionCwd, shellOptions) {
+        this.sessionId = sessionId;
+        this.shellOptions = shellOptions;
+        this.file = join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'command-panes', createHash('sha256').update(sessionId).digest('hex') + '.json');
+        this.sessionDirectory = dirname(getSessionPathForCwd(sessionCwd, sessionId));
+    }
+    async read() {
+        let raw;
+        try {
+            const info = await lstat(this.file);
+            if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024)
+                throw new Error('Invalid command-pane manifest file.');
+            raw = await readFile(this.file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { version: 1, sessionId: this.sessionId, commands: [] };
+            throw error;
+        }
+        const data = JSON.parse(raw);
+        if (data.version !== 1 || data.sessionId !== this.sessionId || !Array.isArray(data.commands) || data.commands.length > 32)
+            throw new Error('Invalid command-pane manifest.');
+        const names = new Set();
+        const ids = new Set();
+        for (const c of data.commands) {
+            if (!namePattern.test(c.name) || !uuidPattern.test(c.id) || names.has(c.name) || ids.has(c.id)
+                || typeof c.command !== 'string' || !c.command.trim() || c.command.length > 16384 || c.command.includes('\0')
+                || typeof c.cwd !== 'string' || !states.has(c.state)
+                || (c.state === 'running' && !c.receipt)
+                || (c.receipt && !uuidPattern.test(c.receipt.job_id))
+                || (c.admission && (!uuidPattern.test(c.admission.id) || !Number.isSafeInteger(c.admission.ownerPid) || c.admission.ownerPid <= 0)))
+                throw new Error('Invalid pinned command.');
+            validateEnvironment(c.env);
+            names.add(c.name);
+            ids.add(c.id);
+        }
+        return data;
+    }
+    async mutate(operation) {
+        if (this.closed)
+            throw new Error('Command-pane manager has stopped.');
+        return withPathLock(this.file, async () => {
+            await mkdir(dirname(this.file), { recursive: true, mode: 0o700 });
+            const lockPath = this.file + '.lock';
+            const lock = await open(lockPath, 'wx', 0o600).catch(error => {
+                if (error.code === 'EEXIST')
+                    throw new Error('A command-pane operation owns this session. Inspect its lock before recovery.');
+                throw error;
+            });
+            const identity = await lock.stat();
+            try {
+                await lock.writeFile(JSON.stringify({ pid: process.pid, sessionId: this.sessionId }));
+                const data = await this.read();
+                const before = JSON.stringify(data);
+                const result = await operation(data);
+                const after = JSON.stringify(data);
+                if (after !== before) {
+                    await writeFileAtomic(this.file, after);
+                    await chmod(this.file, 0o600);
+                }
+                return result;
+            }
+            finally {
+                await lock.close();
+                const current = await lstat(lockPath).catch(error => { if (error.code !== 'ENOENT')
+                    throw error; return null; });
+                if (current?.ino === identity.ino && current.dev === identity.dev)
+                    await rm(lockPath);
+            }
+        });
+    }
+    find(data, name) {
+        const command = data.commands.find(c => c.name === name);
+        if (!command)
+            throw new Error('Pinned command not found in this session.');
+        return command;
+    }
+    async pin(options) {
+        if (!namePattern.test(options.name))
+            throw new Error('Command name must use 1–64 letters, numbers, underscores or hyphens.');
+        const command = options.command.trim();
+        if (!command || command.length > 16384 || command.includes('\0'))
+            throw new Error('Command must contain 1–16384 characters without NUL.');
+        const env = options.env ?? {};
+        validateEnvironment(env);
+        const cwd = await realpath(options.cwd);
+        if (!(await lstat(cwd)).isDirectory())
+            throw new Error('Command cwd must be a directory.');
+        await this.mutate(async (data) => {
+            if (data.commands.some(c => c.name === options.name))
+                throw new Error('That command name is already pinned.');
+            if (data.commands.length >= 32)
+                throw new Error('Pinned command limit (32) reached. Unpin an inactive command first.');
+            data.commands.push({ id: randomUUID(), name: options.name, command, cwd, env: { ...env }, state: 'suspended' });
+        });
+        if (!options.suspended)
+            await this.run(options.name, 'none');
+        this.watch();
+        await this.publish();
+        return (await this.list()).find(c => c.name === options.name);
+    }
+    /** expectedAttempt binds an action to the snapshot it was offered on. */
+    async run(name, expectedAttempt) {
+        await this.mutate(async (data) => {
+            const c = this.find(data, name);
+            if ((c.admission?.id ?? c.receipt?.job_id ?? 'none') !== expectedAttempt)
+                throw new Error('Command attempt changed. Refresh before rerunning.');
+            if (c.admission && !c.admission.error && alive(c.admission.ownerPid))
+                throw new Error('Command admission is unresolved in a live owner. Inspect it before rerunning.');
+            if (c.state === 'running' && (this.localJobs.has(c.receipt.job_id) || alive(c.receipt?.owner_pid)))
+                throw new Error('Command is still running. Stop it before rerunning.');
+            // Rebind cwd before launch; a missing directory never falls back to another workspace.
+            if (await realpath(c.cwd) !== c.cwd || !(await lstat(c.cwd)).isDirectory())
+                throw new Error('Command directory changed. Inspect it before running.');
+            const shell = this.shellOptions();
+            // Persist the action identity before any process can run. Lost completion
+            // acknowledgement must not restore the old action's admission authority.
+            c.admission = { id: randomUUID(), ownerPid: process.pid };
+            c.state = 'unknown';
+            delete c.receipt;
+            delete c.evidence;
+            await writeFileAtomic(this.file, JSON.stringify(data));
+            await chmod(this.file, 0o600);
+            let receipt;
+            try {
+                receipt = await startCommandJob({ sessionId: this.sessionId, command: c.command, cwd: c.cwd, maxJobs: 8,
+                    shell: { ...shell, env: { ...buildUserSubprocessEnv(shell.env), ...c.env } } });
+            }
+            catch (error) {
+                c.admission.error = error instanceof Error ? error.message : String(error);
+                c.state = 'failed';
+                await writeFileAtomic(this.file, JSON.stringify(data));
+                await chmod(this.file, 0o600);
+                throw error;
+            }
+            this.admittedJobs.set(c.admission.id, receipt.job_id);
+            c.receipt = receipt;
+            c.state = stateOf(receipt);
+            delete c.admission;
+            if (receipt.status === 'running')
+                this.localJobs.add(receipt.job_id);
+        });
+        this.watch();
+        await this.refresh();
+        return (await this.list()).find(c => c.name === name);
+    }
+    async stop(name, expectedAttempt) {
+        await this.mutate(async (data) => {
+            const c = this.find(data, name);
+            if (c.receipt?.job_id !== expectedAttempt)
+                throw new Error('Command attempt changed. Refresh before stopping.');
+            if (!this.localJobs.has(expectedAttempt))
+                throw new Error('This process does not own that command.');
+            c.receipt = await stopCommandJob(this.sessionId, expectedAttempt);
+            c.state = stateOf(c.receipt);
+            this.localJobs.delete(expectedAttempt);
+        });
+        await this.publish();
+    }
+    async unpin(name) {
+        await this.mutate(async (data) => {
+            const c = this.find(data, name);
+            if (c.state === 'running' && (this.localJobs.has(c.receipt.job_id) || alive(c.receipt?.owner_pid)))
+                throw new Error('Stop the running command before unpinning.');
+            if (c.receipt)
+                this.localJobs.delete(c.receipt.job_id);
+            data.commands = data.commands.filter(entry => entry.id !== c.id);
+        });
+        await this.publish();
+    }
+    async output(c) {
+        if (!c.receipt || !this.localJobs.has(c.receipt.job_id) && c.state === 'running')
+            return '';
+        try {
+            const receipt = await readCommandJob(this.sessionId, c.receipt.job_id);
+            const file = await open(receipt.log_path, 'r');
+            try {
+                const size = (await file.stat()).size;
+                const length = Math.min(size, 32768);
+                const buffer = Buffer.alloc(length);
+                const { bytesRead } = await file.read(buffer, 0, length, size - length);
+                let start = 0;
+                while (start < bytesRead && (buffer[start] & 0xc0) === 0x80)
+                    start++;
+                return (size > length ? '[earlier output omitted from pane; attach evidence for retained log]\n' : '') + buffer.subarray(start, bytesRead).toString('utf8');
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (error) {
+            return `[Output unavailable: ${error instanceof Error ? error.message : String(error)}]`;
+        }
+    }
+    async list() {
+        const data = await this.read();
+        return Promise.all(data.commands.map(async (c) => ({ id: c.id, name: c.name, command: c.command, cwd: c.cwd,
+            environmentKeys: Object.keys(c.env), state: c.state === 'running' && !this.localJobs.has(c.receipt.job_id) ? 'unknown' : c.state,
+            attempt: c.admission?.id ?? c.receipt?.job_id ?? 'none', exitCode: c.receipt?.exit_code,
+            error: c.admission ? c.admission.error ?? 'Command admission has no durable process receipt. Inspect the owner before retrying.' : c.receipt?.error,
+            output: await this.output(c), evidence: c.evidence })));
+    }
+    async attachEvidence(name, expectedAttempt) {
+        const evidence = await this.mutate(async (data) => {
+            const c = this.find(data, name);
+            if (!c.receipt || c.receipt.job_id !== expectedAttempt)
+                throw new Error('Command attempt changed or has not started. Refresh before attaching evidence.');
+            if (c.state === 'running')
+                throw new Error('Wait for a terminal command result before attaching evidence.');
+            if (c.evidence)
+                return c.evidence;
+            const receipt = await readCommandJob(this.sessionId, expectedAttempt);
+            const log = await readFile(receipt.log_path);
+            if (log.length > 16 * 1024 * 1024)
+                throw new Error('Retained command log exceeds its evidence limit.');
+            const root = join(this.sessionDirectory, 'command-evidence');
+            await mkdir(root, { recursive: true, mode: 0o700 });
+            const target = join(root, expectedAttempt);
+            const staging = target + '.tmp-' + randomUUID();
+            await mkdir(staging, { mode: 0o700 });
+            try {
+                const outputSha256 = createHash('sha256').update(log).digest('hex');
+                const payload = JSON.stringify({ schemaVersion: 1, sessionId: this.sessionId, commandPaneId: c.id, name: c.name,
+                    command: c.command, cwd: c.cwd, environmentKeys: Object.keys(c.env), receipt, outputSha256, outputBytes: log.length }, null, 2);
+                const file = await open(join(staging, 'receipt.json'), 'wx', 0o600);
+                try {
+                    await file.writeFile(payload);
+                }
+                finally {
+                    await file.close();
+                }
+                const out = await open(join(staging, 'output.log'), 'wx', 0o600);
+                try {
+                    await out.writeFile(log);
+                }
+                finally {
+                    await out.close();
+                }
+                await rename(staging, target);
+                c.evidence = { path: join(target, 'receipt.json'), sha256: createHash('sha256').update(payload).digest('hex') };
+                return c.evidence;
+            }
+            finally {
+                await rm(staging, { recursive: true, force: true });
+            }
+        });
+        await this.publish();
+        return evidence;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        this.watch();
+        void this.list().then(views => { if (this.listeners.has(listener))
+            listener(views); }).catch(() => { });
+        return () => { this.listeners.delete(listener); };
+    }
+    watch() {
+        if (this.closed || this.timer)
+            return;
+        this.timer = setInterval(() => { if (!this.refreshTask)
+            void this.refresh().catch(() => { }); }, 1000);
+        this.timer.unref();
+    }
+    refresh() {
+        if (this.closed)
+            return Promise.resolve();
+        if (this.refreshTask)
+            return this.refreshTask;
+        this.refreshTask = (async () => {
+            const current = await this.read();
+            if (current.commands.some(c => c.state === 'running' || c.admission && this.admittedJobs.has(c.admission.id)))
+                await this.mutate(async (data) => {
+                    for (const c of data.commands) {
+                        if (c.admission) {
+                            const job = this.admittedJobs.get(c.admission.id);
+                            if (job) {
+                                c.receipt = await readCommandJob(this.sessionId, job);
+                                delete c.admission;
+                                c.state = stateOf(c.receipt);
+                            }
+                        }
+                        if (c.state !== 'running' || !c.receipt) {
+                            if (c.receipt)
+                                this.localJobs.delete(c.receipt.job_id);
+                            continue;
+                        }
+                        if (!this.localJobs.has(c.receipt.job_id) && alive(c.receipt.owner_pid))
+                            continue;
+                        c.receipt = await readCommandJob(this.sessionId, c.receipt.job_id);
+                        c.state = stateOf(c.receipt);
+                        if (c.state !== 'running')
+                            this.localJobs.delete(c.receipt.job_id);
+                    }
+                });
+            const reserved = new Set((await this.read()).commands.flatMap(c => c.admission ? [c.admission.id] : []));
+            for (const id of this.admittedJobs.keys())
+                if (!reserved.has(id))
+                    this.admittedJobs.delete(id);
+            const remaining = await this.read();
+            if (!remaining.commands.some(c => c.state === 'running' || c.admission && this.admittedJobs.has(c.admission.id)) && this.timer) {
+                clearInterval(this.timer);
+                this.timer = undefined;
+            }
+            await this.publish();
+        })().finally(() => { this.refreshTask = undefined; });
+        return this.refreshTask;
+    }
+    async publish() {
+        if (this.closed)
+            return;
+        const views = await this.list();
+        const signature = JSON.stringify(views);
+        if (signature === this.lastPublished)
+            return;
+        this.lastPublished = signature;
+        for (const listener of this.listeners) {
+            try {
+                listener(views);
+            }
+            catch { /* Views cannot change execution outcomes. */ }
+        }
+    }
+    async dispose() {
+        if (this.closed)
+            return;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        await this.refresh();
+        for (const job of this.localJobs)
+            await stopCommandJob(this.sessionId, job);
+        await this.refresh();
+        this.closed = true;
+        this.listeners.clear();
+    }
+}
+export function commandPaneText(command) {
+    return `${command.name} · ${command.state}${command.exitCode === undefined ? '' : ' · exit ' + command.exitCode}\n`
+        + `Directory: ${command.cwd}\nCommand: ${command.command}\nEnvironment: ${command.environmentKeys.join(', ') || 'inherited application environment'}\n`
+        + `Attempt: ${command.attempt}\n`
+        + (command.state === 'running' ? `/job stop ${command.name} --after ${command.attempt}\n`
+            : `/job ${command.attempt === 'none' ? 'start' : 'rerun'} ${command.name} --after ${command.attempt}\n`)
+        + (command.attempt !== 'none' && command.state !== 'running' ? `/job evidence ${command.name} --after ${command.attempt}\n` : '')
+        + (command.evidence ? `Evidence: ${command.evidence.path}\nSHA-256: ${command.evidence.sha256}\n` : '')
+        + (command.error ? `Error: ${command.error}\n` : '') + '\n' + command.output;
+}

package/dist/agent/runtime/command_wait.d.ts

@@ -0,0 +1,19 @@
+import type { AgentEvent, Message } from '../../types.js';
+import { type ManagedCommandObservation } from './command_jobs.js';
+export type ManagedCommandWaitObservation = ManagedCommandObservation & {
+    toolCallId: string;
+    readCursor?: number;
+};
+export interface ManagedCommandWaitOptions {
+    signal?: AbortSignal;
+    takeSteering?: () => Message[];
+    emit?: (event: AgentEvent) => void;
+    deadlineAt?: number;
+}
+export interface ManagedCommandWaitResult {
+    observations: ManagedCommandWaitObservation[];
+    steering: Message[];
+    waited: boolean;
+}
+export declare function awaitManagedCommandProgress(observations: readonly ManagedCommandWaitObservation[], options?: ManagedCommandWaitOptions): Promise<ManagedCommandWaitResult>;
+export declare function formatManagedCommandObservations(observations: readonly ManagedCommandWaitObservation[]): string;

package/dist/agent/runtime/command_wait.js

@@ -0,0 +1,167 @@
+import { readCommandJob, waitForCommandProgress } from './command_jobs.js';
+export async function awaitManagedCommandProgress(observations, options = {}) {
+    if (options.deadlineAt !== undefined && (!Number.isFinite(options.deadlineAt) || options.deadlineAt < 0)) {
+        throw new Error('deadlineAt must be a finite non-negative timestamp');
+    }
+    let current = observations.map(item => ({ ...item }));
+    // A launch or zero-wait inspection is not a request to suspend independent work.
+    if (!current.length || current.length > 256 || current.some(item => item.kind !== 'read'
+        || !Number.isSafeInteger(item.requestedWaitMs) || item.requestedWaitMs <= 0 || item.requestedWaitMs > 60000
+        || item.result.status !== 'running' || item.result.output !== '' || item.result.has_more
+        || !Number.isSafeInteger(item.result.cursor) || item.result.cursor < 0
+        || !item.toolCallId || item.toolCallId.length > 256)) {
+        return { observations: current, steering: [], waited: false };
+    }
+    // The scheduler may admit up to 256 calls, but one owned job/cursor needs
+    // only one waiter. The managed broker admits at most 32 active jobs.
+    const unique = new Map();
+    for (const item of current) {
+        const key = JSON.stringify([item.sessionId, item.result.job_id, item.result.cursor]);
+        if (!unique.has(key))
+            unique.set(key, item);
+    }
+    if (unique.size > 32)
+        return { observations: current, steering: [], waited: false };
+    current = [...unique.values()];
+    const refresh = async () => {
+        for (const item of current) {
+            item.readCursor = item.result.cursor;
+            item.result = await readCommandJob(item.sessionId, item.result.job_id, item.readCursor);
+        }
+    };
+    const startedAt = Date.now();
+    let reason = 'error';
+    for (const item of current)
+        options.emit?.({ type: 'command_wait', waiting: {
+                kind: 'managed_command', toolCallId: item.toolCallId, jobId: item.result.job_id,
+                cursor: item.result.cursor, startedAt, ...(options.deadlineAt === undefined ? {} : { deadlineAt: options.deadlineAt }),
+            } });
+    try {
+        while (true) {
+            if (options.signal?.aborted)
+                throw new Error('Command waiting cancelled; the owned job may still be running.');
+            const steering = options.takeSteering?.() ?? [];
+            if (steering.length) {
+                reason = 'steering';
+                await refresh();
+                return { observations: current, steering, waited: true };
+            }
+            const remaining = options.deadlineAt === undefined ? 60000 : Math.max(0, options.deadlineAt - Date.now());
+            if (remaining === 0) {
+                await refresh();
+                reason = 'deadline';
+                return { observations: current, steering: [], waited: true };
+            }
+            // Job notifications wake immediately; the bounded clock wake also admits Enter steering.
+            const maxWaitMs = Math.min(Math.ceil(remaining), options.takeSteering ? 1000 : 60000);
+            const reads = new AbortController();
+            const signal = options.signal ? AbortSignal.any([options.signal, reads.signal]) : reads.signal;
+            const pending = current.map(item => waitForCommandProgress(item.sessionId, item.result.job_id, { cursor: item.result.cursor, maxWaitMs, signal }));
+            let change;
+            try {
+                change = await Promise.race(pending);
+            }
+            finally {
+                reads.abort();
+                await Promise.allSettled(pending);
+            }
+            if (change.reason !== 'deadline') {
+                // Dispose the other read waiters, then preserve each job's exact current observation.
+                // Aborting a read never aborts its independently owned process.
+                await refresh();
+                reason = current.some(item => item.result.status !== 'running') ? 'terminal' : 'output';
+                return { observations: current, steering: [], waited: true };
+            }
+        }
+    }
+    catch (error) {
+        reason = options.signal?.aborted ? 'cancelled' : 'error';
+        throw error;
+    }
+    finally {
+        for (const item of current)
+            options.emit?.({ type: 'command_wait_end', toolCallId: item.toolCallId, reason });
+    }
+}
+export function formatManagedCommandObservations(observations) {
+    const prefix = '[Host command observation] ';
+    const budget = 64 * 1024;
+    if (observations.length > 32)
+        throw new Error('at most 32 managed command observations can be formatted');
+    const rows = observations.map(item => ({
+        toolCallId: item.toolCallId, job_id: item.result.job_id, status: item.result.status,
+        cursor: item.result.cursor, has_more: item.result.has_more, output: item.result.output,
+        ...(item.result.ended_at === undefined ? {} : { ended_at: item.result.ended_at }),
+        ...(item.result.exit_code === undefined ? {} : { exit_code: item.result.exit_code }),
+        ...(item.result.error === undefined ? {} : { error: item.result.error }),
+        ...(item.result.output_truncated === undefined ? {} : { output_truncated: item.result.output_truncated }),
+        ...(item.result.dropped_bytes === undefined ? {} : { dropped_bytes: item.result.dropped_bytes }),
+    }));
+    const serialize = () => prefix + JSON.stringify(rows);
+    const full = serialize();
+    if (Buffer.byteLength(full) <= budget)
+        return full;
+    const fields = [];
+    for (const [index, item] of observations.entries()) {
+        const row = rows[index];
+        for (const field of ['output', 'error']) {
+            const value = item.result[field];
+            if (!value)
+                continue;
+            fields.push({ index, field, value });
+            row[field] = '';
+            row[field === 'output' ? 'output_omitted_bytes' : 'error_omitted_bytes'] = Buffer.byteLength(value);
+        }
+        if ((row.output_omitted_bytes ?? 0) > 0 || (row.error_omitted_bytes ?? 0) > 0) {
+            row.retrieval = { tool: 'read_command', arguments: {
+                    job_id: item.result.job_id,
+                    cursor: item.readCursor ?? Math.max(0, item.result.cursor - Buffer.byteLength(item.result.output)),
+                    wait_ms: 0,
+                } };
+        }
+    }
+    const metadataBytes = Buffer.byteLength(serialize());
+    if (metadataBytes > budget)
+        throw new Error('managed command observation metadata exceeds the context budget');
+    const allowance = Math.floor((budget - metadataBytes) / Math.max(1, fields.length));
+    for (const { index, field, value } of fields) {
+        const row = rows[index];
+        const initialBytes = Buffer.byteLength(JSON.stringify(row));
+        const characters = Array.from(value);
+        const sourceBytes = Buffer.byteLength(value);
+        const project = (count) => {
+            const visible = characters.slice(0, count).join('');
+            const candidate = { ...row, [field]: visible };
+            const omittedField = field === 'output' ? 'output_omitted_bytes' : 'error_omitted_bytes';
+            const omitted = sourceBytes - Buffer.byteLength(visible);
+            if (omitted > 0)
+                candidate[omittedField] = omitted;
+            else
+                delete candidate[omittedField];
+            if (!(candidate.output_omitted_bytes ?? 0) && !(candidate.error_omitted_bytes ?? 0))
+                delete candidate.retrieval;
+            return candidate;
+        };
+        const fits = (candidate) => Buffer.byteLength(JSON.stringify(candidate)) - initialBytes <= allowance;
+        const complete = project(characters.length);
+        if (fits(complete)) {
+            rows[index] = complete;
+            continue;
+        }
+        // Search code-point boundaries using encoded JSON bytes, including escaping.
+        let low = 0;
+        let high = characters.length - 1;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            if (fits(project(middle)))
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        rows[index] = project(low);
+    }
+    const bounded = serialize();
+    if (Buffer.byteLength(bounded) > budget)
+        throw new Error('managed command observation metadata exceeds the context budget');
+    return bounded;
+}

package/dist/agent/runtime/cpu_benchmark.d.ts

@@ -0,0 +1,30 @@
+import type { ToolContext } from '../tools/types.js';
+export type CPUVariant = 'for_loop' | 'array_reduce';
+export interface CPUWorkload {
+    values: number[];
+    config: {
+        schema_version: 1;
+        variant: CPUVariant;
+        iterations: number;
+        warmup: number;
+        samples: number;
+    };
+}
+export declare const CPU_HOST_INSTANCE_ID: string;
+export declare const cpuHash: (text: string) => string;
+/** Independent exact arithmetic, outside the measured process and timing interval. */
+export declare function integerSumOracle(values: readonly number[]): number;
+export declare const CPU_PROGRAM_SHA256: Readonly<{
+    for_loop: string;
+    array_reduce: string;
+}>;
+export declare const CPU_CHECKER_SHA256: string;
+export declare const CPU_RECIPE_SHA256: string;
+export declare function parseCPUWorkload(input: string, config: string): CPUWorkload | null;
+export interface CPURun {
+    outcome: 'passed' | 'failed' | 'timed_out' | 'cancelled' | 'unknown';
+    output: string;
+    executionPolicyId: string | null;
+}
+/** Launch only the fixed host script; project bytes enter through stdin as data, never code. */
+export declare function runCPUWorkload(workload: CPUWorkload, context: Pick<ToolContext, 'cwd' | 'signal' | 'commandPolicy'>): Promise<CPURun>;