agenttaskflow 0.0.1 → 0.4.2

package/dist/state.js

@@ -0,0 +1,92 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, renameSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import lockfile from 'proper-lockfile';
+import { StateError } from './errors.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, val]) => [key, canonical(val)]));
+    }
+    return value;
+}
+export const fingerprint = (value) => createHash('sha256')
+    .update(JSON.stringify(canonical(value))).digest('hex');
+export function writeJson(file, value) {
+    const temp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+    renameSync(temp, file);
+}
+export class State {
+    directory;
+    file;
+    snapshot;
+    unlock;
+    compromised;
+    constructor(directory, runId, configuration) {
+        this.directory = join(directory, runId);
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        this.file = join(this.directory, 'state.json');
+        try {
+            this.unlock = lockfile.lockSync(this.directory, {
+                stale: 30_000, update: 10_000, retries: 0,
+                onCompromised: error => { this.compromised = error; },
+            });
+        }
+        catch (error) {
+            throw new StateError(`Run ${runId} is already locked or cannot be opened: ${String(error)}`);
+        }
+        try {
+            const config = fingerprint(configuration);
+            this.snapshot = existsSync(this.file) ? JSON.parse(readFileSync(this.file, 'utf8')) :
+                { version: 1, config, checkpoints: {} };
+            if (this.snapshot.version !== 1 || this.snapshot.config !== config) {
+                throw new StateError('Run configuration/version changed; use a new runId');
+            }
+            this.persist();
+        }
+        catch (error) {
+            this.unlock();
+            throw error;
+        }
+    }
+    assertOwned() {
+        if (this.compromised)
+            throw new StateError(`Run lock lost: ${this.compromised.message}`);
+    }
+    persist() { this.assertOwned(); writeJson(this.file, this.snapshot); }
+    get sessionId() { return this.snapshot.sessionId; }
+    bind(sessionId) {
+        this.assertOwned();
+        if (this.snapshot.sessionId && this.snapshot.sessionId !== sessionId) {
+            throw new ProtocolStateError('Host changed the session ID');
+        }
+        if (this.snapshot.sessionId !== sessionId) {
+            this.snapshot.sessionId = sessionId;
+            this.persist();
+        }
+    }
+    saveCheckpoint(key, value, input) {
+        // Store serialized copies, so callers cannot mutate persisted state indirectly.
+        const copy = JSON.parse(JSON.stringify(value));
+        Object.defineProperty(this.snapshot.checkpoints, key, {
+            value: { input: fingerprint(input), value: copy }, enumerable: true, writable: true, configurable: true,
+        });
+        this.persist();
+    }
+    loadCheckpoint(key, input) {
+        this.assertOwned();
+        if (!Object.hasOwn(this.snapshot.checkpoints, key))
+            return undefined;
+        const saved = this.snapshot.checkpoints[key];
+        if (saved.input !== fingerprint(input))
+            throw new StateError(`Checkpoint ${key} inputs changed`);
+        return JSON.parse(JSON.stringify(saved.value));
+    }
+    close() { this.unlock(); }
+}
+class ProtocolStateError extends StateError {
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/sync.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { AgentOptions, RunOptions } from './agent.js';
+export type SyncAgentOptions = Omit<AgentOptions, 'signal'>;
+export type SyncRunOptions<S extends z.ZodType = z.ZodType> = Omit<RunOptions<S>, 'signal'>;
+/** Blocking workflow API. A worker thread keeps agent I/O and timeouts running. */
+export declare class Agent {
+    private options;
+    private worker;
+    private port;
+    private wake;
+    private sequence;
+    private closed;
+    private busy;
+    private display;
+    runId: string;
+    sessionId?: string;
+    pid?: number;
+    constructor(options?: SyncAgentOptions);
+    run<S extends z.ZodType>(prompt: string, options: SyncRunOptions<S> & {
+        schema: S;
+    }): z.output<S>;
+    run(prompt: string, options?: SyncRunOptions & {
+        schema?: undefined;
+    }): string;
+    saveCheckpoint(key: string, value: unknown, input: unknown): void;
+    loadCheckpoint<T = unknown>(key: string, input: unknown): T | undefined;
+    close(): void;
+    [Symbol.dispose](): void;
+    private request;
+}
+export declare function withAgent<T>(options: SyncAgentOptions, workflow: (agent: Agent) => T): T;

package/dist/sync.js

@@ -0,0 +1,151 @@
+import { MessageChannel, receiveMessageOnPort, Worker } from 'node:worker_threads';
+import { z } from 'zod';
+import { Console } from './events.js';
+import * as errors from './errors.js';
+/** Blocking workflow API. A worker thread keeps agent I/O and timeouts running. */
+export class Agent {
+    options;
+    worker;
+    port;
+    wake = new Int32Array(new SharedArrayBuffer(4));
+    sequence = 0;
+    closed = false;
+    busy = false;
+    display;
+    runId = '';
+    sessionId;
+    pid;
+    constructor(options = {}) {
+        this.options = options;
+        const { display, onEvent, ...serializable } = options;
+        this.display = display === false ? false : typeof display === 'function' ? display : (display ?? new Console()).emit;
+        const { port1, port2 } = new MessageChannel();
+        this.port = port1;
+        // File-based workers cannot inherit the parent's eval/stdin-only switches.
+        // Preserve other runtime flags (including any Node permission configuration).
+        const execArgv = [];
+        for (let i = 0; i < process.execArgv.length; i++) {
+            const arg = process.execArgv[i];
+            if (['--input-type', '--eval', '-e', '--print', '-p'].includes(arg)) {
+                i++;
+                continue;
+            }
+            if (/^--(?:input-type|eval|print)=/.test(arg))
+                continue;
+            execArgv.push(arg);
+        }
+        this.worker = new Worker(new URL('./worker.js', import.meta.url), {
+            workerData: { port: port2, wake: this.wake.buffer }, transferList: [port2], execArgv,
+        });
+        this.worker.on('error', () => { }); // Synchronous waits have a bounded deadline for boot failures.
+        try {
+            this.request('init', serializable, undefined, 30_000);
+        }
+        catch (error) {
+            this.port.close();
+            void this.worker.terminate();
+            this.closed = true;
+            throw error;
+        }
+    }
+    run(prompt, options = {}) {
+        if (typeof prompt !== 'string' || !prompt.trim())
+            throw new TypeError('prompt must be nonempty text');
+        return this.request('run', { prompt, name: options.name,
+            jsonSchema: options.schema ? z.toJSONSchema(options.schema) : undefined }, options.schema);
+    }
+    saveCheckpoint(key, value, input) {
+        this.request('saveCheckpoint', { key, value, input });
+    }
+    loadCheckpoint(key, input) {
+        return this.request('loadCheckpoint', { key, input });
+    }
+    close() {
+        if (this.closed)
+            return;
+        try {
+            this.request('close', {}, undefined, 10_000);
+        }
+        finally {
+            this.closed = true;
+            this.port.close();
+            void this.worker.terminate();
+        }
+    }
+    [Symbol.dispose]() { this.close(); }
+    request(method, args, schema, timeoutMs) {
+        if (this.closed)
+            throw new errors.StateError('Agent is closed');
+        if (this.busy)
+            throw new errors.StateError('Do not call Agent methods from its synchronous event callback');
+        this.busy = true;
+        const id = ++this.sequence;
+        const deadline = Date.now() + (timeoutMs ?? (this.options.timeoutMs ?? 3_600_000) + 15_000);
+        let callbackError;
+        try {
+            this.port.postMessage({ id, method, args });
+            for (;;) {
+                const version = Atomics.load(this.wake, 0);
+                const received = receiveMessageOnPort(this.port);
+                if (!received) {
+                    if (Date.now() >= deadline)
+                        throw new errors.AgentTimeoutError('Agent worker did not respond; close this Agent');
+                    Atomics.wait(this.wake, 0, version, Math.min(1000, deadline - Date.now()));
+                    continue;
+                }
+                const message = received.message;
+                if (message.type === 'event') {
+                    if (message.event.kind === 'process_started')
+                        this.pid = message.event.data.pid;
+                    if (message.event.kind === 'session_started')
+                        this.sessionId = message.event.text;
+                    // Drain the current operation even if a presentation callback throws.
+                    try {
+                        if (this.display)
+                            this.display(message.event);
+                        this.options.onEvent?.(message.event);
+                    }
+                    catch (error) {
+                        callbackError ??= error;
+                    }
+                }
+                else if (message.type === 'validate') {
+                    let value;
+                    try {
+                        const result = schema.safeParse(message.data);
+                        value = result.success ? { success: true, data: result.data } : { success: false, issues: result.error.issues };
+                    }
+                    catch (error) {
+                        value = { success: false, issues: String(error) };
+                    }
+                    this.port.postMessage({ type: 'validation_result', id: message.id, value });
+                }
+                else if (message.type === 'result' && message.id === id) {
+                    this.pid = message.pid;
+                    this.sessionId = message.sessionId;
+                    this.runId = message.runId;
+                    if (callbackError)
+                        throw callbackError;
+                    if (message.error) {
+                        const ErrorType = errors[message.error.name] ?? errors.AgentTaskFlowError;
+                        throw new ErrorType(message.error.message);
+                    }
+                    return message.value;
+                }
+            }
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+}
+export function withAgent(options, workflow) {
+    const agent = new Agent(options);
+    try {
+        return workflow(agent);
+    }
+    finally {
+        agent.close();
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,33 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+export type Wire = Record<string, any>;
+export type Frame = {
+    kind: 'raw';
+    value: Wire;
+} | {
+    kind: 'stderr';
+    value: string;
+};
+/** One child for the lifetime of the connection; bounded stdout/stderr queue. */
+export declare class Transport {
+    child?: ChildProcessWithoutNullStreams;
+    lastActivity: number;
+    private frames;
+    private waiter?;
+    private failure?;
+    private closing;
+    private closed;
+    private closePromise?;
+    private exited?;
+    private tail;
+    private guardian?;
+    get pid(): number | undefined;
+    start(argv: string[], cwd: string, env: NodeJS.ProcessEnv): Promise<void>;
+    private line;
+    private put;
+    fail(error: Error): void;
+    assertAlive(): void;
+    read(): Promise<Frame>;
+    send(message: Wire): Promise<void>;
+    close(): Promise<void>;
+    private shutdown;
+}

package/dist/transport.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import { AgentProcessError, ProtocolError, StateError } from './errors.js';
+const MAX_LINE = 16 * 1024 * 1024;
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/** One child for the lifetime of the connection; bounded stdout/stderr queue. */
+export class Transport {
+    child;
+    lastActivity = Date.now();
+    frames = [];
+    waiter;
+    failure;
+    closing = false;
+    closed = false;
+    closePromise;
+    exited;
+    tail = '';
+    guardian;
+    get pid() { return this.child?.pid; }
+    async start(argv, cwd, env) {
+        if (this.child || this.closed) {
+            this.assertAlive();
+            return;
+        }
+        const child = this.child = spawn(argv[0], argv.slice(1), {
+            cwd, env, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.exited = new Promise(resolve => child.once('close', () => resolve()));
+        child.once('error', error => this.fail(new AgentProcessError(`Could not start ${argv[0]}: ${error.message}`)));
+        child.once('exit', (code, signal) => {
+            if (!this.closing)
+                this.fail(new AgentProcessError(`Persistent CLI exited (code=${code}, signal=${signal}); no automatic restart\n${this.tail}`));
+        });
+        let buffer = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            this.lastActivity = Date.now();
+            if (this.closing || this.failure)
+                return;
+            buffer += chunk;
+            try {
+                let index;
+                while ((index = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.slice(0, index);
+                    buffer = buffer.slice(index + 1);
+                    this.line(line);
+                }
+                if (Buffer.byteLength(buffer) > MAX_LINE)
+                    throw new ProtocolError('Host event exceeds 16 MiB');
+            }
+            catch (error) {
+                this.fail(error instanceof Error ? error : new ProtocolError(String(error)));
+            }
+        });
+        child.stdout.once('end', () => {
+            if (this.closing)
+                return;
+            try {
+                if (buffer.trim())
+                    this.line(buffer);
+            }
+            catch (error) {
+                this.fail(error);
+            }
+            this.fail(new AgentProcessError('Persistent CLI closed stdout; no automatic restart'));
+        });
+        child.stderr.on('data', (text) => {
+            this.lastActivity = Date.now();
+            this.tail = (this.tail + text).slice(-8192);
+            this.put({ kind: 'stderr', value: text });
+        });
+        // EPIPE is reported through send/connection failure, never an unhandled event.
+        child.stdin.on('error', error => { if (!this.closing)
+            this.fail(new AgentProcessError(error.message)); });
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+        if (process.platform !== 'win32' && child.pid) {
+            // A tiny independent watcher cleans up the detached agent group if the
+            // workflow process/worker dies (including Ctrl+C during a synchronous wait).
+            const script = `IFS= read -r target || exit 0
+case "$target" in ''|*[!0-9]*) exit 1;; esac
+cleanup() {
+  kill -TERM -- "-$target" 2>/dev/null
+  sleep 0.2
+  kill -KILL -- "-$target" 2>/dev/null
+  exit 0
+}
+trap cleanup INT TERM HUP
+IFS= read -r finished
+[ "$finished" = done ] && exit 0
+cleanup`;
+            // Stay in the workflow's foreground group so terminal Ctrl+C reaches the
+            // watcher even while the main JS thread is inside Atomics.wait().
+            this.guardian = spawn('/bin/sh', ['-c', script], { detached: false, stdio: ['pipe', 'ignore', 'ignore'] });
+            this.guardian.on('error', error => this.fail(new AgentProcessError(`Lifecycle watcher failed: ${error.message}`)));
+            this.guardian.stdin.on('error', () => { });
+            this.guardian.stdin.write(`${child.pid}\n`);
+        }
+    }
+    line(line) {
+        if (!line.trim())
+            return;
+        if (Buffer.byteLength(line) > MAX_LINE)
+            throw new ProtocolError('Host event exceeds 16 MiB');
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new ProtocolError('CLI stdout must contain JSONL; check command/provider configuration');
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new ProtocolError('Host event must be an object');
+        this.put({ kind: 'raw', value: value });
+    }
+    put(frame) {
+        if (this.closing || this.failure)
+            return;
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter.resolve(frame);
+        }
+        else
+            this.frames.push(frame);
+        if (this.frames.length >= 1024) {
+            this.child?.stdout.pause();
+            this.child?.stderr.pause();
+        }
+        // A single chunk can contain many tiny frames; reject a protocol flood rather than grow without bound.
+        if (this.frames.length > 8192)
+            this.fail(new ProtocolError('Host event queue overflow'));
+    }
+    fail(error) {
+        this.failure ??= error;
+        if (this.waiter) {
+            this.waiter.reject(this.failure);
+            this.waiter = undefined;
+        }
+    }
+    assertAlive() {
+        if (this.failure)
+            throw this.failure;
+        if (this.closing || this.closed)
+            throw new StateError('Persistent connection closed; create a new Agent explicitly');
+        if (this.child && (this.child.exitCode !== null || this.child.signalCode !== null)) {
+            throw new AgentProcessError('Persistent CLI exited; no automatic restart');
+        }
+    }
+    async read() {
+        this.assertAlive();
+        const frame = this.frames.shift();
+        if (this.frames.length < 512) {
+            this.child?.stdout.resume();
+            this.child?.stderr.resume();
+        }
+        if (frame)
+            return frame;
+        if (this.waiter)
+            throw new StateError('Only one reader may consume a connection');
+        return new Promise((resolve, reject) => { this.waiter = { resolve, reject }; });
+    }
+    async send(message) {
+        this.assertAlive();
+        if (!this.child)
+            throw new StateError('Connection not started');
+        await new Promise((resolve, reject) => this.child.stdin.write(JSON.stringify(message) + '\n', error => {
+            if (error)
+                reject(new AgentProcessError(`Host input pipe failed: ${error.message}`));
+            else
+                resolve();
+        }));
+    }
+    close() { return this.closePromise ??= this.shutdown(); }
+    async shutdown() {
+        this.closing = true;
+        this.fail(new StateError('Connection closed'));
+        this.frames.length = 0;
+        const child = this.child;
+        if (child) {
+            child.stdout.resume();
+            child.stderr.resume();
+            child.stdin.end();
+            await Promise.race([this.exited, sleep(500)]);
+            const kill = (signal) => {
+                try {
+                    if (process.platform !== 'win32' && child.pid)
+                        process.kill(-child.pid, signal);
+                    else
+                        child.kill(signal);
+                }
+                catch (error) {
+                    if (error.code !== 'ESRCH')
+                        throw error;
+                }
+            };
+            kill('SIGTERM');
+            await sleep(100);
+            kill('SIGKILL');
+            await Promise.race([this.exited, sleep(1000)]);
+            child.stdout.destroy();
+            child.stderr.destroy();
+            child.stdin.destroy();
+        }
+        this.guardian?.stdin?.end('done\n');
+        this.closed = true;
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA0D,MAAM,oBAAoB,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI3E,MAAM,QAAQ,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAClC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpF,iFAAiF;AACjF,MAAM,OAAO,SAAS;IACpB,KAAK,CAAkC;IACvC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAClB,MAAM,GAAY,EAAE,CAAC;IACrB,MAAM,CAAuE;IAC7E,OAAO,CAAS;IAChB,OAAO,GAAG,KAAK,CAAC;IAChB,MAAM,GAAG,KAAK,CAAC;IACf,YAAY,CAAiB;IAC7B,MAAM,CAAiB;IACvB,IAAI,GAAG,EAAE,CAAC;IACV,QAAQ,CAAgB;IAEhC,IAAI,GAAG,KAAyB,OAAO,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAEzD,KAAK,CAAC,KAAK,CAAC,IAAc,EAAE,GAAW,EAAE,GAAsB;QAC7D,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAAC,OAAO;QAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;YACvD,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAClF,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC3E,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QAC/G,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAClC,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,+BAA+B,IAAI,YAAY,MAAM,4BAA4B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACpJ,CAAC,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YACzC,MAAM,IAAI,KAAK,CAAC;YAChB,IAAI,CAAC;gBACH,IAAI,KAAa,CAAC;gBAClB,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;oBACpC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;oBACjC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAClB,CAAC;gBACD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ;oBAAE,MAAM,IAAI,aAAa,CAAC,2BAA2B,CAAC,CAAC;YACjG,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAC,CAAC;QACnG,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE;YAC5B,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YACzB,IAAI,CAAC;gBAAC,IAAI,MAAM,CAAC,IAAI,EAAE;oBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAAC,CAAC;YAC7C,OAAO,KAAK,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,KAAc,CAAC,CAAC;YAAC,CAAC;YAC5C,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,oDAAoD,CAAC,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YACvC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,+EAA+E;QAC/E,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1G,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;YAC9C,uEAAuE;YACvE,6EAA6E;YAC7E,MAAM,MAAM,GAAG;;;;;;;;;;;QAWb,CAAC;YACH,yEAAyE;YACzE,kEAAkE;YAClE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC3G,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,6BAA6B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;YACnH,IAAI,CAAC,QAAQ,CAAC,KAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,QAAQ,CAAC,KAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAEO,IAAI,CAAC,IAAY;QACvB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO;QACzB,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ;YAAE,MAAM,IAAI,aAAa,CAAC,2BAA2B,CAAC,CAAC;QAC7F,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QACjC,MAAM,CAAC;YAAC,MAAM,IAAI,aAAa,CAAC,qEAAqE,CAAC,CAAC;QAAC,CAAC;QACzG,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,aAAa,CAAC,8BAA8B,CAAC,CAAC;QACzH,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAa,EAAE,CAAC,CAAC;IAClD,CAAC;IAEO,GAAG,CAAC,KAAY;QACtB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAAC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAAC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;;YAC3F,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;QAC3F,uGAAuG;QACvG,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,2BAA2B,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,CAAC,KAAY;QACf,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC;QACvB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAAC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QAAC,CAAC;IACjF,CAAC;IACD,WAAW;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,CAAC,OAAO,CAAC;QACrC,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,UAAU,CAAC,6DAA6D,CAAC,CAAC;QACrH,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC,EAAE,CAAC;YACnF,MAAM,IAAI,iBAAiB,CAAC,6CAA6C,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAAC,CAAC;QAC3F,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,UAAU,CAAC,0CAA0C,CAAC,CAAC;QAClF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,OAAa;QACtB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;QAChE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE;YAC3G,IAAI,KAAK;gBAAE,MAAM,CAAC,IAAI,iBAAiB,CAAC,2BAA2B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;;gBAAM,OAAO,EAAE,CAAC;QACvG,CAAC,CAAC,CAAC,CAAC;IACN,CAAC;IACD,KAAK,KAAoB,OAAO,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChE,KAAK,CAAC,QAAQ;QACpB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YAClB,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,CAAC,MAAsB,EAAE,EAAE;gBACtC,IAAI,CAAC;oBACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,GAAG;wBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;;wBAC3E,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAAC,IAAK,KAA+B,CAAC,IAAI,KAAK,OAAO;wBAAE,MAAM,KAAK,CAAC;gBAAC,CAAC;YACzF,CAAC,CAAC;YACF,IAAI,CAAC,SAAS,CAAC,CAAC;YAChB,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,CAAC,SAAS,CAAC,CAAC;YAChB,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;CACF"}

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,55 @@
+import { workerData } from 'node:worker_threads';
+import { Agent } from './agent.js';
+const port = workerData.port;
+const wake = new Int32Array(workerData.wake);
+let agent;
+let validationCounter = 0;
+const validations = new Map();
+function post(message) {
+    port.postMessage(message);
+    Atomics.add(wake, 0, 1);
+    Atomics.notify(wake, 0);
+}
+port.on('message', async (message) => {
+    if (message.type === 'validation_result') {
+        validations.get(message.id)?.(message.value);
+        validations.delete(message.id);
+        return;
+    }
+    const { id, method, args } = message;
+    try {
+        let value;
+        if (method === 'init') {
+            agent = new Agent({ ...args, display: false, onEvent: event => post({ type: 'event', event }) });
+        }
+        else if (!agent)
+            throw new Error('Worker agent has not initialized');
+        else if (method === 'run') {
+            value = args.jsonSchema
+                ? await agent.runValidated(args.prompt, { name: args.name }, {
+                    jsonSchema: args.jsonSchema,
+                    validate: data => new Promise(resolve => {
+                        const validationId = ++validationCounter;
+                        validations.set(validationId, resolve);
+                        post({ type: 'validate', id: validationId, data });
+                    }),
+                })
+                : await agent.run(args.prompt, { name: args.name });
+        }
+        else if (method === 'saveCheckpoint')
+            agent.saveCheckpoint(args.key, args.value, args.input);
+        else if (method === 'loadCheckpoint')
+            value = agent.loadCheckpoint(args.key, args.input);
+        else if (method === 'close')
+            await agent.close();
+        else
+            throw new Error(`Unknown worker operation: ${method}`);
+        post({ type: 'result', id, value, pid: agent?.pid, sessionId: agent?.sessionId, runId: agent?.runId });
+    }
+    catch (error) {
+        post({ type: 'result', id, error: { name: error instanceof Error ? error.constructor.name : 'Error', message: String(error) },
+            pid: agent?.pid, sessionId: agent?.sessionId, runId: agent?.runId });
+    }
+});
+post({ type: 'ready' });
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AAEtD,MAAM,IAAI,GAAgB,UAAU,CAAC,IAAI,CAAC;AAC1C,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC7C,IAAI,KAAwB,CAAC;AAC7B,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAC1B,MAAM,WAAW,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE5D,SAAS,IAAI,CAAC,OAAgB;IAC5B,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC;AACD,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;IACjC,IAAI,OAAO,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;QACzC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7C,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IACD,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACrC,IAAI,CAAC;QACH,IAAI,KAAc,CAAC;QACnB,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,GAAG,IAAoB,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACnH,CAAC;aAAM,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;aAClE,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YAC1B,KAAK,GAAG,IAAI,CAAC,UAAU;gBACrB,CAAC,CAAC,MAAM,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE;oBAC3D,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE;wBACtC,MAAM,YAAY,GAAG,EAAE,iBAAiB,CAAC;wBACzC,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;wBACvC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;oBACrD,CAAC,CAAC;iBACH,CAAC;gBACF,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;aAAM,IAAI,MAAM,KAAK,gBAAgB;YAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;aAC1F,IAAI,MAAM,KAAK,gBAAgB;YAAE,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;aACpF,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;;YAC5C,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACzG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE;YAC3H,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC,CAAC,CAAC;AACH,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC"}

package/docs/validation.md

@@ -0,0 +1,27 @@
+# TypeScript 版验证记录
+
+验证日期：2026-09-26，macOS arm64，Node.js 22.19.0。
+
+- TypeScript 构建及源码、示例、测试类型检查通过。
+- 命令行回归测试 38 项全部通过。协议测试使用独立假 CLI，覆盖 Codex/Claude 常驻进程、多轮上下文、格式补答、失败不重放、超时、流式输出、恢复、运行锁和进程清理。
+- 简洁 `flow` API 验证了普通 for/if、check、choose、自动步骤名称；五次提示词共用一个进程。
+- 默认同步 API 的真实 Codex smoke 通过：命令 cxh，记忆标记加两轮回忆，共三步，PID 始终为 16517。运行 ID：a892f8a1-954a-4694-bfdf-efab260e58f8。
+- 默认同步 API 的真实 Claude Code smoke 通过：记忆标记加两轮回忆，共三步，PID 始终为 15684。运行 ID：d591ad33-3424-4ad3-b0eb-84f70b216f4c。
+
+真实 smoke 验证的是同步执行基础层；简洁 flow 包装层的分支使用假 CLI 验证。上述测试不证明模型能够可靠完成任意业务流程，也不保证无限上下文。Windows 未验证。
+
+复现自动检查：
+
+```bash
+nvm use
+npm run build
+npm run check
+npm test
+```
+
+真实 CLI 测试需要已配置的命令及模型访问：
+
+```bash
+npm run smoke -- --provider codex --command cxh --rounds 2
+npm run smoke -- --provider claude --command claude --rounds 2
+```