bunqueue 2.8.46 → 2.8.47

package/dist/client/workflow/waitFor.js

@@ -0,0 +1,137 @@
+/**
+ * waitFor node execution — parking a run for a human/external signal, and the
+ * timeout timers that bound the wait.
+ *
+ * Split out of the executor because parking is the one node type with a genuinely
+ * concurrent counterpart: `signal()` mutates the same row from outside the worker,
+ * so every transition here has to be expressed as a claim against the store rather
+ * than an in-memory state change. See storeSignals.ts for the ownership rules.
+ */
+import { WaitForSignalError } from './compensator';
+import { hasSignal } from './storeSignals';
+import { clock } from './clock';
+/** Largest delay setTimeout accepts before wrapping (2**31-1 ms, ~24.8 days) */
+export const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * Arm the timer that re-enters a parked node once its wait budget elapses.
+ *
+ * setTimeout takes a 32-bit signed delay; anything larger wraps to 1ms and fires
+ * immediately (`TimeoutOverflowWarning`). Clamping and letting the re-check job
+ * re-arm for whatever remains is what makes multi-week approval windows survive
+ * (test/repro-workflow-timeout-overflow.test.ts).
+ */
+export function scheduleTimeoutCheck(deps, execId, workflowName, nodeIdx, ms) {
+    const delay = Math.min(Math.max(ms, 0), MAX_TIMER_MS);
+    // Replacing a live timer for the same execution — re-entering a waitFor node used
+    // to leak the previous one, which then fired against a node the run had left.
+    const previous = deps.timers.get(execId);
+    if (previous)
+        clock().clearTimeout(previous);
+    const timer = clock().setTimeout(() => {
+        deps.timers.delete(execId);
+        const jobData = { executionId: execId, workflowName, nodeIndex: nodeIdx };
+        deps.queue.add('wf:step', jobData).catch(() => {
+            /* Queue may be closed */
+        });
+    }, delay);
+    // A parked approval gate is a NORMAL steady state, and the clamp above makes this
+    // timer up to ~24.8 days long. Without unref a process whose only remaining work is
+    // a parked run never exits, even after close(): the event loop stays alive holding a
+    // timer for a signal that may never come. unref keeps the timer fully functional
+    // while the process has other work, and stops it from being the reason to stay up.
+    // `clearTimers()` covers the explicit-shutdown path. This does NOT, on its own, let
+    // a parked engine's process exit: measured, a child that omits `close()` hangs with
+    // or without this line, because the embedded queue and worker pin the process
+    // independently. It is defence in depth for the timer itself, no more, and the
+    // earlier version of this comment claimed the stronger property.
+    timer.unref?.();
+    deps.timers.set(execId, timer);
+}
+/**
+ * Cancel every armed wait timer. Called on engine shutdown: `unref` alone lets a
+ * process exit, but a still-armed timer can also fire into a queue that is closing,
+ * and a caller that shuts one engine down while keeping the process alive has no
+ * other way to release them.
+ */
+export function clearTimers(timers) {
+    for (const timer of timers.values())
+        clock().clearTimeout(timer);
+    timers.clear();
+}
+/**
+ * Execute a `waitFor` node: advance if the signal is already there, fail if the wait
+ * has expired, otherwise park the run and throw the sentinel so processStep
+ * short-circuits without treating the pause as an error.
+ */
+export async function runWaitFor(deps, exec, node, idx, wf) {
+    if (hasSignal(exec.signals, node.event)) {
+        await deps.advance(exec, idx + 1, wf);
+        return;
+    }
+    const waitKey = `__waitFor:${node.event}`;
+    let remaining = 0;
+    if (node.timeout !== undefined) {
+        const existing = exec.steps[waitKey];
+        const waitingSince = existing?.startedAt ?? clock().now();
+        if (!existing)
+            exec.steps[waitKey] = { status: 'running', startedAt: waitingSince };
+        if (clock().now() - waitingSince >= node.timeout) {
+            // Re-read before failing: a signal delivered while this node was executing is
+            // not in our snapshot, and expiring an already-approved run would compensate
+            // (refund, release stock) work the approver just authorised.
+            const fresh = deps.store.get(exec.id);
+            if (fresh && hasSignal(fresh.signals, node.event)) {
+                exec.signals = fresh.signals;
+                await deps.advance(exec, idx + 1, wf);
+                return;
+            }
+            deps.emitter?.emitSignal('signal:timeout', exec.id, exec.workflowName, node.event);
+            exec.steps[waitKey] = {
+                status: 'failed',
+                startedAt: waitingSince,
+                completedAt: clock().now(),
+                error: `Signal "${node.event}" timed out after ${node.timeout}ms`,
+            };
+            exec.state = 'failed';
+            // Unguarded on purpose, same reasoning as the failure write in `executor.ts`. Disk
+            // still says `waiting`, which `listRecoverable()` covers, so `recoverWaiting`
+            // recomputes the remaining time, re-enqueues, and the gate times out again rather
+            // than leaving a run that looks settled and was never unwound.
+            //
+            // A throw here skips the compensate CALL below but not the compensation: it
+            // propagates into `runNode`'s catch, which compensates anyway. That is the generic
+            // path the `WaitForSignalError` sentinel below exists to avoid on the normal route,
+            // so the outcome is a redundant route, not a missing rollback.
+            deps.store.update(exec);
+            // Compensate here, then signal completion via the WaitForSignalError sentinel
+            // so processStep short-circuits (return null) instead of re-running
+            // compensation through its generic catch path.
+            await deps.compensate(exec, wf);
+            deps.emitter?.emitWorkflow('workflow:failed', exec.id, exec.workflowName, 'failed');
+            throw new WaitForSignalError(node.event);
+        }
+        deps.store.update(exec);
+        remaining = node.timeout - (clock().now() - waitingSince);
+    }
+    // Park transactionally. Between the in-memory check above and this point a signal
+    // can land: it would be recorded with no parked run left to claim the resume,
+    // hanging the execution forever. parkForSignal() re-reads the persisted signals
+    // and only transitions 'running' -> 'waiting' when none has arrived.
+    const park = deps.store.parkForSignal(exec.id, node.event);
+    if (park.signalPresent) {
+        exec.signals = park.signals;
+        await deps.advance(exec, idx + 1, wf);
+        return;
+    }
+    if (!park.parked) {
+        // Another job already moved this execution off 'running'; don't advance or emit
+        // a second waiting event for the same node.
+        throw new WaitForSignalError(node.event);
+    }
+    exec.state = 'waiting';
+    if (node.timeout !== undefined) {
+        deps.scheduleTimeoutCheck(exec.id, exec.workflowName, idx, remaining);
+    }
+    deps.emitter?.emitWorkflow('workflow:waiting', exec.id, exec.workflowName, 'waiting');
+    throw new WaitForSignalError(node.event);
+}

