@vantageos/agent-engine 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/component/_generated/api.d.ts

@@ -7,21 +7,49 @@
  * @module
  */
 import type * as engine_agents from "../engine/agents.js";
+import type * as engine_awaitEventTimeout from "../engine/awaitEventTimeout.js";
+import type * as engine_delegation from "../engine/delegation.js";
+import type * as engine_directory from "../engine/directory.js";
 import type * as engine_durableJob from "../engine/durableJob.js";
+import type * as engine_habits from "../engine/habits.js";
+import type * as engine_mandates from "../engine/mandates.js";
 import type * as engine_resolvers from "../engine/resolvers.js";
+import type * as engine_sandboxCallback from "../engine/sandboxCallback.js";
 import type * as engine_sessions from "../engine/sessions.js";
 import type * as engine_toolApprovals from "../engine/toolApprovals.js";
+import type * as engine_vpConnection from "../engine/vpConnection.js";
+import type * as engine_wakeup from "../engine/wakeup.js";
+import type * as engine_workflows from "../engine/workflows.js";
 import type * as lib_auth from "../lib/auth.js";
 import type * as testFixtures_callerSteps from "../testFixtures/callerSteps.js";
+import type * as testFixtures_delegationDemoWorkflow from "../testFixtures/delegationDemoWorkflow.js";
+import type * as testFixtures_sandboxDemoWorkflow from "../testFixtures/sandboxDemoWorkflow.js";
+import type * as testFixtures_vpTool from "../testFixtures/vpTool.js";
+import type * as testFixtures_wakeupDemoWorkflow from "../testFixtures/wakeupDemoWorkflow.js";
+import type * as testFixtures_wakeupWork from "../testFixtures/wakeupWork.js";
 import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
 declare const fullApi: ApiFromModules<{
     "engine/agents": typeof engine_agents;
+    "engine/awaitEventTimeout": typeof engine_awaitEventTimeout;
+    "engine/delegation": typeof engine_delegation;
+    "engine/directory": typeof engine_directory;
     "engine/durableJob": typeof engine_durableJob;
+    "engine/habits": typeof engine_habits;
+    "engine/mandates": typeof engine_mandates;
     "engine/resolvers": typeof engine_resolvers;
+    "engine/sandboxCallback": typeof engine_sandboxCallback;
     "engine/sessions": typeof engine_sessions;
     "engine/toolApprovals": typeof engine_toolApprovals;
+    "engine/vpConnection": typeof engine_vpConnection;
+    "engine/wakeup": typeof engine_wakeup;
+    "engine/workflows": typeof engine_workflows;
     "lib/auth": typeof lib_auth;
     "testFixtures/callerSteps": typeof testFixtures_callerSteps;
+    "testFixtures/delegationDemoWorkflow": typeof testFixtures_delegationDemoWorkflow;
+    "testFixtures/sandboxDemoWorkflow": typeof testFixtures_sandboxDemoWorkflow;
+    "testFixtures/vpTool": typeof testFixtures_vpTool;
+    "testFixtures/wakeupDemoWorkflow": typeof testFixtures_wakeupDemoWorkflow;
+    "testFixtures/wakeupWork": typeof testFixtures_wakeupWork;
 }>;
 /**
  * A utility for referencing Convex functions in your app's public API.
@@ -46,5 +74,8 @@ export declare const components: {
     agentTurnPool: import("@convex-dev/workpool/_generated/component.js").ComponentApi<"agentTurnPool">;
     wakeupPool: import("@convex-dev/workpool/_generated/component.js").ComponentApi<"wakeupPool">;
     agent: import("@convex-dev/agent/_generated/component.js").ComponentApi<"agent">;
+    rateLimiter: import("@convex-dev/rate-limiter/_generated/component.js").ComponentApi<"rateLimiter">;
+    shardedCounter: import("@convex-dev/sharded-counter/_generated/component.js").ComponentApi<"shardedCounter">;
+    crons: import("@convex-dev/crons/_generated/component.js").ComponentApi<"crons">;
 };
 export {};

package/dist/component/_generated/component.d.ts

@@ -23,10 +23,15 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         agents: {
             create: FunctionReference<"mutation", "internal", {
                 createdBy: string;
+                description?: string;
                 instructions: string;
+                maxInputTokensPerSession?: number | false;
+                maxSubagents?: number;
                 model: string;
+                modelProvider?: "gateway" | "openrouter";
                 name: string;
                 orgId: string;
+                reasoningEffort?: "none" | "low" | "medium" | "high";
             }, string, Name>;
             get: FunctionReference<"query", "internal", {
                 agentId: string;
@@ -36,14 +41,88 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 _id: string;
                 createdAt: number;
                 createdBy: string;
+                description?: string;
                 instructions: string;
+                maxInputTokensPerSession?: number | false;
+                maxSubagents?: number;
                 model: string;
+                modelProvider?: "gateway" | "openrouter";
                 name: string;
                 orgId: string;
+                reasoningEffort?: "none" | "low" | "medium" | "high";
                 status: "draft" | "live" | "archived";
                 updatedAt: number;
             } | null, Name>;
         };
+        awaitEventTimeout: {
+            cancel: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                timeoutRowId: string;
+            }, null, Name>;
+            schedule: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+                sessionId: string;
+                timeoutMs: number;
+            }, string, Name>;
+        };
+        delegation: {
+            declareSubagent: FunctionReference<"mutation", "internal", {
+                childAgentId: string;
+                description?: string;
+                orgId: string;
+                parentAgentId: string;
+                toolName: string;
+            }, string, Name>;
+            delegateToSubagent: FunctionReference<"action", "internal", {
+                awaitedEventName: string;
+                cost: number;
+                orgId: string;
+                payload?: string;
+                reason: string;
+                scope: string;
+                subagentId: string;
+                workFunctionHandle: string;
+                workflowId: string;
+            }, string, Name>;
+            invokeAgentClone: FunctionReference<"action", "internal", {
+                agentId: string;
+                awaitedEventName: string;
+                cost: number;
+                orgId: string;
+                payload?: string;
+                reason: string;
+                scope: string;
+                viaAgentTool: boolean;
+                workFunctionHandle: string;
+                workflowId: string;
+            }, string, Name>;
+            listSubagents: FunctionReference<"query", "internal", {
+                orgId: string;
+                parentAgentId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                childAgentId: string;
+                createdAt: number;
+                description?: string;
+                enabled: boolean;
+                orgId: string;
+                parentAgentId: string;
+                toolName: string;
+            }>, Name>;
+        };
+        directory: {
+            listByOrg: FunctionReference<"query", "internal", {
+                orgId: string;
+            }, Array<{
+                _id: string;
+                createdAt: number;
+                model: string;
+                name: string;
+                status: "draft" | "live" | "archived";
+            }>, Name>;
+        };
         durableJob: {
             cancel: FunctionReference<"mutation", "internal", {
                 jobId: string;
@@ -67,6 +146,140 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 totalSteps: number;
             }, string, Name>;
         };
+        habits: {
+            create: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                cronExpression: string;
+                name: string;
+                orgId: string;
+                prompt: string;
+            }, string, Name>;
+            disable: FunctionReference<"mutation", "internal", {
+                habitId: string;
+                orgId: string;
+            }, null, Name>;
+            enable: FunctionReference<"mutation", "internal", {
+                habitId: string;
+                orgId: string;
+            }, null, Name>;
+            get: FunctionReference<"query", "internal", {
+                habitId: string;
+                orgId: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                createdAt: number;
+                cronExpression: string;
+                cronJobId?: string;
+                enabled: boolean;
+                lastRunAt?: number;
+                name: string;
+                orgId: string;
+                prompt: string;
+                updatedAt: number;
+            } | null, Name>;
+            listForAgent: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                createdAt: number;
+                cronExpression: string;
+                cronJobId?: string;
+                enabled: boolean;
+                lastRunAt?: number;
+                name: string;
+                orgId: string;
+                prompt: string;
+                updatedAt: number;
+            }>, Name>;
+            listRuns: FunctionReference<"query", "internal", {
+                habitId: string;
+                orgId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                habitId: string;
+                orgId: string;
+                ranAt: number;
+            }>, Name>;
+            updateSchedule: FunctionReference<"mutation", "internal", {
+                cronExpression?: string;
+                habitId: string;
+                name?: string;
+                orgId: string;
+                prompt?: string;
+            }, null, Name>;
+        };
+        mandates: {
+            get: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+                scope: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                capacity?: number;
+                createdAt: number;
+                kind: "token bucket" | "fixed window";
+                orgId: string;
+                period: number;
+                rate: number;
+                scope: string;
+                updatedAt: number;
+            } | null, Name>;
+            listApprovals: FunctionReference<"query", "internal", {
+                agentId?: string;
+                orgId: string;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                createdAt: number;
+                orgId: string;
+                reason: string;
+                requestedCost: number;
+                resolvedAt?: number;
+                resolvedBy?: string;
+                scope: string;
+                status: "pending" | "approved" | "denied";
+            }>, Name>;
+            resolveApproval: FunctionReference<"mutation", "internal", {
+                approvalId: string;
+                decision: "approved" | "denied";
+                orgId: string;
+                resolvedBy: string;
+            }, null, Name>;
+            set: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                capacity?: number;
+                kind: "token bucket" | "fixed window";
+                orgId: string;
+                period: number;
+                rate: number;
+                scope: string;
+            }, string, Name>;
+            spend: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                cost: number;
+                orgId: string;
+                reason: string;
+                scope: string;
+            }, {
+                approvalId?: string;
+                ok: boolean;
+            }, Name>;
+            usageCount: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+                scope: string;
+            }, number, Name>;
+        };
         resolvers: {
             resolveManifest: FunctionReference<"query", "internal", {
                 orgId: string;
@@ -82,6 +295,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 }>;
             }, Name>;
         };
+        sandboxCallback: {
+            attachSandboxId: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                sandboxId: string;
+                sandboxRunId: string;
+            }, null, Name>;
+            deadLetterMalformed: FunctionReference<"mutation", "internal", {
+                deliveryId: string;
+                orgId?: string;
+                rawBody: string;
+                reason: string;
+            }, null, Name>;
+            getStatus: FunctionReference<"query", "internal", {
+                orgId: string;
+                sandboxRunId: string;
+            }, {
+                resultSummary?: string;
+                status: "pending" | "completed" | "failed" | "timedOut";
+            }, Name>;
+            processCallback: FunctionReference<"mutation", "internal", {
+                deliveryId: string;
+                orgId: string;
+                resultSummary?: string;
+                sandboxRunId: string;
+                status: "completed" | "failed";
+            }, {
+                outcome: "woke" | "duplicate" | "dead-lettered";
+            }, Name>;
+            startRun: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+                timeoutMs: number;
+                workflowId: string;
+            }, string, Name>;
+        };
         sessions: {
             appendReasoning: FunctionReference<"mutation", "internal", {
                 chunk: string;
@@ -105,7 +353,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 _creationTime: number;
                 _id: string;
                 createdAt: number;
-                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved";
+                name: "session.started" | "turn.started" | "turn.reasoning" | "turn.toolCall.requested" | "turn.toolCall.completed" | "turn.toolCall.denied" | "turn.completed" | "tool.approval.requested" | "tool.approval.resolved" | "sandbox.timeout";
                 payload?: string;
             }>, Name>;
             requestToolCall: FunctionReference<"mutation", "internal", {
@@ -127,7 +375,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 agentId: string;
                 createdBy: string;
                 orgId: string;
-            }, string, Name>;
+            }, {
+                sessionId: string;
+                workflowId: string;
+            }, Name>;
         };
         toolApprovals: {
             respond: FunctionReference<"mutation", "internal", {
@@ -138,5 +389,98 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 updatePolicy?: "always" | "once" | "never";
             }, null, Name>;
         };
+        vpConnection: {
+            get: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, {
+                _creationTime: number;
+                _id: string;
+                agentId: string;
+                createdAt: number;
+                memoryEnabled: boolean;
+                messagesEnabled: boolean;
+                notesEnabled: boolean;
+                orgId: string;
+                tasksEnabled: boolean;
+                updatedAt: number;
+            } | null, Name>;
+            getToggles: FunctionReference<"query", "internal", {
+                agentId: string;
+                orgId: string;
+            }, {
+                memoryEnabled: boolean;
+                messagesEnabled: boolean;
+                notesEnabled: boolean;
+                tasksEnabled: boolean;
+            }, Name>;
+            invokeVpTool: FunctionReference<"action", "internal", {
+                agentId: string;
+                argsJson: string;
+                orgId: string;
+                tool: "memory" | "tasks" | "messages" | "notes";
+                vpFunctionHandle: string;
+            }, null, Name>;
+            setToggles: FunctionReference<"mutation", "internal", {
+                agentId: string;
+                memoryEnabled?: boolean;
+                messagesEnabled?: boolean;
+                notesEnabled?: boolean;
+                orgId: string;
+                tasksEnabled?: boolean;
+            }, string, Name>;
+        };
+        wakeup: {
+            cancel: FunctionReference<"mutation", "internal", {
+                orgId: string;
+                wakeableWorkId: string;
+            }, null, Name>;
+            enqueue: FunctionReference<"action", "internal", {
+                agentId: string;
+                awaitedEventName: string;
+                cost: number;
+                orgId: string;
+                payload?: string;
+                reason: string;
+                scope: string;
+                workFunctionHandle: string;
+                workflowId: string;
+            }, string, Name>;
+            getStatus: FunctionReference<"query", "internal", {
+                orgId: string;
+                wakeableWorkId: string;
+            }, {
+                resultSummary?: string;
+                status: "pending" | "completed" | "failed" | "cancelled";
+            }, Name>;
+        };
+    };
+    testFixtures: {
+        delegationDemoWorkflow: {
+            start: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+            }, {
+                workflowId: string;
+            }, Name>;
+        };
+        sandboxDemoWorkflow: {
+            start: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+            }, {
+                resultId: string;
+                workflowId: string;
+            }, Name>;
+        };
+        wakeupDemoWorkflow: {
+            start: FunctionReference<"mutation", "internal", {
+                awaitedEventName: string;
+                orgId: string;
+            }, {
+                resultId: string;
+                workflowId: string;
+            }, Name>;
+        };
     };
 };

package/dist/component/convex.config.js

@@ -2,6 +2,9 @@ import { defineComponent } from "convex/server";
 import workflow from "@convex-dev/workflow/convex.config";
 import workpool from "@convex-dev/workpool/convex.config";
 import agent from "@convex-dev/agent/convex.config";
+import rateLimiter from "@convex-dev/rate-limiter/convex.config";
+import shardedCounter from "@convex-dev/sharded-counter/convex.config";
+import crons from "@convex-dev/crons/convex.config";
 // @vantageos/agent-engine — Convex COMPONENT definition (pattern
 // `@convex-dev/*`, verified against the published shape of
 // `@convex-dev/workflow` — `defineComponent(name)` + a `convex.config.ts`
@@ -32,9 +35,24 @@ import agent from "@convex-dev/agent/convex.config";
 // awaitEventTimeouts, wakeableWork) is deliberately NOT yet re-hosted
 // here — porting those without a working component-level test harness
 // behind each of them would violate Day 128 (never ship unverified).
+// Mandates (bounded, weighted spending authority per agent/org/scope) are
+// hosted under this component boundary, using official `@convex-dev/*`
+// libraries only -- no canary/alpha dependency for a guardrail:
+// `rate-limiter` for the fails-closed spend gate itself, `sharded-counter`
+// for the usage rollup. See component/engine/mandates.ts.
+// Habits (a dynamic, per-agent/org cron schedule editable at runtime) are
+// also hosted under this component boundary, ported byte-identical from the
+// repo-root prototype (convex/habits.ts). `crons` is a sub-component of
+// THIS component -- create/updateSchedule/enable/disable register or tear
+// down a runtime cron job via `@convex-dev/crons` inside the SAME Convex
+// mutation transaction that writes the `habits` row, so no habit schedule
+// change ever requires a redeploy. See component/engine/habits.ts.
 const component = defineComponent("agentEngine");
 component.use(workflow);
 component.use(workpool, { name: "agentTurnPool" });
 component.use(workpool, { name: "wakeupPool" });
 component.use(agent);
+component.use(rateLimiter);
+component.use(shardedCounter);
+component.use(crons);
 export default component;

package/dist/component/engine/agents.d.ts

@@ -1,4 +1,9 @@
 export declare const create: import("convex/server").RegisteredMutation<"public", {
+    description?: string | undefined;
+    reasoningEffort?: "none" | "low" | "medium" | "high" | undefined;
+    modelProvider?: "gateway" | "openrouter" | undefined;
+    maxSubagents?: number | undefined;
+    maxInputTokensPerSession?: number | false | undefined;
     name: string;
     orgId: string;
     instructions: string;
@@ -11,6 +16,11 @@ export declare const get: import("convex/server").RegisteredQuery<"public", {
 }, Promise<{
     _id: import("convex/values").GenericId<"agents">;
     _creationTime: number;
+    description?: string | undefined;
+    reasoningEffort?: "none" | "low" | "medium" | "high" | undefined;
+    modelProvider?: "gateway" | "openrouter" | undefined;
+    maxSubagents?: number | undefined;
+    maxInputTokensPerSession?: number | false | undefined;
     name: string;
     orgId: string;
     status: "draft" | "live" | "archived";

package/dist/component/engine/agents.js

@@ -8,13 +8,21 @@ import { requireOrgId } from "../lib/auth.js";
 // `create`/`get`, no `update`/`list`/skills/connections — the full agent
 // aggregate CRUD stays out of this component boundary for this pass (see
 // component/schema.ts SCOPE note).
+const reasoningEffort = v.union(v.literal("none"), v.literal("low"), v.literal("medium"), v.literal("high"));
+const modelProvider = v.union(v.literal("gateway"), v.literal("openrouter"));
+const maxInputTokensPerSession = v.union(v.number(), v.literal(false));
 const agentDoc = v.object({
     _id: v.id("agents"),
     _creationTime: v.number(),
     orgId: v.string(),
     name: v.string(),
+    description: v.optional(v.string()),
     instructions: v.string(),
     model: v.string(),
+    reasoningEffort: v.optional(reasoningEffort),
+    modelProvider: v.optional(modelProvider),
+    maxSubagents: v.optional(v.number()),
+    maxInputTokensPerSession: v.optional(maxInputTokensPerSession),
     status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
     createdBy: v.string(),
     createdAt: v.number(),
@@ -25,8 +33,13 @@ export const create = mutation({
         orgId: v.string(),
         createdBy: v.string(),
         name: v.string(),
+        description: v.optional(v.string()),
         instructions: v.string(),
         model: v.string(),
+        reasoningEffort: v.optional(reasoningEffort),
+        modelProvider: v.optional(modelProvider),
+        maxSubagents: v.optional(v.number()),
+        maxInputTokensPerSession: v.optional(maxInputTokensPerSession),
     },
     returns: v.id("agents"),
     handler: async (ctx, args) => {
@@ -43,12 +56,20 @@ export const create = mutation({
         if (args.model.trim().length === 0) {
             throw new Error("Validation: model must not be empty");
         }
+        if (args.maxSubagents !== undefined && args.maxSubagents < 0) {
+            throw new Error("Validation: maxSubagents must not be negative");
+        }
         const now = Date.now();
         return await ctx.db.insert("agents", {
             orgId,
             name: args.name,
+            description: args.description,
             instructions: args.instructions,
             model: args.model,
+            reasoningEffort: args.reasoningEffort,
+            modelProvider: args.modelProvider,
+            maxSubagents: args.maxSubagents,
+            maxInputTokensPerSession: args.maxInputTokensPerSession,
             status: "live",
             createdBy: args.createdBy,
             createdAt: now,

package/dist/component/engine/awaitEventTimeout.d.ts

@@ -0,0 +1,13 @@
+export declare const schedule: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    sessionId: import("convex/values").GenericId<"sessions">;
+    awaitedEventName: string;
+    timeoutMs: number;
+}, Promise<import("convex/values").GenericId<"awaitEventTimeouts">>>;
+export declare const cancel: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    timeoutRowId: import("convex/values").GenericId<"awaitEventTimeouts">;
+}, Promise<null>>;
+export declare const fire: import("convex/server").RegisteredMutation<"internal", {
+    timeoutRowId: import("convex/values").GenericId<"awaitEventTimeouts">;
+}, Promise<null>>;

package/dist/component/engine/awaitEventTimeout.js

@@ -0,0 +1,81 @@
+import { v } from "convex/values";
+import { internal } from "../_generated/api.js";
+import { internalMutation, mutation } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+// engine/awaitEventTimeout — self-built timeout for step.awaitEvent
+// (workflow#177: "Convex does not provide a native timeout for
+// awaitEvent"). We schedule a mutation that
+// fires a "blank" `sandbox.timeout` sessionEvent at the deadline; the
+// workflow's `awaitEvent` call is written to also accept this event name so
+// it wakes up even if the awaited event never arrives. Pattern:
+// maintainer's posted code in workflow#177, adapted to our sessionEvents
+// table.
+//
+// NOTE ("intentional divergence from Eve"): orgId is an EXPLICIT ARGUMENT on
+// every public function, never derived from `ctx.auth` -- auth does NOT
+// propagate across a component boundary (component/lib/auth.ts). Also:
+// `sessionEvents.name`'s union in component/schema.ts did not previously
+// include `sandbox.timeout` -- it has been added there (and mirrored in
+// `engine/sessions.listEvents`'s return validator) as part of this
+// migration, otherwise `fire`'s insert below would not compile under the
+// strict build.
+export const schedule = mutation({
+    args: {
+        orgId: v.string(),
+        sessionId: v.id("sessions"),
+        awaitedEventName: v.string(),
+        timeoutMs: v.number(),
+    },
+    returns: v.id("awaitEventTimeouts"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const session = await ctx.db.get(args.sessionId);
+        assertSameOrg(orgId, session, "Session not found");
+        if (args.timeoutMs <= 0) {
+            throw new Error("Validation: timeoutMs must be > 0");
+        }
+        const timeoutRowId = await ctx.db.insert("awaitEventTimeouts", {
+            orgId,
+            sessionId: args.sessionId,
+            awaitedEventName: args.awaitedEventName,
+            deadlineAt: Date.now() + args.timeoutMs,
+        });
+        const scheduledFunctionId = await ctx.scheduler.runAfter(args.timeoutMs, internal.engine.awaitEventTimeout.fire, { timeoutRowId });
+        await ctx.db.patch(timeoutRowId, { scheduledFunctionId });
+        return timeoutRowId;
+    },
+});
+export const cancel = mutation({
+    args: { orgId: v.string(), timeoutRowId: v.id("awaitEventTimeouts") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const row = await ctx.db.get(args.timeoutRowId);
+        assertSameOrg(orgId, row, "Timeout not found");
+        if (!row.firedAt && !row.cancelledAt && row.scheduledFunctionId) {
+            await ctx.scheduler.cancel(row.scheduledFunctionId);
+            await ctx.db.patch(args.timeoutRowId, { cancelledAt: Date.now() });
+        }
+        return null;
+    },
+});
+// internal — invoked only by the scheduler, never by a client.
+export const fire = internalMutation({
+    args: { timeoutRowId: v.id("awaitEventTimeouts") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const row = await ctx.db.get(args.timeoutRowId);
+        if (!row || row.firedAt || row.cancelledAt) {
+            return null; // already resolved by the real event or by a prior fire
+        }
+        await ctx.db.patch(args.timeoutRowId, { firedAt: Date.now() });
+        await ctx.db.insert("sessionEvents", {
+            orgId: row.orgId,
+            sessionId: row.sessionId,
+            name: "sandbox.timeout",
+            payload: JSON.stringify({ awaitedEventName: row.awaitedEventName }),
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});