@jigging/agent-method 0.0.0 → 0.1.0-alpha.3

package/dist/conversation.js

@@ -0,0 +1,346 @@
+import { exactKeys, ordinaryRecord, validSessionReceipt } from './values.js';
+/** Retains received answers and every primary/cleanup failure; never manufactures success. */
+export class AgentConversationError extends AggregateError {
+    turns;
+    settlement;
+    constructor(errors, turns, settlement) {
+        super(errors, 'Agent conversation did not complete cleanly', { cause: errors[0] });
+        this.turns = turns;
+        this.settlement = settlement;
+        this.name = 'AgentConversationError';
+    }
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => {
+        resolve = yes;
+        reject = no;
+    });
+    // A caller may inspect another part of a turn first. Rejections are still
+    // returned to every waiter; this is not a global failure acknowledgement ledger.
+    void promise.catch(() => undefined);
+    return { promise, resolve, reject };
+}
+function invalid(message) {
+    return new Error(message);
+}
+/** Ordinary Agent Run caller logic: no ACP implementation, host imports, or provider access. */
+export async function withAgentConversation(run, options, use) {
+    if (options.events && options.onEvent)
+        throw new TypeError('Choose onEvent or an external events writer, not both');
+    const requestedSession = options.input.session !== undefined;
+    const turns = [];
+    const errors = [];
+    const record = (error) => {
+        if (!errors.includes(error))
+            errors.push(error);
+    };
+    const reads = new AbortController();
+    const pending = new Set();
+    const tracked = () => {
+        const value = deferred();
+        pending.add(value);
+        void value.promise.then(() => pending.delete(value), () => pending.delete(value));
+        return value;
+    };
+    const fail = (error) => {
+        record(error);
+        reads.abort(error);
+        for (const value of pending)
+            value.reject(error);
+    };
+    let commands;
+    let replies;
+    let events;
+    let observer;
+    const observerStop = new AbortController();
+    const observationErrors = [];
+    let offered = false;
+    let work;
+    let pump;
+    let settlement;
+    let writerClosed = false;
+    let value;
+    let active = true;
+    let current = { turn: 0, result: tracked() };
+    let promptControl;
+    let interruptControl;
+    let closeControl;
+    let controls = 0;
+    let finished = false;
+    const send = async (message) => {
+        if (++controls > 64)
+            throw invalid('Conversation control limit is 64 commands');
+        await commands.send.send(message, { signal: run.signal });
+    };
+    try {
+        commands = await run.channel({
+            contract: { slot: options.slot, channel: 'commands' },
+        });
+        replies = await run.channel({
+            contract: { slot: options.slot, channel: 'replies' },
+        });
+        if (options.onEvent) {
+            events = await run.channel({
+                contract: { slot: options.slot, channel: 'events' },
+            });
+        }
+        offered = true;
+        // Do not cancel this local waiter to stop a conversation. Its real terminal
+        // is the evidence that lets a healthy parent subsequently use the capacity.
+        work = run
+            .call({
+            operationId: options.operationId,
+            slot: options.slot,
+            input: { ...options.input, conversation: true },
+            channels: {
+                commands: commands.receive,
+                replies: replies.send,
+                ...(events ? { events: events.send } : options.events ? { events: options.events } : {}),
+            },
+        })
+            .then((result) => ({ result }), (error) => {
+            fail(error);
+            observerStop.abort(error);
+            return { error };
+        });
+        if (events) {
+            observer = (async () => {
+                try {
+                    for (;;) {
+                        const item = await events.receive.next({
+                            signal: AbortSignal.any([run.signal, observerStop.signal]),
+                        });
+                        if (item.done)
+                            break;
+                        const returned = options.onEvent(item.value);
+                        if (returned && typeof returned.then === 'function') {
+                            void Promise.resolve(returned).catch(() => undefined);
+                            throw new TypeError('onEvent must be synchronous; use events for asynchronous channel processing');
+                        }
+                    }
+                }
+                catch (error) {
+                    observationErrors.push(error);
+                }
+                finally {
+                    try {
+                        await events.receive.close();
+                    }
+                    catch (error) {
+                        if (!observationErrors.includes(error))
+                            observationErrors.push(error);
+                    }
+                }
+            })();
+        }
+        pump = (async () => {
+            try {
+                for (;;) {
+                    const item = await replies.receive.next({
+                        signal: AbortSignal.any([run.signal, reads.signal]),
+                    });
+                    if (item.done)
+                        throw invalid('Agent replies ended before accepted conversation close');
+                    const message = item.value;
+                    if (!message ||
+                        Array.isArray(message) ||
+                        typeof message !== 'object' ||
+                        message.turn !== current.turn)
+                        throw invalid('Agent reply has an unexpected turn');
+                    if (message.type === 'accepted' || message.type === 'rejected') {
+                        if (message.command === 'prompt' && promptControl) {
+                            const control = promptControl;
+                            promptControl = undefined;
+                            if (message.type === 'accepted')
+                                control.accepted.resolve();
+                            else {
+                                const error = invalid(`Agent rejected prompt: ${String(message.code)}`);
+                                current.result.reject(error);
+                                current = control.previous;
+                                active = false;
+                                control.accepted.reject(error);
+                            }
+                        }
+                        else if (message.command === 'interrupt' && interruptControl) {
+                            const control = interruptControl;
+                            interruptControl = undefined;
+                            if (message.type === 'accepted')
+                                control.resolve('accepted');
+                            else if (message.code === 'NOT_RUNNING')
+                                control.resolve('not-running');
+                            else
+                                control.reject(invalid(`Agent rejected interruption: ${String(message.code)}`));
+                        }
+                        else if (message.command === 'close' && closeControl) {
+                            if (message.type !== 'accepted')
+                                throw invalid('Agent rejected conversation close');
+                            closeControl.resolve();
+                            return;
+                        }
+                        else
+                            throw invalid('Agent sent an unexpected control reply');
+                    }
+                    else {
+                        if (!active || promptControl)
+                            throw invalid('Agent sent an out-of-order turn result');
+                        if (message.type === 'result') {
+                            const result = message.result;
+                            if (!result || typeof result.outcome !== 'string' || !Object.hasOwn(result, 'output'))
+                                throw invalid('Agent omitted its complete turn result');
+                        }
+                        else if (message.type !== 'cancelled' &&
+                            !(message.type === 'error' &&
+                                message.code === 'INVALID_RESULT' &&
+                                typeof message.message === 'string'))
+                            throw invalid('Agent sent an invalid turn terminal');
+                        const turn = item.value;
+                        if (turns.length >= 8)
+                            throw invalid('Agent exceeded the eight-turn conversation limit');
+                        turns.push(turn);
+                        active = false;
+                        current.result.resolve(turn);
+                    }
+                }
+            }
+            catch (error) {
+                if (!reads.signal.aborted)
+                    fail(error);
+            }
+        })();
+        const conversation = {
+            initial: current.result.promise,
+            prompt(input) {
+                if (finished || active || interruptControl || errors.length)
+                    return Promise.reject(invalid('Conversation is not ready for another prompt'));
+                if (current.turn >= 7)
+                    return Promise.reject(invalid('Conversation turn limit reached'));
+                const previous = current;
+                current = { turn: previous.turn + 1, result: tracked() };
+                const result = current.result.promise;
+                active = true;
+                promptControl = { accepted: tracked(), previous };
+                void send({
+                    type: 'prompt',
+                    turn: current.turn,
+                    input: input,
+                }).catch(fail);
+                return result;
+            },
+            async interrupt() {
+                if (finished || errors.length)
+                    throw invalid('Conversation is closing or failed');
+                if (promptControl)
+                    await promptControl.accepted.promise;
+                if (!active)
+                    return 'not-running';
+                if (interruptControl)
+                    return interruptControl.promise;
+                const control = tracked();
+                interruptControl = control;
+                void send({ type: 'interrupt', turn: current.turn }).catch(fail);
+                return control.promise;
+            },
+        };
+        try {
+            value = await use(conversation);
+        }
+        catch (error) {
+            record(error);
+        }
+        finished = true;
+        if (active)
+            record(invalid('Application left a live Agent turn unfinished'));
+        if (!active && !reads.signal.aborted && !run.signal.aborted) {
+            if (interruptControl)
+                await interruptControl.promise;
+            closeControl = tracked();
+            await send({ type: 'close', turn: current.turn });
+            await commands.send.close({ signal: run.signal });
+            writerClosed = true;
+            await closeControl.promise;
+        }
+    }
+    catch (error) {
+        record(error);
+    }
+    finally {
+        finished = true;
+        // A failed callback/transport stops delivery to the Agent through ordinary
+        // channel closure, while preserving the non-cancelled invocation waiter.
+        if (commands && !writerClosed) {
+            try {
+                await commands.send.close({ error: 'LAGGED', signal: run.signal });
+            }
+            catch (error) {
+                record(error);
+            }
+        }
+        reads.abort();
+        await pump;
+        if (work) {
+            const terminal = await work;
+            if ('error' in terminal)
+                record(terminal.error);
+            else
+                settlement = terminal.result;
+        }
+        await observer;
+        if (events && !offered) {
+            try {
+                await events.send.close({ error: 'LAGGED', signal: run.signal });
+            }
+            catch (error) {
+                record(error);
+            }
+            try {
+                await events.receive.close();
+            }
+            catch (error) {
+                record(error);
+            }
+        }
+        if (replies) {
+            try {
+                await replies.receive.close();
+            }
+            catch (error) {
+                record(error);
+            }
+        }
+        // An allocated receiver that was never offered is still ours.
+        if (commands && !offered) {
+            try {
+                await commands.receive.close();
+            }
+            catch (error) {
+                record(error);
+            }
+        }
+    }
+    if (run.signal.aborted)
+        record(run.signal.reason ?? invalid('Run cancelled'));
+    const output = ordinaryRecord(settlement?.output);
+    if (!settlement ||
+        settlement.outcome !== 'done' ||
+        !output ||
+        output.turns !== turns.length ||
+        !exactKeys(output, ['turns', ...(requestedSession ? ['session'] : [])]) ||
+        (requestedSession && !validSessionReceipt(output.session)))
+        record(invalid('Agent omitted matching conversation settlement'));
+    if (errors.length)
+        throw new AgentConversationError(errors, Object.freeze(turns), settlement);
+    return {
+        value,
+        turns: Object.freeze(turns),
+        settlement: settlement,
+        ...(options.onEvent
+            ? {
+                observation: observationErrors.length
+                    ? { status: 'incomplete', errors: Object.freeze(observationErrors) }
+                    : { status: 'complete' },
+            }
+            : {}),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export type AgentMethodErrorCode = 'INVALID_INPUT' | 'RESOURCE_EXHAUSTED' | 'INVALID_RESULT';
+export declare class AgentMethodError extends Error {
+    readonly code: AgentMethodErrorCode;
+    constructor(code: AgentMethodErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class AgentMethodError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentMethodError';
+    }
+}

package/dist/flow.d.ts

@@ -0,0 +1,3 @@
+import { type RunContext, type RunResult } from '@jigging/flow';
+export declare function agentFlow(run: RunContext): Promise<RunResult>;
+export declare function runAgentFlow(): Promise<void>;