package/dist/client/workflow/workflow.d.ts

@@ -6,12 +6,68 @@
  * so subsequent steps can access previous results without casting.
  */
 import type { WorkflowNode, StepOptions, StepContext, BranchCondition, LoopCondition, ForEachItemsExtractor, TypedStepHandler } from './types';
+/**
+ * Reject a workflow whose step names collide with the `name:index` namespace a loop
+ * reserves for its iterations.
+ *
+ * A step literally called `process:0` next to a forEach called `process` is a real
+ * collision, and both possible silent outcomes are corruption: the loop overwrites
+ * the user's step, or — once iterations are memoised — the loop mistakes the user's
+ * record for its own completed work and skips the iteration entirely. Neither can be
+ * detected at runtime, so it has to be refused at registration.
+ */
+/**
+ * Two `waitFor` nodes on the SAME event cannot both gate.
+ *
+ * `exec.signals` is a permanent record keyed by event name and a wait is satisfied by
+ * the key being present, so nothing marks a signal as consumed and nothing ties a
+ * delivery to the gate that was waiting for it. A run shaped `waitFor('approve')`,
+ * pay, `waitFor('approve')` is therefore walked end to end by ONE
+ * `signal(id, 'approve')`: the second gate never pauses, because the key is already
+ * there. A four-eyes control silently degrades to a one-eye control, and no state,
+ * event or log records that a gate was skipped
+ * (`test/repro-workflow-gate-and-schema.test.ts`).
+ *
+ * Refused at registration rather than fixed at runtime: consuming the signal would
+ * change what `ctx.signals` means for every workflow already written, and a
+ * build-time error cannot be missed, while a runtime one shows up when the money is
+ * already moving. Distinct event names per gate are the correct shape and cost
+ * nothing.
+ */
+/**
+ * Why an event name cannot be used as a gate, or `null` if it can.
+ *
+ * `__proto__` is refused because assignment to that name writes an object's PROTOTYPE
+ * instead of creating an own key, so `SignalCoordinator.record()` stored the payload
+ * nowhere: the gate never saw its own signal, re-parked, expired, and the unwind
+ * reversed work the approver had authorised
+ * (`test/repro-workflow-proto-gate-signal.test.ts`). Making it work instead would mean
+ * reconciling the storage codec, which deliberately renames `__proto__` to `__proto_`
+ * as its own pollution defence, so the gate would be stored under a different name
+ * than it was signalled with. A gate with two spellings is not a gate.
+ *
+ * An empty or non-string name is refused for the plainer reason that nobody can
+ * signal it, and two of them would be opened by one signal.
+ */
+export declare function unusableEventName(event: unknown): string | null;
+export declare function assertNoDuplicateWaitFor(wf: {
+    name: string;
+    nodes: readonly {
+        type: string;
+        event?: string;
+    }[];
+}): void;
+export declare function assertNoIndexCollision(wf: {
+    name: string;
+    getStepNames(): string[];
+    getIndexedStepNames(): string[];
+}): void;
 export declare class Workflow<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
     readonly name: string;
     readonly nodes: WorkflowNode[];
     constructor(name: string);
     /** Add a step to the workflow — return type accumulates into TSteps */
