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

package/dist/environment/store.js

@@ -0,0 +1,387 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { cp, mkdir, readFile, readdir, rename, rm, lstat, realpath, readlink, writeFile, open } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, relative, isAbsolute, dirname, sep } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { activeProfile, validateProfileName } from '../config/profiles.js';
+import { writeFileAtomic } from '../utils/atomic_write.js';
+const root = () => join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'environments');
+const namePattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const valid = (name) => {
+    if (!namePattern.test(name))
+        throw new Error('Environment name must use 1–64 letters, numbers, underscores or hyphens.');
+    return name;
+};
+const envPath = (name) => join(root(), valid(name));
+const now = () => new Date().toISOString();
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code !== 'ESRCH';
+    }
+}
+/** Only this exact directory owns files; symlinked environment roots are refused. */
+async function directory(name) {
+    await requireDirectory(root());
+    const path = envPath(name);
+    const info = await lstat(path);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error('Environment directory is not an owned local directory.');
+    return path;
+}
+async function requireDirectory(path) {
+    const info = await lstat(path);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error('Environment requires an owned local directory.');
+}
+async function ownedDirectory(parent, name) {
+    const path = join(parent, name);
+    await mkdir(path, { mode: 0o700 }).catch(error => {
+        if (error.code !== 'EEXIST')
+            throw error;
+    });
+    await requireDirectory(path);
+    return path;
+}
+async function read(name) {
+    const path = await directory(name);
+    const data = JSON.parse(await readFile(join(path, 'manifest.json'), 'utf8'));
+    if (data.schemaVersion !== 1 || data.name !== name || data.backend !== 'local')
+        throw new Error('Invalid environment manifest.');
+    const expectedWorkspace = join(path, 'workspace');
+    const workspace = await lstat(expectedWorkspace);
+    if (!workspace.isDirectory() || workspace.isSymbolicLink())
+        throw new Error('Environment no longer has an owned workspace directory.');
+    const canonicalWorkspace = await realpath(expectedWorkspace);
+    if (data.workspacePath !== expectedWorkspace && data.workspacePath !== canonicalWorkspace)
+        throw new Error('Invalid environment workspace path.');
+    data.workspacePath = canonicalWorkspace;
+    const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+    if (!uuid.test(data.id) || !Array.isArray(data.checkpoints) || !Array.isArray(data.services)
+        || data.checkpoints.some(c => !uuid.test(c.id)) || data.services.some(s => !uuid.test(s.id)))
+        throw new Error('Invalid environment identities.');
+    validateProfileName(data.credentialProfile);
+    return data;
+}
+async function save(record) { record.updatedAt = now(); await writeFileAtomic(join(envPath(record.name), 'manifest.json'), JSON.stringify(record, null, 2)); }
+async function mutate(name, fn) {
+    const path = await directory(name);
+    const lock = join(path, 'operation.lock');
+    const handle = await open(lock, 'wx', 0o600).catch(error => {
+        if (error.code === 'EEXIST')
+            throw new Error('Environment operation is already in progress. Inspect operation.lock before recovery.');
+        throw error;
+    });
+    try {
+        await handle.writeFile(JSON.stringify({ pid: process.pid, startedAt: now() }));
+        return await fn(await read(name), path);
+    }
+    finally {
+        await handle.close();
+        await rm(lock).catch(e => {
+            if (e.code !== 'ENOENT')
+                throw e;
+        });
+    }
+}
+function assertOwner(record, sessionId) {
+    if (!record.owner || record.owner.sessionId !== sessionId || record.owner.pid !== process.pid)
+        throw new Error('Environment is not owned by this session. Open it before changing it.');
+}
+async function inventory(path, prefix = '') {
+    await requireDirectory(path);
+    const files = [];
+    for (const entry of (await readdir(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = join(path, entry.name);
+        const child = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const info = await lstat(full);
+        const mode = info.mode & 0o777;
+        if (entry.isDirectory()) {
+            files.push({ path: child, kind: 'directory', bytes: 0, sha256: '', mode });
+            files.push(...await inventory(full, child));
+        }
+        else if (entry.isFile()) {
+            const hash = createHash('sha256');
+            let bytes = 0;
+            for await (const chunk of createReadStream(full)) {
+                hash.update(chunk);
+                bytes += chunk.length;
+            }
+            files.push({ path: child, kind: 'file', bytes, sha256: hash.digest('hex'), mode });
+        }
+        else if (entry.isSymbolicLink()) {
+            const target = await readlink(full);
+            files.push({ path: child, kind: 'symlink', target, mode, bytes: Buffer.byteLength(target), sha256: createHash('sha256').update(target).digest('hex') });
+        }
+        else
+            throw new Error(`Checkpoint cannot capture special file ${child}; pause its service first.`);
+    }
+    return files;
+}
+async function services(record) {
+    const results = [];
+    if (record.services.length)
+        await requireDirectory(join(envPath(record.name), 'services'));
+    for (const service of record.services) {
+        await requireDirectory(join(envPath(record.name), 'services', service.id));
+        let receipt;
+        try {
+            receipt = JSON.parse(await readFile(join(envPath(record.name), 'services', service.id, 'receipt.json'), 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            receipt = { ...service };
+        }
+        if (receipt.id !== service.id || !['starting', 'running', 'stopped', 'failed', 'recovery_required'].includes(receipt.status))
+            throw new Error('Invalid service receipt; inspect the environment before recovery.');
+        receipt = { ...service, status: receipt.status, heartbeat: receipt.heartbeat, exitCode: receipt.exitCode, endedAt: receipt.endedAt, failure: receipt.failure, outputTruncated: receipt.outputTruncated };
+        if (['starting', 'running'].includes(receipt.status) && (!receipt.heartbeat || Date.now() - Date.parse(receipt.heartbeat) > 5000))
+            receipt.status = 'recovery_required';
+        results.push(receipt);
+    }
+    return results;
+}
+export async function getEnvironment(name) {
+    const record = await read(name);
+    record.services = await services(record);
+    return record;
+}
+export async function listEnvironments() {
+    let names;
+    try {
+        names = await readdir(root());
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    const records = [];
+    for (const name of names.filter(name => namePattern.test(name))) {
+        const info = await lstat(envPath(name));
+        if (info.isDirectory() && !info.isSymbolicLink())
+            records.push(await getEnvironment(name));
+    }
+    return records;
+}
+export async function createEnvironment(name, sessionId) {
+    valid(name);
+    await mkdir(root(), { recursive: true, mode: 0o700 });
+    await requireDirectory(root());
+    const path = envPath(name);
+    await mkdir(path, { mode: 0o700 }).catch(e => {
+        if (e.code === 'EEXIST')
+            throw new Error('Environment already exists; open it to resume.');
+        throw e;
+    });
+    try {
+        await mkdir(join(path, 'workspace'), { mode: 0o700 });
+        const record = { schemaVersion: 1, id: randomUUID(), name, backend: 'local', workspacePath: await realpath(join(path, 'workspace')), credentialProfile: activeProfile(), status: 'active', createdAt: now(), updatedAt: now(), owner: { sessionId, pid: process.pid, token: randomUUID() }, checkpoints: [], services: [], setupNotes: [] };
+        await save(record);
+        return record;
+    }
+    catch (e) {
+        await rm(path, { recursive: true, force: true });
+        throw e;
+    }
+}
+export async function openEnvironment(name, sessionId) {
+    return mutate(name, async (record) => {
+        if (record.credentialProfile !== activeProfile())
+            throw new Error(`Environment credentials reference profile ${record.credentialProfile}. Select that profile before opening it.`);
+        if (record.owner && alive(record.owner.pid) && (record.owner.pid !== process.pid || record.owner.sessionId !== sessionId))
+            throw new Error('Environment is owned by another live session.');
+        record.owner = { sessionId, pid: process.pid, token: randomUUID() };
+        await save(record);
+        return getEnvironment(name);
+    });
+}
+export async function releaseEnvironment(name, sessionId) {
+    await mutate(name, async (record) => { assertOwner(record, sessionId); delete record.owner; await save(record); });
+}
+export async function checkpointEnvironment(name, sessionId, label) {
+    return mutate(name, async (record, path) => {
+        assertOwner(record, sessionId);
+        const live = await services(record);
+        if (live.some(s => ['running', 'starting', 'recovery_required'].includes(s.status)))
+            throw new Error('Pause environment services before checkpointing a consistent workspace.');
+        const id = randomUUID();
+        const checkpoints = await ownedDirectory(path, 'checkpoints');
+        const dest = await ownedDirectory(checkpoints, id);
+        try {
+            const before = await inventory(record.workspacePath);
+            await cp(record.workspacePath, join(dest, 'workspace'), { recursive: true, dereference: false, verbatimSymlinks: true });
+            const copied = await inventory(join(dest, 'workspace'));
+            const after = await inventory(record.workspacePath);
+            if (JSON.stringify(before) !== JSON.stringify(copied) || JSON.stringify(before) !== JSON.stringify(after))
+                throw new Error('Workspace changed during checkpoint. Pause writers and retry.');
+            const checkpoint = { id, label: label.slice(0, 200), createdAt: now(), files: copied, services: live.map(s => ({ name: s.name, command: s.command, cwd: s.cwd ?? record.workspacePath })) };
+            await writeFile(join(dest, 'checkpoint.json'), JSON.stringify(checkpoint), { mode: 0o600, flag: 'wx' });
+            record.checkpoints.unshift(checkpoint);
+            await save(record);
+            return checkpoint;
+        }
+        catch (e) {
+            await rm(dest, { recursive: true, force: true });
+            throw e;
+        }
+    });
+}
+export async function restoreEnvironment(name, sessionId, checkpointId) {
+    return mutate(name, async (record, path) => {
+        assertOwner(record, sessionId);
+        if (record.status !== 'paused')
+            throw new Error('Pause the environment before restoring.');
+        const checkpoint = record.checkpoints.find(c => c.id === checkpointId);
+        if (!checkpoint)
+            throw new Error('Checkpoint not found.');
+        if ((await services(record)).some(s => ['running', 'starting', 'recovery_required'].includes(s.status)))
+            throw new Error('Service recovery is unresolved; inspect it before restoring.');
+        await requireDirectory(join(path, 'checkpoints'));
+        await requireDirectory(join(path, 'checkpoints', checkpoint.id));
+        const source = join(path, 'checkpoints', checkpoint.id, 'workspace');
+        const sourceInfo = await lstat(source);
+        if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink())
+            throw new Error('Checkpoint integrity failed; current workspace preserved.');
+        if (JSON.stringify(await inventory(source)) !== JSON.stringify(checkpoint.files))
+            throw new Error('Checkpoint integrity failed; current workspace preserved.');
+        const replacement = join(path, `restore-${randomUUID()}`);
+        await cp(source, replacement, { recursive: true, dereference: false, verbatimSymlinks: true });
+        if (JSON.stringify(await inventory(replacement)) !== JSON.stringify(checkpoint.files)) {
+            await rm(replacement, { recursive: true, force: true });
+            throw new Error('Checkpoint integrity failed; current workspace preserved.');
+        }
+        const backup = join(path, `before-restore-${randomUUID()}`);
+        await rename(record.workspacePath, backup);
+        try {
+            await rename(replacement, record.workspacePath);
+        }
+        catch (e) {
+            await rename(backup, record.workspacePath);
+            throw e;
+        }
+        // Preserve the replaced workspace as recovery evidence instead of deleting it.
+        const externalLinks = checkpoint.files.filter(f => f.kind === 'symlink' && !isEnvironmentWorkspacePath(record.workspacePath, resolve(dirname(join(record.workspacePath, f.path)), f.target))).map(f => f.path);
+        record.recovery = { checkpointId, restoredAt: now(), retainedFiles: checkpoint.files.filter(f => f.kind !== 'directory').length, servicesNeedingRestart: checkpoint.services.map(s => s.name), externalLinks };
+        await save(record);
+        return getEnvironment(name);
+    });
+}
+export async function addEnvironmentNote(name, sessionId, text) {
+    if (!text.trim() || text.length > 4000)
+        throw new Error('Setup note must contain 1–4000 characters.');
+    await mutate(name, async (record) => { assertOwner(record, sessionId); record.setupNotes.push({ text, createdAt: now() }); await save(record); });
+}
+export async function startEnvironmentService(name, sessionId, serviceName, command, shell, workingDirectory) {
+    valid(serviceName);
+    if (!command.trim() || command.length > 16000)
+        throw new Error('Service command must contain 1–16000 characters.');
+    return mutate(name, async (record, path) => {
+        assertOwner(record, sessionId);
+        if (record.status !== 'active')
+            throw new Error('Resume the environment before starting a service.');
+        const serviceCwd = await realpath(workingDirectory ?? record.workspacePath);
+        if (!isEnvironmentWorkspacePath(await realpath(record.workspacePath), serviceCwd))
+            throw new Error('Service directory must remain inside its owned environment workspace.');
+        const live = await services(record);
+        if (live.some(s => s.name === serviceName && ['running', 'starting', 'recovery_required'].includes(s.status)))
+            throw new Error('Service already runs or needs recovery; inspect it before restarting.');
+        const id = randomUUID();
+        const serviceRoot = await ownedDirectory(path, 'services');
+        const serviceDir = await ownedDirectory(serviceRoot, id);
+        const service = { id, name: serviceName, command, cwd: serviceCwd, status: 'starting', startedAt: now(), heartbeat: now(), logPath: join(serviceDir, 'output.log') };
+        await writeFile(join(serviceDir, 'launch.json'), JSON.stringify({ service, cwd: serviceCwd, shell }), { flag: 'wx', mode: 0o600 });
+        record.services.push(service);
+        await save(record);
+        const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+        const runner = fileURLToPath(new URL(`./service_runner.${extension}`, import.meta.url));
+        const child = spawn(process.execPath, [...(extension === 'ts' ? ['--import', import.meta.resolve('tsx')] : []), runner, serviceDir], { cwd: serviceCwd, detached: true, stdio: 'ignore', env: process.env });
+        child.unref();
+        try {
+            await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+        }
+        catch (error) {
+            service.status = 'failed';
+            service.failure = String(error);
+            await writeFileAtomic(join(serviceDir, 'receipt.json'), JSON.stringify(service));
+            throw error;
+        }
+        return service;
+    });
+}
+export async function pauseEnvironment(name, sessionId) {
+    return mutate(name, async (record) => {
+        assertOwner(record, sessionId);
+        const live = await services(record);
+        for (const service of live)
+            if (['running', 'starting', 'recovery_required'].includes(service.status))
+                await writeFile(join(envPath(name), 'services', service.id, 'stop'), service.id, { mode: 0o600 });
+        const until = Date.now() + 8000;
+        while ((await services(record)).some(s => ['running', 'starting'].includes(s.status)) && Date.now() < until)
+            await new Promise(r => setTimeout(r, 50));
+        record.services = await services(record);
+        if (record.services.some(s => ['running', 'starting', 'recovery_required'].includes(s.status)))
+            throw new Error('Service did not stop or requires recovery. Workspace unchanged; inspect its receipt and output.');
+        record.status = 'paused';
+        await save(record);
+        return getEnvironment(name);
+    });
+}
+export async function resumeEnvironment(name, sessionId) { return mutate(name, async (record) => { assertOwner(record, sessionId); record.status = 'active'; await save(record); return getEnvironment(name); }); }
+export async function discardEnvironment(name, sessionId) {
+    return mutate(name, async (record, path) => {
+        assertOwner(record, sessionId);
+        if (record.status !== 'paused' || (await services(record)).some(s => ['running', 'starting', 'recovery_required'].includes(s.status)))
+            throw new Error('Pause the environment and resolve services before discarding.');
+        const archive = await ownedDirectory(root(), '.discarded');
+        const target = join(archive, `${name}-${record.id}`);
+        await rename(path, target);
+        await rm(join(target, 'operation.lock'));
+        return target;
+    });
+}
+export async function environmentForWorkspace(cwd) {
+    const absolute = await realpath(cwd);
+    for (const record of await listEnvironments()) {
+        const workspace = await realpath(record.workspacePath);
+        if (isEnvironmentWorkspacePath(workspace, absolute))
+            return record;
+    }
+    return undefined;
+}
+/** Bounded setup context, without keys, owner tokens or service launch commands. */
+export function describeEnvironmentForAgent(record) {
+    return [
+        `Durable local environment: ${record.name} (${record.id}), ${record.status}.`,
+        `Workspace: ${record.workspacePath}. Credentials reference config profile ${record.credentialProfile}.`,
+        'Installed dependencies and repositories persist here. Checkpoint restore never restarts services.',
+        record.recovery ? `Restored checkpoint ${record.recovery.checkpointId}; services requiring explicit restart: ${record.recovery.servicesNeedingRestart.join(', ') || 'none'}.` : '',
+        ...record.setupNotes.slice(-20).map(note => `Saved setup note: ${note.text}`),
+    ].filter(Boolean).join('\n');
+}
+/** Observable status excludes potentially huge per-file inventories and owner tokens. */
+export function environmentSummary(record) {
+    return {
+        ...record,
+        owner: record.owner ? { sessionId: record.owner.sessionId, pid: record.owner.pid } : undefined,
+        checkpointCount: record.checkpoints.length,
+        checkpoints: record.checkpoints.slice(0, 100).map(point => ({ id: point.id, label: point.label, createdAt: point.createdAt, retainedFiles: point.files.filter(file => file.kind !== 'directory').length, services: point.services.map(service => service.name) })),
+        serviceCount: record.services.length,
+        services: record.services.slice(-100),
+        setupNoteCount: record.setupNotes.length,
+        setupNotes: record.setupNotes.slice(-20),
+    };
+}
+export function isEnvironmentWorkspacePath(workspace, path) {
+    const child = relative(workspace, path);
+    return child === '' || (!isAbsolute(child) && child !== '..' && !child.startsWith(`..${sep}`));
+}
+/** A saved environment could not be attached without violating recovery guards. */
+export class EnvironmentRecoveryError extends Error {
+}

package/dist/events.d.ts

@@ -1,3 +1,23 @@
+import type { GoalView } from './goal_contract.js';
+export type { GoalView, GoalProjection } from './goal_contract.js';
+export { parseGoalView, parseGoalProjection, retainGoalView } from './goal_contract.js';
+import type { CommandWaitingState } from './types.js';
+import type { EvidenceSnapshot } from './agent/runtime/evidence.js';
+import type { TaskHandoffProjection } from './session_handoff_contract.js';
+export type { TaskHandoffSnapshot, TaskHandoffProjection, TaskHandoffCorrection } from './session_handoff_contract.js';
+export { parseTaskHandoffSnapshot, parseTaskHandoffProjection } from './session_handoff_contract.js';
+export type { TaskHandoffView } from './web/view_plugin.js';
+export { parseTaskHandoffView, retainTaskHandoffView } from './web/view_plugin.js';
+export type { EvidenceSnapshot, EvidenceRecord, EvidenceSource } from './agent/runtime/evidence.js';
+export type { DelegatedEvidenceHandoff } from './agent/runtime/delegated_evidence.js';
+export { parseEvidenceSnapshot } from './agent/runtime/evidence.js';
+export { parseCheckedCommandResult } from './agent/runtime/checked_commands.js';
+export type { CommandExecutionPolicy, CommandExecutionObservation } from './agent/runtime/command_execution_policy.js';
+export { parseCommandExecutionPolicy, parseCommandExecutionObservation } from './agent/runtime/command_execution_policy.js';
+export type { VerifierDecision, HostVerifierDecision } from './agent/runtime/verifier_contract.js';
+export { parseVerifierDecision, parseHostVerifierDecision } from './agent/runtime/verifier_contract.js';
+export type { CommandVerificationReceipt, CurrentVerificationProjection, SourceSnapshot } from './agent/runtime/source_verification_contract.js';
+export { parseCommandVerificationReceipt, parseCurrentVerificationProjection } from './agent/runtime/source_verification_contract.js';
 /**
  * Public library entry for ZTC event types.
  *
@@ -15,7 +35,7 @@
  * Both are exported here as a discriminated union so embedders don't have to
  * re-declare them.
  */
-export type { AgentEvent } from './types.js';
+export type { AgentEvent, CommandWaitingState } from './types.js';
 export type { Message, MessageRole, ToolCall, AgentStatus, TodoStatus } from './types.js';
 export type HeadlessStatus = 'session_loaded' | 'session_new' | 'ready' | 'thinking' | 'streaming' | 'tool_use' | 'idle' | 'auto_continue' | 'output_saved' | 'task_completed_detected' | 'session_saved' | 'debug' | 'headless_shell_mode' | 'prompt_too_long';
 export interface HeadlessEventBase {
@@ -23,9 +43,24 @@ export interface HeadlessEventBase {
     session_id?: string;
 }
 export type HeadlessEvent = (HeadlessEventBase & {
+    type: 'goal';
+    data: GoalView;
+}) | (HeadlessEventBase & {
+    type: 'task_handoff';
+    data: {
+        sessionId: string;
+        projection: TaskHandoffProjection | null;
+    };
+}) | (HeadlessEventBase & {
+    type: 'evidence';
+    data: {
+        snapshot: EvidenceSnapshot;
+    };
+}) | (HeadlessEventBase & {
     type: 'status';
     data: {
         status: HeadlessStatus | string;
+        waiting?: CommandWaitingState;
         [k: string]: unknown;
     };
 }) | (HeadlessEventBase & {
@@ -109,3 +144,7 @@ export declare function parseHeadlessEvent(line: string): HeadlessEvent | null;
  * reading multi-prompt sessions don't exit early.
  */
 export declare function isTurnComplete(event: HeadlessEvent): boolean;
+export type { BenchmarkVerifierDecision } from './agent/runtime/benchmark_contract.js';
+export { parseBenchmarkVerifierDecision } from './agent/runtime/benchmark_contract.js';
+export type { BenchmarkComparisonDecision } from './agent/runtime/benchmark_comparison.js';
+export { parseBenchmarkComparisonDecision } from './agent/runtime/benchmark_comparison.js';

package/dist/events.js

@@ -1,20 +1,11 @@
-/**
- * Public library entry for ZTC event types.
- *
- * Two related event surfaces live in ZTC:
- *
- *   1. `AgentEvent` — internal events the in-process `Agent` emits to its
- *      subscribers (thinking_start, tool_start/end, stream_start/delta/end,
- *      token_usage, error, ...). Embedders using the library path (see
- *      the root `zerg-ztc` export) subscribe to these directly.
- *
- *   2. `HeadlessEvent` — the NDJSON protocol the `--headless --json` runner
- *      writes to stdout, and reads from stdin. Embedders running ZTC as a
- *      subprocess (e.g. ca_org's ZtcPool) parse these line-by-line.
- *
- * Both are exported here as a discriminated union so embedders don't have to
- * re-declare them.
- */
+export { parseGoalView, parseGoalProjection, retainGoalView } from './goal_contract.js';
+export { parseTaskHandoffSnapshot, parseTaskHandoffProjection } from './session_handoff_contract.js';
+export { parseTaskHandoffView, retainTaskHandoffView } from './web/view_plugin.js';
+export { parseEvidenceSnapshot } from './agent/runtime/evidence.js';
+export { parseCheckedCommandResult } from './agent/runtime/checked_commands.js';
+export { parseCommandExecutionPolicy, parseCommandExecutionObservation } from './agent/runtime/command_execution_policy.js';
+export { parseVerifierDecision, parseHostVerifierDecision } from './agent/runtime/verifier_contract.js';
+export { parseCommandVerificationReceipt, parseCurrentVerificationProjection } from './agent/runtime/source_verification_contract.js';
 /**
  * Parse one NDJSON line into a typed `HeadlessEvent`. Returns null on non-JSON
  * or on unknown shapes — embedders should typically just `continue` in that
@@ -57,3 +48,5 @@ export function isTurnComplete(event) {
         return false;
     return true; // Unknown scope: fail-open so consumers stop instead of hanging.
 }
+export { parseBenchmarkVerifierDecision } from './agent/runtime/benchmark_contract.js';
+export { parseBenchmarkComparisonDecision } from './agent/runtime/benchmark_comparison.js';

package/dist/goal_contract.d.ts

@@ -0,0 +1,25 @@
+import type { GoalRecord } from './agent/commands/goal.js';
+import { type GoalPlateauState, type GoalExitReason, type SustainedGoalAuthority } from './agent/commands/goal_exit.js';
+/** Bounded projection of the existing goal, never another experiment ledger. */
+export interface GoalProjection {
+    schemaVersion: 1;
+    goalId: string;
+    objective: string;
+    status: GoalRecord['status'];
+    tokenBudget: number | null;
+    tokensUsed: number;
+    maxTurns: number | null;
+    turns: number;
+    updatedAt: number;
+    plateau: GoalPlateauState | null;
+    exitReason: GoalExitReason | null;
+    sustained: SustainedGoalAuthority | null;
+}
+export interface GoalView {
+    sessionId: string;
+    goal: GoalProjection | null;
+}
+export declare function parseGoalProjection(value: unknown): GoalProjection | null;
+export declare function projectGoal(record: GoalRecord | null): GoalProjection | null;
+export declare function parseGoalView(value: unknown): GoalView | null;
+export declare function retainGoalView(previous: GoalView | undefined, next: GoalView): GoalView;

package/dist/goal_contract.js

@@ -0,0 +1,44 @@
+import { parseGoalPlateauState, parseGoalExitReason, parseSustainedGoalAuthority } from './agent/commands/goal_exit.js';
+const boundedText = (value, bytes) => typeof value === 'string'
+    && value.trim().length > 0 && new TextEncoder().encode(value).length <= bytes && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value);
+const integer = (value, min = 0) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+function exact(value, keys) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+        && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+export function parseGoalProjection(value) {
+    if (!exact(value, ['schemaVersion', 'goalId', 'objective', 'status', 'tokenBudget', 'tokensUsed', 'maxTurns',
+        'turns', 'updatedAt', 'plateau', 'exitReason', 'sustained']) || value.schemaVersion !== 1
+        || !boundedText(value.goalId, 256) || /[\r\n\t]/u.test(value.goalId) || !boundedText(value.objective, 8000)
+        || typeof value.status !== 'string' || !['active', 'paused', 'complete', 'budget_limited', 'blocked'].includes(value.status)
+        || !(value.tokenBudget === null || integer(value.tokenBudget, 1)) || !integer(value.tokensUsed)
+        || !(value.maxTurns === null || integer(value.maxTurns, 1)) || !integer(value.turns) || !integer(value.updatedAt))
+        return null;
+    const plateau = value.plateau === null ? null : parseGoalPlateauState(value.plateau);
+    const exitReason = value.exitReason === null ? null : parseGoalExitReason(value.exitReason);
+    const sustained = value.sustained === null ? null : parseSustainedGoalAuthority(value.sustained);
+    if ((value.plateau !== null && !plateau) || (value.exitReason !== null && !exitReason) || (value.sustained !== null && !sustained))
+        return null;
+    return { ...structuredClone(value), plateau, exitReason, sustained };
+}
+export function projectGoal(record) {
+    if (!record)
+        return null;
+    return parseGoalProjection({ schemaVersion: 1, goalId: record.goalId, objective: record.objective, status: record.status,
+        tokenBudget: record.tokenBudget ?? null, tokensUsed: record.tokensUsed, maxTurns: record.maxTurns ?? null,
+        turns: record.turns, updatedAt: record.updatedAt, plateau: record.plateau ?? null,
+        exitReason: record.exitReason ?? null, sustained: record.sustained ?? null });
+}
+export function parseGoalView(value) {
+    if (!exact(value, ['sessionId', 'goal']) || !boundedText(value.sessionId, 256) || /[\r\n\t]/u.test(value.sessionId))
+        return null;
+    const goal = value.goal === null ? null : parseGoalProjection(value.goal);
+    return value.goal !== null && !goal ? null : { sessionId: value.sessionId, goal };
+}
+export function retainGoalView(previous, next) {
+    if (previous?.sessionId === next.sessionId && previous.goal?.goalId === next.goal?.goalId
+        && previous.goal && next.goal && next.goal.updatedAt < previous.goal.updatedAt)
+        return previous;
+    return next;
+}