@tessar/core 0.1.0-alpha.0 → 0.1.0

package/dist/engine/execution.js

@@ -0,0 +1,292 @@
+import { stream as streamHooks, model as modelHooks, input as inputHooks, } from "../events/type.js";
+import { TessarError, errorInfo, errorFromInfo, fail } from "../errors.js";
+import { aggregateUsage } from "../trace/usage.js";
+import { bindExecutionModel } from "../models/stream.js";
+import { loop } from "../loop.js";
+import { createDelivery, } from "./delivery.js";
+import { createFrame, loadRecords, watchLease, } from "./frame.js";
+import { eventContext } from "./hooks.js";
+import { Suspension } from "./interrupt.js";
+import { resolveChildAdmission } from "./lineage.js";
+import { prepareResume, prepareRecovery, restoreFrame } from "./resume.js";
+import { recoverTools } from "./tool-executor.js";
+export async function execute(execution, request, sink, registry) {
+    let frame;
+    let pendingLease;
+    try {
+        if (sink.controller.signal.aborted)
+            fail("Cancelled", "Execution cancelled before admission");
+        if (request.kind === "resume") {
+            frame = await prepareResume(execution, request, sink, registry);
+            execution.active.set(frame.stream.id, frame);
+            watchLease(execution, frame);
+            sink.admitted();
+            await execution.hook(frame, streamHooks.resumed, {
+                checkpointId: frame.cp.id,
+                interruptId: request.interruptId,
+                reason: "response",
+            });
+            const cursor = frame.cp.execution.handlerCursor;
+            if (cursor?.eventId === streamHooks.before) {
+                const result = await execution.hook(frame, streamHooks.before, cursor.payload);
+                if (result?.decision === "deny" || result?.decision === "stop") {
+                    await execution.finish(frame, "stopped", result.reason ?? "PolicyStopped");
+                    return;
+                }
+            }
+            if (cursor?.eventId === modelHooks.recover) {
+                const result = await execution.hook(frame, modelHooks.recover, cursor.payload);
+                if (result?.decision !== "retry")
+                    fail("ProviderError", "Recovery policy declined retry");
+                frame.cp.execution.phase = "BeforeModel";
+                await execution.commit(frame, "ExecutionTransition");
+            }
+            await loop(frame, execution);
+            return;
+        }
+        if (request.kind === "recover") {
+            frame = await prepareRecovery(execution, request, sink, registry);
+            execution.active.set(frame.stream.id, frame);
+            watchLease(execution, frame);
+            sink.admitted();
+            if (frame.cp.execution?.pendingInterruptId) {
+                const interrupt = await execution.runtime.backend.executions.get("interrupts", frame.cp.execution.pendingInterruptId, { threadId: request.threadId });
+                await execution.hook(frame, streamHooks.suspended, {
+                    checkpointId: frame.cp.id,
+                    interrupt: interrupt,
+                });
+                return;
+            }
+            await execution.hook(frame, streamHooks.resumed, {
+                checkpointId: frame.cp.id,
+                interruptId: null,
+                reason: "recovery",
+            });
+            await loop(frame, execution);
+            return;
+        }
+        const head = await execution.runtime.backend.threads.get(request.threadId);
+        if (!head)
+            fail("ThreadNotFound", "Thread not found");
+        if (head.activeStreamId)
+            fail("ThreadBusy", "Thread already has unfinished execution");
+        const lease = await execution.runtime.backend.ownership.acquire({
+            threadId: request.threadId,
+            ownerToken: execution.ids.next("owner"),
+            ttlMs: 30000,
+        });
+        pendingLease = lease;
+        const cp = structuredClone((await execution.runtime.backend.checkpoints.get(head.currentCheckpointId)));
+        const streamId = request.origin
+            ? await resolveChildAdmission(execution.runtime.backend, request.origin, request.threadId)
+            : execution.ids.next("stream"), usage = aggregateUsage([]);
+        const stream = {
+            id: streamId,
+            threadId: request.threadId,
+            scope: head.scope,
+            parentStreamId: request.origin?.parentStreamId ?? null,
+            parentToolExecutionId: request.origin?.parentToolExecutionId ?? null,
+            triggerMessageId: null,
+            status: "running",
+            stopReason: null,
+            startedAt: execution.clock.now(),
+            endedAt: null,
+            durationMs: null,
+            error: null,
+            directUsage: usage,
+            inclusiveUsage: usage,
+            outputMessageIds: [],
+        };
+        const records = await loadRecords(execution, request.threadId);
+        frame = createFrame(execution, {
+            request,
+            sink,
+            registry,
+            lease,
+            cp,
+            stream,
+            records,
+            admitted: false,
+        });
+        execution.put(frame, "streams", stream);
+        sink.setId(streamId);
+        execution.active.set(streamId, frame);
+        watchLease(execution, frame);
+        cp.execution = {
+            timing: { completedActiveMs: 0, segmentOpen: true, complete: true },
+            streamId,
+            turnId: null,
+            phase: "BeforeTurn",
+            modelRef: request.model,
+            ...(request.modelOptions ? { modelOptions: request.modelOptions } : {}),
+            baseInstructions: execution.agent.instructions,
+            pendingToolExecutionIds: [],
+            pendingInterruptId: null,
+            handlerCursor: null,
+            budgets: {
+                turns: 0,
+                modelAttempts: 0,
+                toolCalls: 0,
+                limits: { ...execution.agent.limits, ...request.limits },
+            },
+            registryManifest: [
+                ...registry.values.map((r) => ({
+                    pluginId: r.pluginId,
+                    kind: r.kind,
+                    id: r.id,
+                    version: r.version,
+                    pluginVersion: r.pluginVersion,
+                    configurationId: r.configurationId,
+                    requiredForContinuation: true,
+                })),
+                ...registry.handlers.map((r) => ({
+                    pluginId: r.pluginId,
+                    kind: "handler",
+                    id: r.id,
+                    version: r.version,
+                    pluginVersion: r.pluginVersion,
+                    configurationId: r.configurationId,
+                    requiredForContinuation: r.kind !== "notification",
+                })),
+            ],
+        };
+        bindExecutionModel(registry, cp.execution, request.adapter);
+        const input = await execution.hook(frame, inputHooks.prepare, {
+            messages: request.input,
+        });
+        if (input.rejected)
+            throw errorFromInfo(input.rejected);
+        for (const message of input.messages)
+            cp.state = {
+                ...cp.state,
+                messages: [
+                    ...cp.state.messages,
+                    await execution.prepareMessage(frame, message),
+                ],
+            };
+        stream.triggerMessageId = input.messages[0]?.id ?? null;
+        await execution.commit(frame, "InputCommitted");
+        frame.admitted = true;
+        sink.admitted();
+        await execution.hook(frame, streamHooks.started, {
+            modelRef: request.model,
+            checkpointId: frame.cp.id,
+        });
+        await execution.hook(frame, inputHooks.received, {
+            messages: input.messages,
+        });
+        if (input.handled) {
+            for (const message of input.handled.output)
+                await execution.appendMessage(frame, message);
+            await execution.finish(frame, "completed", null);
+            return;
+        }
+        const before = await execution.hook(frame, streamHooks.before, {
+            input: input.messages,
+        });
+        if (before?.decision === "deny" || before?.decision === "stop") {
+            await execution.finish(frame, "stopped", before.reason ?? "PolicyStopped");
+            return;
+        }
+        await loop(frame, execution);
+    }
+    catch (error) {
+        if (error instanceof Suspension)
+            return;
+        if (frame?.ownershipError)
+            error = new TessarError("OwnershipLost", "Execution ownership was lost");
+        const info = errorInfo(error);
+        if (frame?.admitted &&
+            info.source !== "storage" &&
+            ![
+                "StorageUnavailable",
+                "CommitConflict",
+                "OwnershipLost",
+                "RecoveryRequired",
+            ].includes(info.code)) {
+            try {
+                await execution.finish(frame, sink.controller.signal.aborted ? "cancelled" : "failed", info.code, info);
+                return error;
+            }
+            catch (finalizeError) {
+                error = finalizeError;
+            }
+        }
+        const finalError = errorInfo(error);
+        execution.runtime.report(finalError, eventContext(execution, frame));
+        sink.emit(streamHooks.error, {
+            error: finalError,
+            lastKnownCheckpointId: frame?.cp.id ?? null,
+            persistedStatus: frame?.stream.status ?? null,
+        }, eventContext(execution, frame));
+        sink.rejected(finalError);
+        return error;
+    }
+    finally {
+        if (frame) {
+            if (["completed", "failed", "stopped", "cancelled"].includes(frame.stream.status) ||
+                !frame.admitted)
+                execution.pendingModels.delete(frame.request.threadId);
+            if (frame.heartbeat)
+                clearInterval(frame.heartbeat);
+            execution.active.delete(frame.stream.id);
+            try {
+                await execution.runtime.backend.ownership.release(frame.lease);
+            }
+            catch {
+                /* recovery uses lease expiry */
+            }
+        }
+        else if (pendingLease) {
+            try {
+                await execution.runtime.backend.ownership.release(pendingLease);
+            }
+            catch {
+                /* lease expiry remains authoritative */
+            }
+        }
+        await registry.release();
+        sink.close();
+    }
+}
+export async function cancel(execution, threadId, streamId, reason = "Cancelled", target = { kind: "observer", observe: () => { } }, context = {}) {
+    const active = execution.active.get(streamId);
+    if (active) {
+        if (active.cp.threadId !== threadId)
+            fail("InvalidTransition", "Execution belongs to a different thread");
+        await execution.hook(active, streamHooks.cancel, { reason });
+        active.sink.controller.abort(reason);
+        return;
+    }
+    const registry = execution.runtime.hooks.capture(), sink = createDelivery(threadId, execution.ids, target, undefined, execution.runtime.report);
+    let frame;
+    try {
+        frame = await restoreFrame(execution, { ...context, kind: "recover", threadId, streamId }, sink, registry, false);
+        watchLease(execution, frame);
+        if (frame.cp.execution?.pendingToolExecutionIds.length)
+            await recoverTools(frame, execution, true);
+        for (const interrupt of execution.rows(frame, "interrupts"))
+            if (interrupt.streamId === streamId && interrupt.status === "pending") {
+                interrupt.status = "cancelled";
+                interrupt.resolvedAt = execution.clock.now();
+            }
+        for (const attempt of execution.rows(frame, "model_attempts"))
+            if (attempt.streamId === streamId && attempt.status === "running") {
+                attempt.status = "cancelled";
+                attempt.endedAt = execution.clock.now();
+            }
+        await execution.hook(frame, streamHooks.cancel, { reason });
+        await execution.finish(frame, "cancelled", reason);
+        execution.pendingModels.delete(threadId);
+    }
+    finally {
+        if (frame) {
+            if (frame.heartbeat)
+                clearInterval(frame.heartbeat);
+            await execution.runtime.backend.ownership.release(frame.lease);
+        }
+        await registry.release();
+        sink.close();
+    }
+}
+//# sourceMappingURL=execution.js.map