-    step<TName extends string, TResult>(name: TName, handler: TypedStepHandler<TInput, TSteps, TResult>, options?: StepOptions<TInput, TSteps>): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
+    step<TName extends string, TResult>(name: TName, handler: TypedStepHandler<TInput, TSteps, TResult>, options?: StepOptions<TInput, TSteps & Record<TName, Awaited<TResult>>>): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
     /** Add a branch point — call .path() after this to define paths */
     branch(condition: BranchCondition<TInput, TSteps>): this;
     /** Define a branch path (must follow a .branch() call) */
@@ -38,6 +94,20 @@ export declare class Workflow<TInput = unknown, TSteps extends Record<string, un
     }): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
     /** Transform step results into a new value stored under the given name */
     map<TName extends string, TResult>(name: TName, transform: (ctx: StepContext<TInput, TSteps>) => TResult): Workflow<TInput, TSteps & Record<TName, Awaited<TResult>>>;
+    /**
+     * Mark the point of no return.
+     *
+     * Everything before it stays compensatable; everything after is committed and is
+     * never rolled back, however the run ends. Past the pivot the only correct
+     * recovery is forward — retry, alert, fix — because there is no semantic inverse
+     * for "the welcome email was sent". Declare it explicitly; it is never inferred.
+     */
+    pivot(): this;
+    /**
+     * Step names that generate indexed per-iteration records (`name:0`, `name:1`, ...).
+     * Loop bodies and forEach steps both do; a plain step never does.
+     */
+    getIndexedStepNames(): string[];
     /** Get flat list of step names for validation */
     getStepNames(): string[];
 }

package/dist/client/workflow/workflow.js

@@ -5,6 +5,147 @@
  * Supports type-safe step chaining: each .step() narrows the return type
  * so subsequent steps can access previous results without casting.
  */
