@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/engine/runner/step-order.js

@@ -0,0 +1,165 @@
+import { throwIfAborted } from '../../../guardrails/error.js';
+/**
+ * A promise and the function that settles it. `Promise.withResolvers` would do, but the React
+ * package compiles the kernel against ES2023, which lacks it.
+ */
+function settleable() {
+    let resolve = () => undefined;
+    const promise = new Promise((settle) => {
+        resolve = settle;
+    });
+    return { promise, resolve };
+}
+/**
+ * The order of a step's calls. Side by side, every call starts at once. One at a time,
+ * each starts when every call before it has settled. A call whose `pre_tool` answers `waitFor`
+ * is held until those calls settle. A wait on a call outside the step fails; so does a wait
+ * that can never end, because the call waited for waits for this one or runs after it. Every
+ * call whose own wait closes such a loop fails.
+ */
+export function stepOrder(callIds, parallel, signal) {
+    const settled = new Set();
+    const done = new Map(callIds.map((id) => [id, settleable()]));
+    const waits = new Map();
+    const held = new Map();
+    const unhook = new Map();
+    const earlier = (callId) => (parallel ? [] : callIds.slice(0, callIds.indexOf(callId)));
+    for (const id of callIds) {
+        const before = earlier(id);
+        if (before.length > 0)
+            waits.set(id, new Map(before.map((target) => [target, 'after'])));
+    }
+    /** The calls from `from` to `to` along unsettled waits, or `undefined` when none leads there. */
+    const pathTo = (from, to, seen = new Set()) => {
+        if (from === to)
+            return [to];
+        if (seen.has(from) || settled.has(from))
+            return undefined;
+        seen.add(from);
+        for (const next of waits.get(from)?.keys() ?? []) {
+            const rest = pathTo(next, to, seen);
+            if (rest)
+                return [from, ...rest];
+        }
+        return undefined;
+    };
+    const release = (id, outcome) => {
+        held.get(id)?.(outcome);
+        held.delete(id);
+        unhook.get(id)?.();
+        unhook.delete(id);
+        for (const [target, kind] of waits.get(id) ?? []) {
+            if (kind === 'asked')
+                waits.get(id)?.delete(target);
+        }
+    };
+    const doneOf = (id) => done.get(id)?.promise ?? Promise.resolve();
+    return {
+        start: async (callId) => {
+            await Promise.all(earlier(callId).map(doneOf));
+            throwIfAborted(signal);
+        },
+        settle: (callId) => {
+            settled.add(callId);
+            waits.delete(callId);
+            done.get(callId)?.resolve();
+        },
+        wait: (callId, waitFor) => {
+            const unknown = waitFor.filter((id) => !done.has(id));
+            if (unknown.length > 0) {
+                return Promise.resolve({ ok: false, reason: 'unknown', callIds: unknown });
+            }
+            const pending = waitFor.filter((id) => !settled.has(id));
+            if (pending.length === 0)
+                return Promise.resolve({ ok: true });
+            const own = waits.get(callId) ?? new Map();
+            waits.set(callId, own);
+            for (const id of pending)
+                own.set(id, 'asked');
+            const loops = pending.flatMap((id) => {
+                const path = pathTo(id, callId);
+                return path ? [{ id, path }] : [];
+            });
+            if (loops.length > 0) {
+                // why: Every call whose own wait is part of the loop is held for nothing that can come; each fails.
+                for (const { path } of loops) {
+                    for (const [index, id] of path.entries()) {
+                        const next = path[index + 1];
+                        if (next !== undefined && id !== callId && waits.get(id)?.get(next) === 'asked') {
+                            release(id, { ok: false, reason: 'cycle', callIds: [next] });
+                        }
+                    }
+                }
+                release(callId, { ok: false, reason: 'cycle', callIds: loops.map(({ id }) => id) });
+                return Promise.resolve({
+                    ok: false,
+                    reason: 'cycle',
+                    callIds: loops.map(({ id }) => id),
+                });
+            }
+            const outcome = settleable();
+            held.set(callId, outcome.resolve);
+            Promise.all(pending.map(doneOf)).then(() => release(callId, { ok: true }));
+            const aborted = new Promise((_, reject) => {
+                if (!signal)
+                    return;
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener('abort', onAbort, { once: true });
+                unhook.set(callId, () => signal.removeEventListener('abort', onAbort));
+            });
+            // why: An aborted turn ends the wait with the abort; the call settles as aborted.
+            aborted.catch(() => { });
+            return Promise.race([outcome.promise, aborted]);
+        },
+    };
+}
+/** Runs a call's body once the step lets it start, and settles it however the body ends. */
+export async function* inStep(order, callId, body) {
+    try {
+        await order.start(callId);
+        return yield* body();
+    }
+    finally {
+        order.settle(callId);
+    }
+}
+/**
+ * Runs tools side by side and passes on each event as it comes. Returns each run's
+ * settlement by its place in `runs`, `undefined` where there was no run.
+ *
+ * why: One run that throws ends them all; the rest are closed so none keeps running unseen.
+ */
+export async function* runSideBySide(runs) {
+    const settled = runs.map(() => undefined);
+    const waiting = new Map();
+    const pull = (index, run) => {
+        const next = run.next().then((result) => ({ index, next: result }));
+        // why: A run that fails after another already threw is closed below; its failure has nowhere to go.
+        next.catch(() => { });
+        waiting.set(index, next);
+    };
+    runs.forEach((run, index) => {
+        if (run)
+            pull(index, run);
+    });
+    try {
+        while (waiting.size > 0) {
+            const { index, next } = await Promise.race(waiting.values());
+            waiting.delete(index);
+            const run = runs[index];
+            if (next.done || !run) {
+                if (next.done)
+                    settled[index] = next.value;
+                continue;
+            }
+            yield next.value;
+            pull(index, run);
+        }
+    }
+    finally {
+        for (const index of waiting.keys()) {
+            runs[index]?.return(undefined).catch(() => { });
+        }
+    }
+    return settled;
+}

package/esm/src/kernel/engine/runner/steps.d.ts

@@ -0,0 +1,14 @@
+import type { BoundSystem } from '../../system-parts.js';
+import type { Profile, ResolvedGeneration, TurnEvent, TurnModel, TurnRequest } from '../../types.js';
+import { type StepExecutionState } from './state.js';
+declare function executeAttempt(args: {
+    safe: TurnRequest;
+    profile: Profile;
+    generation: ResolvedGeneration;
+    system: BoundSystem;
+    provider: TurnModel;
+    state: StepExecutionState;
+}): AsyncGenerator<TurnEvent, {
+    latestStructured?: unknown;
+}>;
+export { executeAttempt };