package/dist/engine/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../src/engine/execution.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,IAAI,WAAW,EACrB,KAAK,IAAI,UAAU,EACnB,KAAK,IAAI,UAAU,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAK3E,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EACL,cAAc,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,WAAW,EACX,UAAU,GAIX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,SAA2B,EAC3B,OAAyB,EACzB,IAAgB,EAChB,QAAuB;IAEvB,IAAI,KAAiC,CAAC;IACtC,IAAI,YAA+B,CAAC;IACpC,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO;YAChC,IAAI,CAAC,WAAW,EAAE,sCAAsC,CAAC,CAAC;QAC5D,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,KAAK,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChE,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC7C,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE;gBAC/C,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE;gBACzB,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,MAAM,EAAE,UAAU;aACnB,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC,SAAU,CAAC,aAAa,CAAC;YACjD,IAAI,MAAM,EAAE,OAAO,KAAK,WAAW,CAAC,MAAM,EAAE,CAAC;gBAC3C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CACjC,KAAK,EACL,WAAW,CAAC,MAAM,EAClB,MAAM,CAAC,OAAc,CACtB,CAAC;gBACF,IAAI,MAAM,EAAE,QAAQ,KAAK,MAAM,IAAI,MAAM,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC;oBAC/D,MAAM,SAAS,CAAC,MAAM,CACpB,KAAK,EACL,SAAS,EACT,MAAM,CAAC,MAAM,IAAI,eAAe,CACjC,CAAC;oBACF,OAAO;gBACT,CAAC;YACH,CAAC;YACD,IAAI,MAAM,EAAE,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;gBAC3C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CACjC,KAAK,EACL,UAAU,CAAC,OAAO,EAClB,MAAM,CAAC,OAAc,CACtB,CAAC;gBACF,IAAI,MAAM,EAAE,QAAQ,KAAK,OAAO;oBAC9B,IAAI,CAAC,eAAe,EAAE,gCAAgC,CAAC,CAAC;gBAC1D,KAAK,CAAC,EAAE,CAAC,SAAU,CAAC,KAAK,GAAG,aAAa,CAAC;gBAC1C,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;YACvD,CAAC;YACD,MAAM,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,KAAK,GAAG,MAAM,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAClE,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC7C,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,IAAI,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,kBAAkB,EAAE,CAAC;gBAC3C,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAC9D,YAAY,EACZ,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,kBAAkB,EACrC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAC/B,CAAC;gBACF,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,SAAS,EAAE;oBACjD,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE;oBACzB,SAAS,EAAE,SAAU;iBACtB,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE;gBAC/C,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE;gBACzB,WAAW,EAAE,IAAI;gBACjB,MAAM,EAAE,UAAU;aACnB,CAAC,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,cAAc;YACrB,IAAI,CAAC,YAAY,EAAE,yCAAyC,CAAC,CAAC;QAChE,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC;YAC9D,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YACvC,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,YAAY,GAAG,KAAK,CAAC;QACrB,MAAM,EAAE,GAAG,eAAe,CACxB,CAAC,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAC9C,IAAI,CAAC,mBAAmB,CACzB,CAAE,CACJ,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM;YAC3B,CAAC,CAAC,MAAM,qBAAqB,CACzB,SAAS,CAAC,OAAO,CAAC,OAAO,EACzB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,QAAQ,CACjB;YACH,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAChC,KAAK,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAiB;YAC3B,EAAE,EAAE,QAAQ;YACZ,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,cAAc,EAAE,OAAO,CAAC,MAAM,EAAE,cAAc,IAAI,IAAI;YACtD,qBAAqB,EAAE,OAAO,CAAC,MAAM,EAAE,qBAAqB,IAAI,IAAI;YACpE,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,SAAS;YACjB,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,IAAI;YACX,WAAW,EAAE,KAAK;YAClB,cAAc,EAAE,KAAK;YACrB,gBAAgB,EAAE,EAAE;SACrB,CAAC;QACF,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/D,KAAK,GAAG,WAAW,CAAC,SAAS,EAAE;YAC7B,OAAO;YACP,IAAI;YACJ,QAAQ;YACR,KAAK;YACL,EAAE;YACF,MAAM;YACN,OAAO;YACP,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;QACH,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrB,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACtC,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC7B,EAAE,CAAC,SAAS,GAAG;YACb,MAAM,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;YACnE,QAAQ;YACR,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,YAAY;YACnB,QAAQ,EAAE,OAAO,CAAC,KAAK;YACvB,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,gBAAgB,EAAE,SAAS,CAAC,KAAK,CAAC,YAAY;YAC9C,uBAAuB,EAAE,EAAE;YAC3B,kBAAkB,EAAE,IAAI;YACxB,aAAa,EAAE,IAAI;YACnB,OAAO,EAAE;gBACP,KAAK,EAAE,CAAC;gBACR,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,MAAM,EAAE,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE;aACzD;YACD,gBAAgB,EAAE;gBAChB,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC7B,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,aAAa,EAAE,CAAC,CAAC,aAAa;oBAC9B,eAAe,EAAE,CAAC,CAAC,eAAe;oBAClC,uBAAuB,EAAE,IAAI;iBAC9B,CAAC,CAAC;gBACH,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC/B,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,IAAI,EAAE,SAAS;oBACf,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,aAAa,EAAE,CAAC,CAAC,aAAa;oBAC9B,eAAe,EAAE,CAAC,CAAC,eAAe;oBAClC,uBAAuB,EAAE,CAAC,CAAC,IAAI,KAAK,cAAc;iBACnD,CAAC,CAAC;aACJ;SACF,CAAC;QACF,kBAAkB,CAAC,QAAQ,EAAE,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,EAAE;YAC5D,QAAQ,EAAE,OAAO,CAAC,KAAK;SACxB,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,QAAQ;YAAE,MAAM,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACxD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAClC,EAAE,CAAC,KAAK,GAAG;gBACT,GAAG,EAAE,CAAC,KAAK;gBACX,QAAQ,EAAE;oBACR,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ;oBACpB,MAAM,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC;iBAC/C;aACF,CAAC;QACJ,MAAM,CAAC,gBAAgB,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC;QACxD,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;QAChD,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,EAAE;YAC/C,QAAQ,EAAE,OAAO,CAAC,KAAK;YACvB,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE;SAC1B,CAAC,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE;YAC/C,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACzB,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM;gBACxC,MAAM,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;YACjD,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE;YAC7D,KAAK,EAAE,KAAK,CAAC,QAAQ;SACtB,CAAC,CAAC;QACH,IAAI,MAAM,EAAE,QAAQ,KAAK,MAAM,IAAI,MAAM,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC/D,MAAM,SAAS,CAAC,MAAM,CACpB,KAAK,EACL,SAAS,EACT,MAAM,CAAC,MAAM,IAAI,eAAe,CACjC,CAAC;YACF,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,UAAU;YAAE,OAAO;QACxC,IAAI,KAAK,EAAE,cAAc;YACvB,KAAK,GAAG,IAAI,WAAW,CAAC,eAAe,EAAE,8BAA8B,CAAC,CAAC;QAC3E,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC9B,IACE,KAAK,EAAE,QAAQ;YACf,IAAI,CAAC,MAAM,KAAK,SAAS;YACzB,CAAC;gBACC,oBAAoB;gBACpB,gBAAgB;gBAChB,eAAe;gBACf,kBAAkB;aACnB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EACrB,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,MAAM,CACpB,KAAK,EACL,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,EACvD,IAAI,CAAC,IAAI,EACT,IAAI,CACL,CAAC;gBACF,OAAO,KAAK,CAAC;YACf,CAAC;YAAC,OAAO,aAAa,EAAE,CAAC;gBACvB,KAAK,GAAG,aAAa,CAAC;YACxB,CAAC;QACH,CAAC;QACD,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QACpC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,CACP,WAAW,CAAC,KAAK,EACjB;YACE,KAAK,EAAE,UAAU;YACjB,qBAAqB,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,IAAI;YAC3C,eAAe,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI;SAC9C,EACD,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAC/B,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;YAAS,CAAC;QACT,IAAI,KAAK,EAAE,CAAC;YACV,IACE,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,QAAQ,CACtD,KAAK,CAAC,MAAM,CAAC,MAAM,CACpB;gBACD,CAAC,KAAK,CAAC,QAAQ;gBAEf,SAAS,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACzD,IAAI,KAAK,CAAC,SAAS;gBAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACpD,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACzC,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjE,CAAC;YAAC,MAAM,CAAC;gBACP,gCAAgC;YAClC,CAAC;QACH,CAAC;aAAM,IAAI,YAAY,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;YAC1C,CAAC;QACH,CAAC;QACD,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QACzB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,SAA2B,EAC3B,QAAgB,EAChB,QAAgB,EAChB,MAAM,GAAG,WAAW,EACpB,MAAM,GAAmB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,EAChE,OAAO,GAAiD,EAAE;IAE1D,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,MAAM,CAAC,EAAE,CAAC,QAAQ,KAAK,QAAQ;YACjC,IAAI,CAAC,mBAAmB,EAAE,yCAAyC,CAAC,CAAC;QACvE,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7D,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,EAChD,IAAI,GAAG,cAAc,CACnB,QAAQ,EACR,SAAS,CAAC,GAAG,EACb,MAAM,EACN,SAAS,EACT,SAAS,CAAC,OAAO,CAAC,MAAM,CACzB,CAAC;IACJ,IAAI,KAAiC,CAAC;IACtC,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,YAAY,CACxB,SAAS,EACT,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,EACnD,IAAI,EACJ,QAAQ,EACR,KAAK,CACN,CAAC;QACF,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC7B,IAAI,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,uBAAuB,CAAC,MAAM;YACpD,MAAM,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QAC7C,KAAK,MAAM,SAAS,IAAI,SAAS,CAAC,IAAI,CAEpC,KAAK,EAAE,YAAY,CAAC;YACpB,IAAI,SAAS,CAAC,QAAQ,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACtE,SAAS,CAAC,MAAM,GAAG,WAAW,CAAC;gBAC/B,SAAS,CAAC,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YAC/C,CAAC;QACH,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,IAAI,CAClC,KAAK,EACL,gBAAgB,CACjB;YACC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAClE,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC;gBAC7B,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YAC1C,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5D,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QACnD,SAAS,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;YAAS,CAAC;QACT,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,KAAK,CAAC,SAAS;gBAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACpD,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QACzB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/engine/frame.d.ts