+/**
+ * Extract the step definitions from a sub-builder, refusing anything else.
+ *
+ * Branch paths, parallel groups and loop bodies all execute inline inside a single
+ * `wf:step` job, so they can only host plain steps — a `waitFor` there has no node
+ * index to park at, a nested `branch` has no dispatcher. These used to be filtered
+ * out silently, which turned an approval gate written inside a path into a no-op the
+ * run sailed straight through (test/repro-workflow-guide-claims.test.ts). Failing at
+ * build time is the only safe answer: the alternative is skipping a human approval
+ * and reporting success.
+ */
+function onlySteps(sub, where, label) {
+    const rejected = sub.nodes.filter((n) => n.type !== 'step');
+    if (rejected.length > 0) {
+        const kinds = [...new Set(rejected.map((n) => n.type))].join(', ');
+        const which = label ? ` (path "${label}")` : '';
+        throw new Error(`${where} accepts step() nodes only${which}, but received: ${kinds}. ` +
+            `Move those nodes to the top level of the workflow, or extract them into a ` +
+            `separate workflow and call it with subWorkflow().`);
+    }
+    return sub.nodes
+        .filter((n) => n.type === 'step')
+        .map((n) => n.def);
+}
+/**
+ * Reject a workflow whose step names collide with the `name:index` namespace a loop
+ * reserves for its iterations.
+ *
+ * A step literally called `process:0` next to a forEach called `process` is a real
+ * collision, and both possible silent outcomes are corruption: the loop overwrites
+ * the user's step, or — once iterations are memoised — the loop mistakes the user's
+ * record for its own completed work and skips the iteration entirely. Neither can be
+ * detected at runtime, so it has to be refused at registration.
+ */
+/**
+ * Two `waitFor` nodes on the SAME event cannot both gate.
+ *
+ * `exec.signals` is a permanent record keyed by event name and a wait is satisfied by
+ * the key being present, so nothing marks a signal as consumed and nothing ties a
+ * delivery to the gate that was waiting for it. A run shaped `waitFor('approve')`,
+ * pay, `waitFor('approve')` is therefore walked end to end by ONE
+ * `signal(id, 'approve')`: the second gate never pauses, because the key is already
+ * there. A four-eyes control silently degrades to a one-eye control, and no state,
+ * event or log records that a gate was skipped
+ * (`test/repro-workflow-gate-and-schema.test.ts`).
+ *
+ * Refused at registration rather than fixed at runtime: consuming the signal would
+ * change what `ctx.signals` means for every workflow already written, and a
+ * build-time error cannot be missed, while a runtime one shows up when the money is
+ * already moving. Distinct event names per gate are the correct shape and cost
+ * nothing.
+ */
+/**
+ * Why an event name cannot be used as a gate, or `null` if it can.
+ *
+ * `__proto__` is refused because assignment to that name writes an object's PROTOTYPE
+ * instead of creating an own key, so `SignalCoordinator.record()` stored the payload
+ * nowhere: the gate never saw its own signal, re-parked, expired, and the unwind
+ * reversed work the approver had authorised
+ * (`test/repro-workflow-proto-gate-signal.test.ts`). Making it work instead would mean
+ * reconciling the storage codec, which deliberately renames `__proto__` to `__proto_`
+ * as its own pollution defence, so the gate would be stored under a different name
+ * than it was signalled with. A gate with two spellings is not a gate.
+ *
+ * An empty or non-string name is refused for the plainer reason that nobody can
+ * signal it, and two of them would be opened by one signal.
+ */
+export function unusableEventName(event) {
+    if (typeof event !== 'string' || event.length === 0)
+        return 'with no event name';
+    if (event === '__proto__') {
+        return 'named "__proto__", which cannot be stored as a signal key and would never receive its signal';
+    }
+    return null;
+}
+export function assertNoDuplicateWaitFor(wf) {
+    const seen = new Set();
+    for (const node of wf.nodes) {
+        if (node.type !== 'waitFor')
+            continue;
+        // Skipping a nameless gate here would reopen the very bypass this function
+        // exists to close: two `waitFor(undefined)` nodes registered cleanly and one
+        // `signal(id, undefined)` walked both. Not theoretical either, since
+        // `noUncheckedIndexedAccess` is off: `.waitFor(gates.manager)` on a
+        // `Record<string, string>` with a missing key types as `string`, is `undefined` at
+        // runtime, and compiles. A gate nobody can name is a gate nobody can open, so it
+        // is refused outright rather than ignored.
+        const bad = unusableEventName(node.event);
+        if (bad !== null)
+            throw new Error(`Workflow "${wf.name}" has a waitFor gate ${bad}`);
+        // Narrowed by the guard above: `unusableEventName` returns null only for a
+        // non-empty string.
+        const event = node.event;
+        if (seen.has(event)) {
+            throw new Error(`Workflow "${wf.name}" waits for the event "${event}" more than once. ` +
+                `One signal would open every one of those gates, because a delivered signal ` +
+                `is never consumed. Give each gate its own event name.`);
+        }
+        seen.add(event);
+    }
+}
+export function assertNoIndexCollision(wf) {
+    const generators = wf.getIndexedStepNames();
+    if (generators.length === 0)
+        return;
+    for (const declared of wf.getStepNames()) {
+        for (const base of generators) {
+            if (declared !== base && new RegExp(`^${escapeRe(base)}:\\d+$`).test(declared)) {
+                throw new Error(`Step "${declared}" in "${wf.name}" collides with the per-iteration names ` +
+                    `reserved by the loop step "${base}" ("${base}:0", "${base}:1", ...). ` +
+                    `Rename one of them.`);
+            }
+        }
+    }
+}
+function escapeRe(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * `retry` is the number of ATTEMPTS, not the number of extra tries: the retry loop is
+ * `for (attempt = 1; attempt <= def.retry; attempt++)`.
+ *
+ * `retry: 0` therefore never executed the body at all, and the code after the loop read
+ * `exec.steps[def.name].startedAt` on a record that was never written, so the run's
+ * `failureReason` became `undefined is not an object (...)`: a TypeError where an operator
+ * looks for what went wrong. In a RESUMED loop the memo path restores the bare record, so
+ * `startedAt` resolves and a `failed` record is written for a handler that was never
+ * called, which the unwind then reverses: a rollback of a side effect that never happened
+ * (`test/repro-workflow-retry-zero.test.ts`).
+ *
+ * Refused where it is written rather than coerced to 1. A workflow asking for zero
+ * attempts is asking for something the engine cannot do, and quietly running the step
+ * once would be a different thing from what was written.
+ */
+function assertUsableRetry(step, retry) {
+    if (retry === undefined)
+        return;
+    if (!Number.isInteger(retry) || retry < 1) {
+        throw new Error(`Step "${step}" declares retry: ${retry}. retry is the number of attempts, so it must be an integer of 1 or more (1 means a single attempt with no retry).`);
+    }
+}
 export class Workflow {
     name;
     nodes = [];
@@ -12,7 +153,13 @@ export class Workflow {
         this.name = name;
     }
     /** Add a step to the workflow — return type accumulates into TSteps */
-    step(name, handler, options) {
+    step(name, handler, 
+    // The compensate handler in `options` sees this step's OWN result too, which the
+    // runtime already provides (compensationContext binds it) but the type used to
+    // omit, so `ctx.steps.charge` inside charge's own rollback was a type error while
+    // working perfectly at run time.
+    options) {
+        assertUsableRetry(name, options?.retry);
         this.nodes.push({
             type: 'step',
             def: {
@@ -43,19 +190,14 @@ export class Workflow {
         }
         const sub = new Workflow(`${this.name}:${name}`);
         builder(sub);
-        const steps = sub.nodes
-            .filter((n) => n.type === 'step')
-            .map((n) => n.def);
-        lastNode.def.paths.set(name, steps);
+        lastNode.def.paths.set(name, onlySteps(sub, 'path()', name));
         return this;
     }
     /** Run multiple steps in parallel — accumulated types from sub-builder merge into TSteps */
     parallel(builder) {
         const sub = new Workflow(`${this.name}:parallel`);
         builder(sub);
-        const steps = sub.nodes
-            .filter((n) => n.type === 'step')
-            .map((n) => n.def);
+        const steps = onlySteps(sub, 'parallel()');
         if (steps.length === 0) {
             throw new Error('parallel() requires at least one step');
         }
@@ -80,9 +222,7 @@ export class Workflow {
     doUntil(condition, builder, options) {
         const sub = new Workflow(`${this.name}:doUntil`);
         builder(sub);
-        const steps = sub.nodes
-            .filter((n) => n.type === 'step')
-            .map((n) => n.def);
+        const steps = onlySteps(sub, 'doUntil()');
         if (steps.length === 0)
             throw new Error('doUntil() requires at least one step');
         this.nodes.push({
@@ -99,9 +239,7 @@ export class Workflow {
     doWhile(condition, builder, options) {
         const sub = new Workflow(`${this.name}:doWhile`);
         builder(sub);
-        const steps = sub.nodes
-            .filter((n) => n.type === 'step')
-            .map((n) => n.def);
+        const steps = onlySteps(sub, 'doWhile()');
         if (steps.length === 0)
             throw new Error('doWhile() requires at least one step');
         this.nodes.push({
@@ -116,6 +254,10 @@ export class Workflow {
     }
     /** Iterate over items, executing a step for each */
     forEach(items, name, handler, options) {
+        // `forEach` builds its step definition here rather than going through `step()`, so it
+        // needs the same guard: without it, `forEach(..., { retry: 0 })` was accepted and the
+        // per-iteration mirror recorded a `failed` record for a handler that never ran.
+        assertUsableRetry(name, options?.retry);
         const step = {
             name,
             handler: handler,
@@ -143,6 +285,34 @@ export class Workflow {
         });
         return this;
     }
+    /**
+     * Mark the point of no return.
+     *
+     * Everything before it stays compensatable; everything after is committed and is
+     * never rolled back, however the run ends. Past the pivot the only correct
+     * recovery is forward — retry, alert, fix — because there is no semantic inverse
+     * for "the welcome email was sent". Declare it explicitly; it is never inferred.
+     */
+    pivot() {
+        this.nodes.push({ type: 'pivot' });
+        return this;
+    }
+    /**
+     * Step names that generate indexed per-iteration records (`name:0`, `name:1`, ...).
+     * Loop bodies and forEach steps both do; a plain step never does.
+     */
+    getIndexedStepNames() {
+        const names = [];
+        for (const node of this.nodes) {
+            if (node.type === 'doUntil' || node.type === 'doWhile') {
+                for (const s of node.def.steps)
+                    names.push(s.name);
+            }
+            else if (node.type === 'forEach')
+                names.push(node.def.step.name);
+        }
+        return names;
+    }
     /** Get flat list of step names for validation */
     getStepNames() {
         const names = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.46",
+  "version": "2.8.47",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",
@@ -56,14 +56,16 @@
     "start": "bun run src/main.ts",
     "build": "bun build --compile --minify src/main.ts --outfile dist/bunqueue",
     "build:lib": "tsc -p tsconfig.build.json",
+    "docs:api": "bun run scripts/build-api-reference.ts",
     "test": "BUNQUEUE_EMBEDDED=1 bun test",
-    "test:model": "BUNQUEUE_EMBEDDED=1 bun test test/model-based/queue-model.test.ts test/model-based/backup-model.test.ts test/model-based/monitoring-model.test.ts test/model-based/enterprise-telemetry-model.test.ts",
+    "test:model": "BUNQUEUE_EMBEDDED=1 bun test test/model-based/queue-model.test.ts test/model-based/workflow-model.test.ts test/model-based/backup-model.test.ts test/model-based/monitoring-model.test.ts test/model-based/enterprise-telemetry-model.test.ts",
     "test:sandbox": "bun run scripts/test-sandbox.ts",
     "test:sandbox:sdk": "bun run scripts/test-sdk-sandbox.ts",
-    "bench": "bun run bench/throughput.ts && bun run bench/latency.ts",
-    "bench:throughput": "bun run bench/throughput.ts",
-    "bench:latency": "bun run bench/latency.ts",
-    "bench:internal": "bun run benchmarks/index.ts",
+    "bench": "bun run bench/comprehensive.ts",
+    "bench:tcp": "bun run bench/tcp-bench.ts",
+    "bench:autobatch": "bun run bench/local-autobatch.ts",
+    "bench:pushbulk": "bun run bench/pushbulk-delta.ts",
+    "bench:joblist": "bun run bench/job-list-perf.ts",
     "bench:compare": "bun run bench/comparison/run.ts",
     "lint": "biome lint src",
     "lint:fix": "biome lint --write src",
@@ -79,13 +81,21 @@
     "msgpackr": "^1.11.8"
   },
   "devDependencies": {
+    "@ai-sdk/anthropic": "^4.0.22",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.220",
     "@biomejs/biome": "2.5.1",
+    "@langchain/core": "^1.2.3",
+    "@langchain/langgraph": "^1.4.8",
+    "@mastra/core": "^1.53.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@openai/agents": "^0.13.5",
     "@types/bun": "^1.3.9",
+    "ai": "^7.0.38",
     "bullmq": "^5.79.3",
     "elysia": "^1.4.25",
     "fast-check": "^4.9.0",
     "ioredis": "^5.11.1",
+    "typedoc": "^0.28.20",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },