@vantageos/agent-engine 0.1.0-alpha.8 → 0.3.0-alpha.1

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

@@ -2,11 +2,11 @@ import type { Id } from "../_generated/dataModel.js";
 export declare const set: import("convex/server").RegisteredMutation<"public", {
     capacity?: number | undefined;
     orgId: string;
-    kind: "token bucket" | "fixed window";
     agentId: import("convex/values").GenericId<"agents">;
     scope: string;
     rate: number;
     period: number;
+    kind: "token bucket" | "fixed window";
 }, Promise<import("convex/values").GenericId<"mandates">>>;
 export declare const get: import("convex/server").RegisteredQuery<"public", {
     orgId: string;
@@ -19,11 +19,11 @@ export declare const get: import("convex/server").RegisteredQuery<"public", {
     orgId: string;
     createdAt: number;
     updatedAt: number;
-    kind: "token bucket" | "fixed window";
     agentId: import("convex/values").GenericId<"agents">;
     scope: string;
     rate: number;
     period: number;
+    kind: "token bucket" | "fixed window";
 } | null>>;
 export declare const spend: import("convex/server").RegisteredMutation<"public", {
     orgId: string;

package/dist/component/engine/mandates.js

@@ -4,26 +4,7 @@ import { ShardedCounter } from "@convex-dev/sharded-counter";
 import { internalMutation, mutation, query } from "../_generated/server.js";
 import { components } from "../_generated/api.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/mandates — "intentional divergence from Eve": BOUNDED AUTHORITY.
-// A mandate is a LINE OF DATA scoped
-// orgId+agentId+scope, never a constant read from code (litmus test: a
-// client changes their mind => zero deployment). The rate-limiter has NO
-// static named config in this module -- every call to `spend` builds its
-// `config` inline, dynamically, from the `mandates` row loaded from the
-// database (@convex-dev/rate-limiter README §"Define a rate limit inline /
-// dynamically"). Fails-closed: no mandate row => refusal, never a silent
-// bypass.
-//
-// orgId discipline (component/lib/auth.ts): every PUBLIC function takes
-// `orgId` as an explicit ARGUMENT (auth does not propagate across a
-// component boundary), same as the rest of this component (agents,
-// wakeup, sessions). `spendInternal` also takes `orgId` as an argument, but
-// is an `internalMutation` -- the ONLY caller reachable from any client is
-// `engine/wakeup.enqueue` (an action), which threads its own
-// caller-supplied `orgId` argument through after validating it.
 const rateLimiter = new RateLimiter(components.rateLimiter);
-// Usage rollup, keyed identically to the rate-limiter key (org+agent+scope).
-// internal research notes: counters via sharded-counter, never a canary/alpha dependency.
 const usageCounter = new ShardedCounter(components.shardedCounter);
 const mandateDoc = v.object({
     _id: v.id("mandates"),
@@ -38,9 +19,6 @@ const mandateDoc = v.object({
     createdAt: v.number(),
     updatedAt: v.number(),
 });
-// set — upserts the DATA row that bounds an agent's authority for a given
-// scope. This is the ONLY place a cap value is ever written; there is no
-// constant anywhere in the engine that plays this role.
 export const set = mutation({
     args: {
         orgId: v.string(),
@@ -101,25 +79,6 @@ export const get = query({
             .unique();
     },
 });
-// spend — the single choke point through which every costed action an
-// agent takes must pass. `cost` is a WEIGHTED count (tokens, euros, calls —
-// whatever the mandate's scope means), never a plain call counter.
-//
-// Deny by default, twice over:
-//   1. No mandate row for this org+agent+scope => throw immediately. We do
-//      NOT fall back to "unlimited"; an unconfigured mandate is a refusal,
-//      not an escape hatch. Nothing needs to be persisted for this case, so
-//      throwing (and rolling back the whole transaction) is safe.
-//   2. Mandate exists but is exhausted => an approvalRequests row MUST be
-//      committed. Convex mutations are single transactions: throwing after
-//      `ctx.db.insert` would roll the insert back along with everything
-//      else, silently destroying the very approval request the guard is
-//      supposed to leave behind. So this path returns `{ ok: false }`
-//      instead of throwing -- the approval row survives, and the caller
-//      (engine/wakeup) is REQUIRED to check `.ok` and treat `false` as a
-//      hard refusal. There is no code path that lets the action proceed
-//      past an exhausted mandate; the only way authority is restored is an
-//      explicit human `resolveApproval("approved")`.
 export const spend = mutation({
     args: {
         orgId: v.string(),
@@ -139,14 +98,6 @@ export const spend = mutation({
         return await spendCore(ctx, orgId, args);
     },
 });
-// spendInternal — SAME choke point as `spend`, INTERNAL ONLY (unreachable
-// from any client). This is the ONE function `engine/wakeup.enqueue` (an
-// `action`) calls, in its OWN transaction, before it may ever call
-// `enqueueInternal` to put work in the pool -- see the wiring note in
-// component/engine/wakeup.ts. Trusting an `orgId` argument here is exactly
-// as safe as `engine/wakeup.enqueueInternal` trusting one: the only code
-// that can reach an `internal.*` function is other server code, never a
-// client SDK. The public `spend` above is completely untouched.
 export const spendInternal = internalMutation({
     args: {
         orgId: v.string(),
@@ -174,7 +125,6 @@ async function spendCore(ctx, orgId, args) {
         .withIndex("by_org_agent_scope", (q) => q.eq("orgId", orgId).eq("agentId", args.agentId).eq("scope", args.scope))
         .unique();
     if (!mandate) {
-        // fails-closed: no data => no authority. Never silently unlimited.
         throw new Error(`Mandate refused: no mandate configured for scope "${args.scope}"`);
     }
     const key = `${orgId}:${args.agentId}:${args.scope}`;
@@ -189,10 +139,6 @@ async function spendCore(ctx, orgId, args) {
         },
     });
     if (!status.ok) {
-        // Overrun => a human approval request is created and PERSISTED
-        // (returning instead of throwing so the transaction commits it). This
-        // is the ONLY consequence of an overrun -- there is no code path that
-        // spends past an exhausted mandate.
         const approvalId = await ctx.db.insert("approvalRequests", {
             orgId,
             agentId: args.agentId,
@@ -204,8 +150,6 @@ async function spendCore(ctx, orgId, args) {
         });
         return { ok: false, approvalId };
     }
-    // Rollup via sharded-counter (internal research notes: no canary dependency for a
-    // guardrail). One shard bucket per org+agent+scope key.
     await usageCounter.add(ctx, key, args.cost);
     return { ok: true };
 }
@@ -235,8 +179,6 @@ export const listApprovals = query({
             : rows;
     },
 });
-// resolveApproval — the ONLY way an overrun ever becomes usable authority
-// again: an explicit human decision, recorded, never inferred.
 export const resolveApproval = mutation({
     args: {
         orgId: v.string(),
@@ -257,7 +199,6 @@ export const resolveApproval = mutation({
         return null;
     },
 });
-// usageCount — the rollup readout (sharded-counter), for dashboards/audits.
 export const usageCount = query({
     args: { orgId: v.string(), agentId: v.id("agents"), scope: v.string() },
     returns: v.number(),

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

@@ -0,0 +1,97 @@
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+export declare function enqueueMessage(ctx: MutationCtx, args: {
+    orgId: string;
+    queueName: string;
+    payloadJson: string;
+    idempotencyKey?: string;
+    delaySeconds?: number;
+}): Promise<{
+    messageId: string;
+}>;
+export declare function getMessageById(ctx: MutationCtx | QueryCtx, args: {
+    orgId: string;
+    messageId: string;
+}): Promise<{
+    _id: import("convex/values").GenericId<"worldQueueMessages">;
+    _creationTime: number;
+    idempotencyKey?: string | undefined;
+    orgId: string;
+    status: "failed" | "pending" | "claimed" | "delivered";
+    createdAt: number;
+    updatedAt: number;
+    queueName: string;
+    messageId: string;
+    payloadJson: string;
+    attempt: number;
+    deliverAt: number;
+} | null>;
+export declare function settleMessageById(ctx: MutationCtx, args: {
+    orgId: string;
+    messageId: string;
+    status: "delivered" | "failed";
+}): Promise<boolean>;
+export declare function setMessagePayload(ctx: MutationCtx, args: {
+    orgId: string;
+    messageId: string;
+    payloadJson: string;
+}): Promise<boolean>;
+export declare const enqueue: import("convex/server").RegisteredMutation<"public", {
+    idempotencyKey?: string | undefined;
+    delaySeconds?: number | undefined;
+    orgId: string;
+    queueName: string;
+    payloadJson: string;
+}, Promise<{
+    messageId: string;
+}>>;
+export declare const claimNextForDelivery: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    queueNamePrefix: string;
+}, Promise<{
+    messageId: string;
+    queueName: string;
+    payloadJson: string;
+    idempotencyKey: string | undefined;
+    attempt: number;
+    status: "claimed";
+    deliverAt: number;
+    createdAt: number;
+    updatedAt: number;
+} | null>>;
+export declare const markDelivered: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    messageId: string;
+}, Promise<null>>;
+export declare const markFailedForRetry: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    messageId: string;
+    delaySeconds: number;
+}, Promise<null>>;
+export declare const getMessage: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    messageId: string;
+}, Promise<{
+    messageId: string;
+    queueName: string;
+    payloadJson: string;
+    idempotencyKey: string | undefined;
+    attempt: number;
+    status: "failed" | "pending" | "claimed" | "delivered";
+    deliverAt: number;
+    createdAt: number;
+    updatedAt: number;
+} | null>>;
+export declare const listPending: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    queueNamePrefix: string;
+}, Promise<{
+    messageId: string;
+    queueName: string;
+    payloadJson: string;
+    idempotencyKey: string | undefined;
+    attempt: number;
+    status: "failed" | "pending" | "claimed" | "delivered";
+    deliverAt: number;
+    createdAt: number;
+    updatedAt: number;
+}[]>>;

package/dist/component/engine/queue.js

@@ -0,0 +1,201 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server.js";
+import { requireOrgId } from "../lib/auth.js";
+const queueMessageResult = v.object({
+    messageId: v.string(),
+    queueName: v.string(),
+    payloadJson: v.string(),
+    idempotencyKey: v.optional(v.string()),
+    attempt: v.number(),
+    status: v.union(v.literal("pending"), v.literal("claimed"), v.literal("delivered"), v.literal("failed")),
+    deliverAt: v.number(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+function newMessageId() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 14)}`;
+}
+export async function enqueueMessage(ctx, args) {
+    const { orgId } = args;
+    const now = Date.now();
+    if (args.idempotencyKey) {
+        const existing = await ctx.db
+            .query("worldQueueMessages")
+            .withIndex("by_org_queue_idempotencyKey", (q) => q
+            .eq("orgId", orgId)
+            .eq("queueName", args.queueName)
+            .eq("idempotencyKey", args.idempotencyKey))
+            .unique();
+        if (existing) {
+            return { messageId: existing.messageId };
+        }
+    }
+    const messageId = newMessageId();
+    const deliverAt = now + (args.delaySeconds ?? 0) * 1000;
+    await ctx.db.insert("worldQueueMessages", {
+        orgId,
+        queueName: args.queueName,
+        messageId,
+        payloadJson: args.payloadJson,
+        idempotencyKey: args.idempotencyKey,
+        attempt: 0,
+        status: "pending",
+        deliverAt,
+        createdAt: now,
+        updatedAt: now,
+    });
+    return { messageId };
+}
+export async function getMessageById(ctx, args) {
+    return await ctx.db
+        .query("worldQueueMessages")
+        .withIndex("by_org_message", (q) => q.eq("orgId", args.orgId).eq("messageId", args.messageId))
+        .unique();
+}
+export async function settleMessageById(ctx, args) {
+    const doc = await getMessageById(ctx, args);
+    if (!doc)
+        return false;
+    await ctx.db.patch(doc._id, { status: args.status, updatedAt: Date.now() });
+    return true;
+}
+export async function setMessagePayload(ctx, args) {
+    const doc = await getMessageById(ctx, args);
+    if (!doc)
+        return false;
+    await ctx.db.patch(doc._id, { payloadJson: args.payloadJson, updatedAt: Date.now() });
+    return true;
+}
+export const enqueue = mutation({
+    args: {
+        orgId: v.string(),
+        queueName: v.string(),
+        payloadJson: v.string(),
+        idempotencyKey: v.optional(v.string()),
+        delaySeconds: v.optional(v.number()),
+    },
+    returns: v.object({ messageId: v.string() }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        return await enqueueMessage(ctx, { ...args, orgId });
+    },
+});
+export const claimNextForDelivery = mutation({
+    args: { orgId: v.string(), queueNamePrefix: v.string() },
+    returns: v.union(queueMessageResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const now = Date.now();
+        const candidates = await ctx.db
+            .query("worldQueueMessages")
+            .withIndex("by_org", (q) => q.eq("orgId", orgId))
+            .filter((q) => q.eq(q.field("status"), "pending"))
+            .collect();
+        const due = candidates
+            .filter((doc) => doc.queueName.startsWith(args.queueNamePrefix) && doc.deliverAt <= now)
+            .sort((a, b) => a.deliverAt - b.deliverAt || a.createdAt - b.createdAt);
+        const claim = due[0];
+        if (!claim) {
+            return null;
+        }
+        const attempt = claim.attempt + 1;
+        await ctx.db.patch(claim._id, { attempt, status: "claimed", updatedAt: now });
+        return {
+            messageId: claim.messageId,
+            queueName: claim.queueName,
+            payloadJson: claim.payloadJson,
+            idempotencyKey: claim.idempotencyKey,
+            attempt,
+            status: "claimed",
+            deliverAt: claim.deliverAt,
+            createdAt: claim.createdAt,
+            updatedAt: now,
+        };
+    },
+});
+export const markDelivered = mutation({
+    args: { orgId: v.string(), messageId: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldQueueMessages")
+            .withIndex("by_org_message", (q) => q.eq("orgId", orgId).eq("messageId", args.messageId))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            throw new Error("Queue message not found");
+        }
+        await ctx.db.patch(doc._id, { status: "delivered", updatedAt: Date.now() });
+        return null;
+    },
+});
+export const markFailedForRetry = mutation({
+    args: { orgId: v.string(), messageId: v.string(), delaySeconds: v.number() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldQueueMessages")
+            .withIndex("by_org_message", (q) => q.eq("orgId", orgId).eq("messageId", args.messageId))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            throw new Error("Queue message not found");
+        }
+        await ctx.db.patch(doc._id, {
+            status: "pending",
+            deliverAt: Date.now() + args.delaySeconds * 1000,
+            updatedAt: Date.now(),
+        });
+        return null;
+    },
+});
+export const getMessage = query({
+    args: { orgId: v.string(), messageId: v.string() },
+    returns: v.union(queueMessageResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldQueueMessages")
+            .withIndex("by_org_message", (q) => q.eq("orgId", orgId).eq("messageId", args.messageId))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            return null;
+        }
+        return {
+            messageId: doc.messageId,
+            queueName: doc.queueName,
+            payloadJson: doc.payloadJson,
+            idempotencyKey: doc.idempotencyKey,
+            attempt: doc.attempt,
+            status: doc.status,
+            deliverAt: doc.deliverAt,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        };
+    },
+});
+export const listPending = query({
+    args: { orgId: v.string(), queueNamePrefix: v.string() },
+    returns: v.array(queueMessageResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldQueueMessages")
+            .withIndex("by_org", (q) => q.eq("orgId", orgId))
+            .filter((q) => q.eq(q.field("status"), "pending"))
+            .collect();
+        return docs
+            .filter((doc) => doc.queueName.startsWith(args.queueNamePrefix))
+            .map((doc) => ({
+            messageId: doc.messageId,
+            queueName: doc.queueName,
+            payloadJson: doc.payloadJson,
+            idempotencyKey: doc.idempotencyKey,
+            attempt: doc.attempt,
+            status: doc.status,
+            deliverAt: doc.deliverAt,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        }));
+    },
+});

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

@@ -1,6 +1,6 @@
 export declare const resolveManifest: import("convex/server").RegisteredQuery<"public", {
     orgId: string;
-    sessionId: import("convex/values").GenericId<"sessions">;
+    sessionId: string;
 }, Promise<{
     agentId: import("convex/values").GenericId<"agents">;
     name: string;

package/dist/component/engine/resolvers.js

@@ -1,21 +1,9 @@
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// resolveManifest — the dynamic resolver (eve parity:
-// `dynamicInstructions`/`dynamicSkills`/`dynamicTools`,
-// packages/eve/src/compiler/manifest.ts:722-725). Produced FRESH from the
-// aggregate on every call, never compiled/cached — an agent edited between
-// sessions is visible on the very next `session.started`/`turn.started`
-// call with zero redeploy. `sessions.start` and `sessions.sendTurn` both
-// call this at their respective boundaries (ALLOWED_DYNAMIC_INSTRUCTION_
-// EVENTS, dynamic-tool-definition.ts:40-46).
-//
-// T2-QUINQUIES scope note: `toolApprovals` is included (in scope per
-// brief). `skills`/`connections` are NOT (out of scope for this pass — see
-// component/schema.ts SCOPE note); this resolver returns only what the
-// component boundary currently owns.
+import { agentIdOfRun, loadRun } from "./world.js";
 export const resolveManifest = query({
-    args: { orgId: v.string(), sessionId: v.id("sessions") },
+    args: { orgId: v.string(), sessionId: v.string() },
     returns: v.object({
         agentId: v.id("agents"),
         name: v.string(),
@@ -28,13 +16,13 @@ export const resolveManifest = query({
     }),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const session = await ctx.db.get(args.sessionId);
-        assertSameOrg(orgId, session, "Session not found");
-        const agent = await ctx.db.get(session.agentId);
+        const run = await loadRun(ctx, orgId, args.sessionId, "session", "Session not found");
+        const agentId = agentIdOfRun(ctx, run);
+        const agent = await ctx.db.get(agentId);
         assertSameOrg(orgId, agent, "Agent not found");
         const toolApprovals = await ctx.db
             .query("toolApprovals")
-            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", session.agentId))
+            .withIndex("by_org_agent", (q) => q.eq("orgId", orgId).eq("agentId", agentId))
             .collect();
         return {
             agentId: agent._id,

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

@@ -1,7 +1,7 @@
 export declare const startRun: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
-    workflowId: string;
     awaitedEventName: string;
+    workflowId: string;
     timeoutMs: number;
 }, Promise<import("convex/values").GenericId<"sandboxRuns">>>;
 export declare const attachSandboxId: import("convex/server").RegisteredMutation<"public", {
@@ -13,7 +13,7 @@ export declare const getStatus: import("convex/server").RegisteredQuery<"public"
     orgId: string;
     sandboxRunId: import("convex/values").GenericId<"sandboxRuns">;
 }, Promise<{
-    status: "completed" | "pending" | "failed" | "timedOut";
+    status: "completed" | "failed" | "pending" | "timedOut";
     resultSummary: string | undefined;
 }>>;
 export declare const deadLetterMalformed: import("convex/server").RegisteredMutation<"public", {

package/dist/component/engine/sandboxCallback.js

@@ -3,47 +3,8 @@ import { v } from "convex/values";
 import { components, internal } from "../_generated/api.js";
 import { internalMutation, mutation, query } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/sandboxCallback — THE SIGNED CALLBACK GATE'S DB-SIDE LOGIC.
-//
-// BOUNDARY (see the sandbox-bridge header in component/schema.ts for the
-// measured verdict behind each of these):
-//   - The public HTTP route (`/sandbox/callback`) that verifies the
-//     `SANDBOX_CALLBACK_SECRET` HMAC signature over the raw body CANNOT
-//     live in this component (no official `@convex-dev/*` component ships
-//     an `http.ts`, and none reads `process.env` directly). It stays in
-//     the consumer app's `convex/http.ts`, which reads the secret, verifies
-//     the signature, and ONLY THEN calls `processCallback` /
-//     `deadLetterMalformed` below.
-//   - The "use node" action that talks to `@vercel/sandbox`
-//     (`Sandbox.create()` / `sandbox.runCommand()`) CANNOT live in this
-//     component either (Convex's own bundler hard-crashes on any "use
-//     node" file inside a child component). It stays app-level
-//     and calls INTO `startRun` / `attachSandboxId` below (both PUBLIC
-//     `mutation`s, not `internalMutation`s, precisely so a cross-component
-//     caller can reach them — a component's `internal*` functions are
-//     unreachable from outside the component; engine/mandates.ts's
-//     `spendInternal` follows the same convention).
-//
-// Everything below assumes the signature already checked out (verified by
-// the caller, upstream of this module) — this module's job is dedup-by-
-// delivery-id + the actual wake, both inside ONE mutation transaction so a
-// replayed delivery can never cause a second `sendEvent`. `orgId` is an
-// explicit ARGUMENT on every public function (component boundaries do not
-// propagate `ctx.auth`, see component/lib/auth.ts).
-//
-// Same WorkflowManager component as engine/wakeup.ts / engine/workflows.ts.
 const workflow = new WorkflowManager(components.workflow);
 const wakeStatus = v.union(v.literal("completed"), v.literal("failed"));
-// startRun — the DB-side half of launching a sandbox run (called by the
-// app-level "use node" action, convex/engine/sandboxBridgeActions.ts,
-// AFTER `engine.mandates.spend` has funded it, same two-transaction
-// protocol as `engine.wakeup.enqueue`). Returns the row id so the caller
-// can inject it into the sandbox's own env (SANDBOX_RUN_ID) before
-// `Sandbox.create()`, and schedules the self-built awaitEvent timeout
-// (workflow#177 pattern, same discipline as engine/awaitEventTimeout.ts)
-// so a sandbox that never calls back — killed by the platform's own
-// ceiling, crashed, or just lost — still wakes the workflow, in FAILURE,
-// rather than leaving it asleep forever.
 export const startRun = mutation({
     args: {
         orgId: v.string(),
@@ -68,7 +29,7 @@ export const startRun = mutation({
             orgId,
             workflowId: args.workflowId,
             awaitedEventName: args.awaitedEventName,
-            sandboxId: "", // patched by attachSandboxId once Sandbox.create() resolves
+            sandboxId: "",
             status: "pending",
             createdAt: now,
             updatedAt: now,
@@ -79,10 +40,6 @@ export const startRun = mutation({
         return runId;
     },
 });
-// attachSandboxId — patches the Vercel-assigned sandbox id onto the row
-// once `Sandbox.create()` returns it. Separate step because the row must
-// exist BEFORE the sandbox is created (its id is one of the sandbox's own
-// env vars, so the sandbox can name itself in its callback payload).
 export const attachSandboxId = mutation({
     args: { orgId: v.string(), sandboxRunId: v.id("sandboxRuns"), sandboxId: v.string() },
     returns: v.null(),
@@ -100,8 +57,6 @@ export const attachSandboxId = mutation({
         return null;
     },
 });
-// getStatus — client-facing read, same org-isolation discipline as every
-// other status query in this engine.
 export const getStatus = query({
     args: { orgId: v.string(), sandboxRunId: v.id("sandboxRuns") },
     returns: v.object({
@@ -115,14 +70,6 @@ export const getStatus = query({
         return { status: row.status, resultSummary: row.resultSummary };
     },
 });
-// deadLetterMalformed — reached from the consumer app's `convex/http.ts`
-// when a SIGNATURE-VALID request's body is not valid JSON or is missing
-// required fields. The signature already proved the caller holds the
-// shared secret, so this is not a security refusal (that already happened
-// upstream, in the app's own HTTP route, before this ever runs) — it is a
-// shape problem worth a human's attention, recorded rather than dropped.
-// `orgId` is optional: the payload may not have parsed far enough to know
-// which org this delivery even claims to belong to.
 export const deadLetterMalformed = mutation({
     args: {
         orgId: v.optional(v.string()),
@@ -142,15 +89,6 @@ export const deadLetterMalformed = mutation({
         return null;
     },
 });
-// processCallback — THE WAKE, reached ONLY from the consumer app's
-// `convex/http.ts` AFTER signature verification. `deliveryId` dedup is the
-// FIRST read in this transaction, and the "woke" delivery row is inserted
-// in the SAME transaction as the `sendEvent` call — Convex mutations are
-// single transactions, so there is no window in which two concurrent
-// replays of the same `deliveryId` could both observe "not yet delivered"
-// and both wake the workflow. A delivery whose signature verified but
-// whose `sandboxRunId` is unknown, cross-org, or already resolved is
-// DEAD-LETTERED rather than silently dropped or blindly retried.
 export const processCallback = mutation({
     args: {
         deliveryId: v.string(),
@@ -167,7 +105,6 @@ export const processCallback = mutation({
         if (args.deliveryId.length === 0) {
             throw new Error("Validation: deliveryId must not be empty");
         }
-        // Dedup FIRST, inside this same transaction.
         const existingDelivery = await ctx.db
             .query("sandboxCallbackDeliveries")
             .withIndex("by_org_delivery", (q) => q.eq("orgId", orgId).eq("deliveryId", args.deliveryId))
@@ -188,10 +125,6 @@ export const processCallback = mutation({
             return { outcome: "dead-lettered" };
         }
         if (run.status !== "pending") {
-            // Already resolved (completed/failed/timedOut) — a signature-valid
-            // callback for a run that is no longer pending is not a legitimate
-            // second wake; record it for human inspection instead of firing
-            // sendEvent again or throwing an unreadable error.
             await ctx.db.insert("sandboxCallbackDeadLetters", {
                 orgId,
                 deliveryId: args.deliveryId,
@@ -222,23 +155,13 @@ export const processCallback = mutation({
         return { outcome: "woke" };
     },
 });
-// timeoutInternal — the self-built awaitEvent timeout (workflow#177
-// pattern, same discipline as engine/awaitEventTimeout.ts), scoped to a
-// sandbox run rather than a session. INTERNAL: reached only via
-// `ctx.scheduler.runAfter` from `startRun` above, inside this SAME
-// component — never a cross-component call, so `internalMutation` is
-// correct here (unlike `startRun`/`attachSandboxId`/`processCallback`/
-// `deadLetterMalformed`, which must be reachable from outside). Fires ONLY
-// if the run is still "pending" when the deadline arrives (idempotent
-// against a callback that lands in the same tick); wakes the workflow in a
-// CLEAN FAILURE, not a silent hang.
 export const timeoutInternal = internalMutation({
     args: { sandboxRunId: v.id("sandboxRuns") },
     returns: v.null(),
     handler: async (ctx, args) => {
         const run = await ctx.db.get(args.sandboxRunId);
         if (!run || run.status !== "pending") {
-            return null; // already resolved by a real callback, or row gone
+            return null;
         }
         await ctx.db.patch(run._id, {
             status: "timedOut",

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

@@ -0,0 +1,9 @@
+export declare const getBoxId: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+}, Promise<string | null>>;
+export declare const setBoxId: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    agentId: import("convex/values").GenericId<"agents">;
+    boxId: string;
+}, Promise<null>>;