@@ -0,0 +1,77 @@
+import type { Agent } from "../agent.js";
+import type { ExecutionRuntime } from "./runtime.js";
+import { type ErrorInfo } from "../errors.js";
+import type { JsonObject, JsonValue } from "../json.js";
+import type { MessageData } from "../messages/message.js";
+import type { ModelAdapter, ModelRef } from "../models/contract.js";
+import type { RegistryLease } from "../plugins/registry.js";
+import { PluginStateAccess } from "../state/plugin-state.js";
+import type { Lease } from "../state/storage-ports.js";
+import type { Checkpoint, RecordEntry, StreamLimits } from "../state/schema.js";
+import type { StreamRecord } from "../trace/records.js";
+import type { LoopContext } from "../loop.js";
+import type { Attachment } from "./delivery.js";
+import type { SessionHookHandle, ThreadHookHandle } from "../plugins/context.js";
+export interface ExecutionOrigin {
+    parentStreamId: string;
+    parentToolExecutionId?: string;
+    dispatchId: string;
+}
+export type ExecutionRequest = ({
+    kind: "input";
+    threadId: string;
+    input: readonly MessageData[];
+    model: ModelRef;
+    origin?: ExecutionOrigin;
+    context?: JsonObject;
+    limits?: Partial<StreamLimits>;
+} | {
+    kind: "resume";
+    threadId: string;
+    interruptId: string;
+    value: JsonValue;
+    model?: ModelRef;
+} | {
+    kind: "recover";
+    threadId: string;
+    streamId: string;
+    model?: ModelRef;
+}) & {
+    signal?: AbortSignal;
+    adapter?: ModelAdapter;
+    modelOptions?: JsonObject;
+    session?: SessionHookHandle;
+    thread?: ThreadHookHandle;
+};
+export interface ExecutionFrame {
+    activeSegmentStartedAt?: number;
+    turnStartedAt?: number;
+    effectLocks?: Map<string, Promise<unknown>>;
+    commitQueue?: Promise<void>;
+    heartbeat?: ReturnType<typeof setInterval>;
+    ownershipError?: ErrorInfo;
+    request: ExecutionRequest;
+    sink: Attachment;
+    registry: RegistryLease;
+    lease: Lease;
+    cp: Checkpoint;
+    stream: StreamRecord;
+    records: Map<string, RecordEntry>;
+    state: PluginStateAccess;
+    admitted: boolean;
+    sequence: number;
+}
+export type ExecutionContext = Omit<LoopContext, "finish"> & {
+    agent: Agent;
+    runtime: ExecutionRuntime;
+    active: Map<string, ExecutionFrame>;
+    pendingModels: Map<string, ModelAdapter>;
+    resumeAdmissions: Map<string, Promise<ExecutionFrame>>;
+    prepareMessage(frame: ExecutionFrame, message: MessageData): Promise<MessageData>;
+    finish(frame: ExecutionFrame, status: "completed" | "stopped" | "failed" | "cancelled", reason: string | null, error?: ErrorInfo | null): Promise<void>;
+};
+export declare function loadRecords(execution: ExecutionContext, threadId: string): Promise<Map<string, RecordEntry>>;
+export declare function createFrame(execution: ExecutionContext, options: Pick<ExecutionFrame, "request" | "sink" | "registry" | "lease" | "cp" | "stream" | "records" | "admitted">): ExecutionFrame;
+export declare function watchLease(execution: ExecutionContext, frame: ExecutionFrame): void;
+/** Account only observed attachment time; a crashed open segment is incomplete. */
+export declare function sampleActiveTime(frame: ExecutionFrame, close?: boolean): void;

package/dist/engine/frame.js

@@ -0,0 +1,83 @@
+import { errorInfo } from "../errors.js";
+import { PluginStateAccess, } from "../state/plugin-state.js";
+import { childStateDefinition } from "./tracked-effects.js";
+export async function loadRecords(execution, threadId) {
+    const records = new Map();
+    for (const kind of [
+        "streams",
+        "turns",
+        "model_attempts",
+        "tool_executions",
+        "interrupts",
+    ])
+        for (const row of await execution.runtime.backend.executions.listRecords(kind, threadId)) {
+            const id = "id" in row ? row.id : "";
+            records.set(kind + ":" + id, {
+                kind,
+                id,
+                threadId,
+                data: structuredClone(row),
+            });
+        }
+    return records;
+}
+export function createFrame(execution, options) {
+    if (options.request.adapter)
+        execution.pendingModels.set(options.request.threadId, options.request.adapter);
+    else if (options.request.kind !== "input")
+        options = {
+            ...options,
+            request: {
+                ...options.request,
+                adapter: execution.pendingModels.get(options.request.threadId),
+            },
+        };
+    let frame;
+    const state = new PluginStateAccess([
+        childStateDefinition,
+        ...options.registry.list("state"),
+    ], { type: "thread", id: options.request.threadId }, options.cp.state.pluginStates, async () => {
+        await execution.commit(frame, "PluginStateCommitted");
+        return frame.cp.id;
+    }, undefined, execution.runtime.backend.ownedState);
+    const timing = options.cp.execution?.timing;
+    if (options.cp.execution)
+        options.cp.execution.timing = {
+            completedActiveMs: timing?.completedActiveMs ?? 0,
+            complete: timing !== undefined && timing.complete && !timing.segmentOpen,
+            segmentOpen: true,
+        };
+    frame = {
+        ...options,
+        state,
+        sequence: 0,
+        activeSegmentStartedAt: performance.now(),
+    };
+    return frame;
+}
+export function watchLease(execution, frame) {
+    if (frame.heartbeat)
+        return;
+    frame.heartbeat = setInterval(() => {
+        void execution.runtime.backend.ownership.renew(frame.lease, 30000).then((lease) => {
+            frame.lease = lease;
+        }, (error) => {
+            frame.ownershipError = errorInfo(error, {
+                source: "storage",
+                backendId: execution.runtime.backend.id,
+            });
+            frame.sink.controller.abort("OwnershipLost");
+        });
+    }, 10000);
+}
+/** Account only observed attachment time; a crashed open segment is incomplete. */
+export function sampleActiveTime(frame, close = false) {
+    const timing = frame.cp.execution?.timing;
+    if (!timing || frame.activeSegmentStartedAt === undefined)
+        return;
+    const now = performance.now();
+    timing.completedActiveMs += Math.max(0, now - frame.activeSegmentStartedAt);
+    timing.segmentOpen = !close;
+    frame.activeSegmentStartedAt = close ? undefined : now;
+}
+//# sourceMappingURL=frame.js.map

package/dist/engine/frame.js.map

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

package/dist/engine/hooks.d.ts

@@ -0,0 +1,4 @@
+import type { AnyEvent, EventContext, PayloadOf, ResultOf } from "../events/definition.js";
+import type { ExecutionContext, ExecutionFrame } from "./frame.js";
+export declare function eventContext(execution: ExecutionContext, frame?: ExecutionFrame): EventContext;
+export declare function hook<D extends AnyEvent>(execution: ExecutionContext, frame: ExecutionFrame, definition: D, payload: PayloadOf<D>, toolExecutionId?: string): Promise<ResultOf<D>>;

package/dist/engine/hooks.js

@@ -0,0 +1,138 @@
+import { stream as streamHooks } from "../events/type.js";
+import { fail } from "../errors.js";
+import { immutable } from "../json.js";
+import {} from "../events/type.js";
+import { canonicalJson } from "../state/commit.js";
+import { Suspension } from "./interrupt.js";
+import { phaseForEvent } from "./resume.js";
+export function eventContext(execution, frame) {
+    return {
+        agentId: execution.agent.id,
+        controllerId: execution.runtime.id,
+        ...(frame
+            ? {
+                scope: frame.cp.state.scope,
+                sessionId: frame.request.session?.id,
+                streamId: frame.stream.id,
+                threadId: frame.cp.threadId,
+                sequence: ++frame.sequence,
+                timestamp: execution.clock.now(),
+            }
+            : {}),
+    };
+}
+export async function hook(execution, frame, definition, payload, toolExecutionId) {
+    const cursor = frame.cp.execution?.handlerCursor?.eventId === definition
+        ? frame.cp.execution.handlerCursor
+        : null;
+    const decisions = cursor?.decisions.slice() ?? [];
+    const kind = execution.runtime.hooks.kind(definition);
+    const mutable = kind === "transformation" || kind === "decision";
+    const context = {
+        ...eventContext(execution, frame),
+        ...(frame.request.session ? { session: frame.request.session } : {}),
+        ...(frame.request.thread ? { thread: frame.request.thread } : {}),
+        ...(mutable
+            ? {
+                ...execution.services(frame, toolExecutionId),
+                state: frame.state,
+            }
+            : {}),
+        signal: frame.sink.controller.signal,
+        context: frame.request.kind === "input" ? frame.request.context : undefined,
+        turnId: frame.cp.execution?.turnId,
+        streamId: frame.stream.id,
+        threadId: frame.cp.threadId,
+        startIndex: cursor?.nextIndex ?? 0,
+        initialDecision: decisions.at(-1) ?? undefined,
+        allowedHandlerIds: frame.cp.execution?.registryManifest
+            .filter((r) => r.kind === "handler")
+            .map((r) => r.id),
+        suspend: kind === "decision"
+            ? (def, data) => {
+                phaseForEvent(definition);
+                const binding = frame.registry.find("interruption", def.id);
+                if (!binding || binding.definition.version !== def.version)
+                    fail("ResumeIncompatible", "Interruption definition is not registered");
+                return {
+                    decision: "suspend",
+                    definitionId: def.id,
+                    definitionVersion: def.version,
+                    pluginId: binding.pluginId,
+                    payload: immutable(def.payload ? def.payload.parse(data) : data),
+                };
+            }
+            : undefined,
+        onDecision: execution.runtime.hooks.kind(definition) === "decision"
+            ? async (entry) => {
+                const value = entry.decision;
+                decisions.push(value ? immutable(value) : null);
+                frame.cp.execution.handlerCursor = {
+                    eventId: definition,
+                    handlerId: entry.handlerId,
+                    nextIndex: entry.index + 1,
+                    payload: immutable(cursor?.payload ?? payload),
+                    decisions,
+                };
+                if (value?.decision !== "suspend")
+                    await execution.commit(frame, "ExecutionTransition");
+            }
+            : undefined,
+    };
+    const value = await execution.runtime.hooks.dispatch(definition, payload, context, frame.registry);
+    if (execution.runtime.hooks.kind(definition) === "decision") {
+        if (value?.decision === "suspend")
+            await suspend(execution, frame, value, toolExecutionId);
+        if (frame.cp.execution?.handlerCursor?.eventId === definition)
+            frame.cp.execution.handlerCursor = null;
+    }
+    if (execution.runtime.hooks.kind(definition) === "notification")
+        frame.sink.emit(definition, payload, context);
+    return value;
+}
+async function suspend(execution, frame, decision, toolExecutionId) {
+    if (decision.decision !== "suspend")
+        fail("InvalidTransition", "Expected suspension decision");
+    const binding = frame.registry.find("interruption", decision.definitionId);
+    const position = frame.cp.execution, id = execution.ids.next("interrupt");
+    const tool = toolExecutionId
+        ? execution
+            .rows(frame, "tool_executions")
+            .find((t) => t.id === toolExecutionId)
+        : null;
+    const interrupt = {
+        id,
+        threadId: frame.cp.threadId,
+        streamId: frame.stream.id,
+        checkpointId: frame.cp.id,
+        definitionId: decision.definitionId,
+        definitionVersion: decision.definitionVersion,
+        pluginId: decision.pluginId,
+        payload: decision.payload,
+        responseSchema: binding.definition.response.jsonSchema,
+        actionRef: tool
+            ? {
+                toolExecutionId: tool.id,
+                toolName: tool.toolName,
+                argumentsDigest: canonicalJson(tool.arguments),
+            }
+            : null,
+        status: "pending",
+        response: null,
+        resolvedDecision: null,
+        createdAt: execution.clock.now(),
+        resolvedAt: null,
+        revision: frame.cp.revision,
+    };
+    execution.put(frame, "interrupts", interrupt);
+    position.pendingInterruptId = id;
+    position.phase = "Suspended";
+    frame.stream.status = "suspended";
+    await execution.commit(frame, "Suspended");
+    await execution.hook(frame, streamHooks.suspended, {
+        checkpointId: frame.cp.id,
+        interrupt,
+    });
+    throw new Suspension();
+}
+//# sourceMappingURL=hooks.js.map

package/dist/engine/hooks.js.map

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

package/dist/engine/interrupt.d.ts

@@ -1,6 +1,6 @@
 import { type JsonValue } from "../json.js";
 import type { InputDefinition } from "../tools/input-definition.js";
-import type { ControlDecision } from "../events/catalog.js";
+import type { ControlDecision } from "../events/type.js";
 import type { PluginStateAccess } from "../state/plugin-state.js";
 import type { ExecutionHookContext } from "./tracked-effects.js";
 export interface InterruptionDefinition<R = any, D extends ControlDecision = ControlDecision, P extends JsonValue = JsonValue> {

package/dist/engine/lineage.d.ts

@@ -2,7 +2,7 @@ import type { StorageBackend } from "../state/storage-ports.js";
 import type { PluginStateSnapshot } from "../state/schema.js";
 import type { ModelAttemptRecord } from "../trace/records.js";
 import { type ChildReservation } from "./tracked-effects.js";
-import type { ExecutionOrigin } from "../agent.js";
+import type { ExecutionOrigin } from "./frame.js";
 export declare function reservations(states: readonly PluginStateSnapshot[], streamId: string): ChildReservation[];
 export declare function resolveChildAdmission(backend: StorageBackend, origin: ExecutionOrigin, threadId: string): Promise<string>;
 export declare function summarizeStreamUsage(backend: StorageBackend, streamId: string, local?: {