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

package/dist/component/schema.js

@@ -65,8 +65,13 @@ export default defineSchema({
     agents: defineTable({
         orgId: v.string(),
         name: v.string(),
+        description: v.optional(v.string()), // eve: agent-definition.ts:291
         instructions: v.string(),
         model: v.string(),
+        reasoningEffort: v.optional(v.union(v.literal("none"), v.literal("low"), v.literal("medium"), v.literal("high"))), // eve: agent-definition.ts:315-319
+        modelProvider: v.optional(v.union(v.literal("gateway"), v.literal("openrouter"))), // notre ligne (BYOK, mvp §2.3); optional here to stay additive/backwards-compatible with rows created before this field existed
+        maxSubagents: v.optional(v.number()), // eve: agent-definition.ts:163-179, défaut 100
+        maxInputTokensPerSession: v.optional(v.union(v.number(), v.literal(false))), // eve: :195, false = illimité
         status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
         createdBy: v.string(),
         createdAt: v.number(),
@@ -99,11 +104,19 @@ export default defineSchema({
     // with its own step function. This is a deliberate divergence ("notre
     // ligne") from the app-level prototype, narrowing the shipped surface to
     // what has a working component-level test harness behind it.
+    // C1.5 ("notre ligne", measured trou fixed): sessions ARE now piloted by
+    // a versioned `@convex-dev/workflow` run (component/engine/workflows.ts:
+    // sessionWorkflowV1) -- the divergence note above (T2-QUINQUIES,
+    // "deliberately does NOT tie a session to a workflow run") is retired.
+    // `workflowId`/`workflowVersion` are optional so pre-C1.5 rows (written
+    // before this migration) remain valid without a backfill.
     sessions: defineTable({
         orgId: v.string(),
         agentId: v.id("agents"),
         status: v.union(v.literal("running"), v.literal("completed"), v.literal("cancelled")),
         createdBy: v.string(),
+        workflowId: v.optional(v.string()),
+        workflowVersion: v.optional(v.string()),
         createdAt: v.number(),
         updatedAt: v.number(),
     })
@@ -128,10 +141,349 @@ export default defineSchema({
         // a denied tool call had no event of its own -- a consumer had no
         // way to tell "refused this turn" from "skipped, turn completed
         // anyway", which is the wrong default Hestia had to code around.
-        v.literal("turn.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved")),
+        v.literal("turn.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved"), 
+        // C2 — blank event auto-inserted by `engine/awaitEventTimeout.fire`
+        // (workflow#177: Convex provides no native timeout for
+        // `step.awaitEvent`). See component/engine/awaitEventTimeout.ts.
+        v.literal("sandbox.timeout")),
         payload: v.optional(v.string()), // JSON-serialized, free contract per event name
         createdAt: v.number(),
     })
         .index("by_org", ["orgId"])
         .index("by_org_session", ["orgId", "sessionId"]),
+    // ---------------------------------------------------------------------
+    // C2 — WAKE-UP WITHOUT POLLING (I2, SYNTHESE.md §5). Ported from
+    // convex/schema.ts (repo-root prototype); table shapes are byte-identical
+    // to their app-level source. See component/engine/wakeup.ts and
+    // component/engine/awaitEventTimeout.ts for the mechanism itself.
+    // ---------------------------------------------------------------------
+    // wakeableWork — GENERIC wake-up primitive. `enqueue` puts caller-supplied
+    // work (an action, referenced by an opaque function-handle string) into a
+    // dedicated `@convex-dev/workpool`; that pool's `onComplete` callback
+    // calls `workflow.sendEvent(...)` against the CALLER-supplied
+    // `workflowId` the instant the work resolves — success, failure, OR
+    // cancellation alike. Zero setInterval, zero cron.
+    wakeableWork: defineTable({
+        orgId: v.string(),
+        workflowId: v.string(), // target: the workflow parked on step.awaitEvent
+        awaitedEventName: v.string(), // event name that workflow is awaiting
+        workId: v.string(), // @convex-dev/workpool WorkId, opaque string
+        status: v.union(v.literal("pending"), v.literal("completed"), // work succeeded
+        v.literal("failed"), // work threw
+        v.literal("cancelled")),
+        resultSummary: v.optional(v.string()), // error message when status=="failed"
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_workflow", ["orgId", "workflowId"]),
+    // awaitEventTimeouts — self-built timeout for `step.awaitEvent`
+    // (workflow#177: "Convex does not provide a native timeout for
+    // awaitEvent"). A scheduled mutation (`ctx.scheduler.runAfter`) fires a
+    // blank `sandbox.timeout` sessionEvent if the awaited event never arrives
+    // before `deadlineAt`.
+    awaitEventTimeouts: defineTable({
+        orgId: v.string(),
+        sessionId: v.id("sessions"),
+        awaitedEventName: v.string(),
+        deadlineAt: v.number(),
+        // optional: patched right after insert, once the scheduled function
+        // itself has been created (it needs this row's id as its argument).
+        scheduledFunctionId: v.optional(v.id("_scheduled_functions")),
+        firedAt: v.optional(v.number()),
+        cancelledAt: v.optional(v.number()),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_session", ["orgId", "sessionId"]),
+    // wakeupDemoResults — TEST-ONLY fixture, see
+    // component/testFixtures/wakeupDemoWorkflow.ts. Not part of the public
+    // contract; a reference recipient workflow parked on `step.awaitEvent`
+    // patches `wokenAt`/`observedStatus` here ONLY after
+    // `engine/wakeup.onWorkComplete` has called `sendEvent` -- its presence
+    // is the test-observable proof that the wake mechanism (not a poll)
+    // resumed the workflow. Same discipline as `callerStepInvocations` above.
+    wakeupDemoResults: defineTable({
+        orgId: v.string(),
+        enqueuedAt: v.number(),
+        wokenAt: v.optional(v.number()),
+        observedStatus: v.optional(v.union(v.literal("completed"), v.literal("failed"), v.literal("cancelled"))),
+        observedResultSummary: v.optional(v.string()),
+    }).index("by_org", ["orgId"]),
+    // ---------------------------------------------------------------------
+    // C3 — MANDATES: "notre ligne" (autorité bornée, SYNTHESE §2/§4.e-ter).
+    // Ported from convex/schema.ts (repo-root prototype, lines 168-214);
+    // table shapes are byte-identical to their app-level source. See
+    // component/engine/mandates.ts and component/engine/wakeup.ts (the C3
+    // seam: `enqueue` now funds through `mandates.spendInternal` before any
+    // work can enter the wakeup pool).
+    // ---------------------------------------------------------------------
+    // mandates — a plafond is a DATA row scoped by orgId + agentId + scope,
+    // never a constant read from code. `kind`/`rate`/`period`/`capacity` are
+    // the inline contract of @convex-dev/rate-limiter ("dynamic config"): the
+    // COST (`count`) is a WEIGHTED count (tokens/euros/calls), never a plain
+    // call counter. Changing a cap is a row mutation, never a deployment.
+    mandates: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        scope: v.string(), // free-form business name (e.g. "llm-tokens") -- DATA, not a constant
+        kind: v.union(v.literal("token bucket"), v.literal("fixed window")),
+        rate: v.number(),
+        period: v.number(), // ms
+        capacity: v.optional(v.number()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"])
+        .index("by_org_agent_scope", ["orgId", "agentId", "scope"]),
+    // approvalRequests — created whenever a mandate is exceeded. NEVER a
+    // silent bypass: an overrun always becomes a persisted HUMAN approval
+    // request, never a silent refusal with no trace.
+    approvalRequests: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        scope: v.string(),
+        requestedCost: v.number(),
+        reason: v.string(),
+        status: v.union(v.literal("pending"), v.literal("approved"), v.literal("denied")),
+        createdAt: v.number(),
+        resolvedAt: v.optional(v.number()),
+        resolvedBy: v.optional(v.string()),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"])
+        .index("by_org_status", ["orgId", "status"]),
+    // ---------------------------------------------------------------------
+    // C4 — HABITS: "notre ligne" (une habitude = un cron DYNAMIQUE par
+    // agent/org, SYNTHESE §2/§4.e-ter: "ce qui transforme un chat en
+    // employé"). Ported from convex/schema.ts (repo-root prototype, lines
+    // 108-124 / 210-217); table shapes are byte-identical to their app-level
+    // source. See component/engine/habits.ts (the C4 seam: `crons` is a new
+    // sub-component of THIS component, registered in component/convex.config.ts).
+    // ---------------------------------------------------------------------
+    // habits — a schedule is a DATA row scoped by orgId + agentId, never a
+    // constant read from a deployed `convex/crons.ts`. `cronExpression` is
+    // the DATA that drives the runtime cron registered via
+    // `@convex-dev/crons`; create/updateSchedule/enable/disable never
+    // redeploy anything.
+    habits: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        name: v.string(),
+        cronExpression: v.string(),
+        prompt: v.string(),
+        enabled: v.boolean(),
+        // id of the runtime-registered @convex-dev/crons job, present only
+        // while `enabled` is true (cleared by `disable`, reassigned by
+        // `enable` / `updateSchedule` -- no redeploy involved in any transition).
+        cronJobId: v.optional(v.string()),
+        lastRunAt: v.optional(v.number()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"]),
+    // habitRuns — proof of execution of a habit (MUST_PASS/MUST_BLOCK probe,
+    // component/habits.componentPackaging.test.ts). Every tick of the runtime
+    // cron registered via @convex-dev/crons writes a row here -- this is what
+    // makes "fires its first run without a deploy" PROVABLE rather than
+    // asserted on trust.
+    habitRuns: defineTable({
+        orgId: v.string(),
+        habitId: v.id("habits"),
+        agentId: v.id("agents"),
+        ranAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_habit", ["orgId", "habitId"]),
+    // ---------------------------------------------------------------------
+    // C5 — SANDBOX BRIDGE (I5, SYNTHESE.md §4.c-d: "le pont pause/réveil vers
+    // le bac à sable ET vers la délégation entre agents, même mécanisme").
+    // Ported from convex/schema.ts (repo-root prototype, sandboxRuns /
+    // sandboxCallbackDeliveries / sandboxCallbackDeadLetters); table shapes
+    // are byte-identical to their app-level source. See
+    // component/engine/sandboxCallback.ts.
+    //
+    // NOTRE LIGNE (frontière, C5 recherche-d'abord): the "use node" action
+    // that actually talks to `@vercel/sandbox` (convex/engine/
+    // sandboxBridgeActions.ts) CANNOT be ported into this component — the
+    // Convex CLI's own component bundler HARD-CRASHES on any "use node" file
+    // found in a child component directory ("use node directive is not
+    // supported in components", node_modules/convex/dist/cjs/cli/lib/
+    // components/definition/bundle.js). It stays app-level and calls INTO
+    // this component's public `engine.sandboxCallback.startRun` /
+    // `attachSandboxId` (and `engine.mandates.spend`) instead. Likewise, no
+    // official `@convex-dev/*` component ships an `http.ts` or reads
+    // `process.env` directly (measured: zero hits across all 7 installed
+    // `@convex-dev/*` component dist trees) — the signed callback's public
+    // HTTP route (`/sandbox/callback`) and its `SANDBOX_CALLBACK_SECRET`
+    // read + HMAC verification stay in the CONSUMER app's `convex/http.ts`,
+    // which delegates to this component's public
+    // `engine.sandboxCallback.processCallback` /
+    // `engine.sandboxCallback.deadLetterMalformed` ONLY after the signature
+    // has already checked out.
+    sandboxConfig: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        provider: v.literal("vercel-sandbox"),
+        image: v.optional(v.string()),
+        timeoutSeconds: v.number(),
+        egressPolicy: v.union(v.literal("allow-all"), v.literal("deny-all-allowlist")),
+        allowlistDomains: v.array(v.string()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"]),
+    sandboxRuns: defineTable({
+        orgId: v.string(),
+        workflowId: v.string(), // target: the workflow parked on step.awaitEvent
+        awaitedEventName: v.string(), // event name that workflow is awaiting
+        sandboxId: v.string(), // Vercel Sandbox id (opaque, from Sandbox.create())
+        status: v.union(v.literal("pending"), v.literal("completed"), v.literal("failed"), v.literal("timedOut")),
+        resultSummary: v.optional(v.string()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_workflow", ["orgId", "workflowId"])
+        .index("by_org_sandbox", ["orgId", "sandboxId"]),
+    sandboxCallbackDeliveries: defineTable({
+        orgId: v.string(),
+        sandboxRunId: v.id("sandboxRuns"),
+        deliveryId: v.string(), // caller-supplied, opaque, unique per attempt-family
+        outcome: v.union(v.literal("woke"), // first valid delivery for this id -- sendEvent fired
+        v.literal("duplicate")),
+        receivedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_delivery", ["orgId", "deliveryId"])
+        .index("by_org_run", ["orgId", "sandboxRunId"]),
+    sandboxCallbackDeadLetters: defineTable({
+        orgId: v.optional(v.string()), // absent when the payload itself couldn't be parsed
+        deliveryId: v.string(),
+        reason: v.string(),
+        rawBody: v.string(),
+        createdAt: v.number(),
+    }).index("by_org", ["orgId"]),
+    // ---------------------------------------------------------------------
+    // C6 — DELEGATION + VP CONNECTION (I6, SYNTHESE.md §4.d: "un agent qui
+    // délègue à un autre agent = LE MÊME système pause/réveil que le pont
+    // sandbox -- un seul système à écrire, pas deux"). Ported from
+    // convex/schema.ts (repo-root prototype, lines 74-91 / 377-467); table
+    // shapes are byte-identical to their app-level source. See
+    // component/engine/delegation.ts and component/engine/vpConnection.ts
+    // (the C6 seam: both terminate delegation/clone paths in exactly one call
+    // to THIS component's own `engine/wakeup.enqueue`, C2/C3's public action,
+    // never a second onComplete/sendEvent path).
+    // ---------------------------------------------------------------------
+    // subagents — declared subagents, RECURSIVE (the child is a full
+    // `agents` row with its own aggregate). Isolation is by construction
+    // (eve.dev/docs/subagents: "inherits nothing from the root's authored
+    // slots") -- this table ONLY declares the parent->child link and exposes
+    // it as a named tool; it never copies a single field out of the child's
+    // own skills/connections/toolApprovals onto the parent.
+    subagents: defineTable({
+        orgId: v.string(),
+        parentAgentId: v.id("agents"),
+        childAgentId: v.id("agents"), // full agent, own aggregate -- strict isolation
+        toolName: v.string(),
+        description: v.optional(v.string()),
+        enabled: v.boolean(),
+        createdAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_parent", ["orgId", "parentAgentId"])
+        .index("by_org_child", ["orgId", "childAgentId"])
+        // I6 build-time collision guard (engine/delegation.declareSubagent):
+        // exact-match lookup of an existing (parent, toolName) pair, no filter().
+        .index("by_org_parent_tool", ["orgId", "parentAgentId", "toolName"]),
+    // delegationRuns — one row per A->B delegation through a declared
+    // subagent (`subagents` table above). `workflowId`/`awaitedEventName` are
+    // the SAME two fields `engine/wakeup.enqueue` already threads through to
+    // `workflow.sendEvent` -- this table records WHICH delegation a given
+    // `wakeableWork` row belongs to; it never duplicates the wake mechanism
+    // itself (no second onComplete/sendEvent path exists anywhere in this
+    // engine).
+    delegationRuns: defineTable({
+        orgId: v.string(),
+        parentAgentId: v.id("agents"),
+        childAgentId: v.id("agents"),
+        toolName: v.string(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        status: v.union(v.literal("pending"), v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+        resultSummary: v.optional(v.string()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_parent", ["orgId", "parentAgentId"])
+        .index("by_org_workflow", ["orgId", "workflowId"])
+        .index("by_org_awaitedEvent", ["orgId", "awaitedEventName"]),
+    // agentCloneRuns — I6 built-in `agent` tool (eve.dev/docs/subagents: "the
+    // built-in `agent` tool clones the ROOT, root-only, NOT recursive -- it
+    // cannot call itself"). `viaAgentTool` is the recursion guard: a clone
+    // invocation started BY a clone invocation (viaAgentTool: true passed in)
+    // is refused at `engine/delegation.invokeAgentClone` BEFORE any row here
+    // is written -- so every row in this table by construction has
+    // `viaAgentTool === false` on entry. Wakes through the SAME
+    // `engine/wakeup.enqueue` mechanism as `delegationRuns`.
+    agentCloneRuns: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"), // the root being cloned
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        status: v.union(v.literal("pending"), v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+        resultSummary: v.optional(v.string()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"]),
+    // vpConnections — I6 (mvp-evevantage.md §2.2 "Travail d'équipe"). The
+    // four VantagePeers tools (memory, tasks, messages, notes) wired as a
+    // CONNECTION of the agent aggregate, notre ligne. 0..1 row per agent;
+    // absence means "use the defaults" (all four ON) -- see
+    // `engine/vpConnection.ts:defaultToggles`. DIRECT access: invocation
+    // goes through a caller-supplied Convex function handle
+    // (`createFunctionHandle`, same discipline as `wakeableWork.workId` /
+    // `durableJobs.stepFunctionHandle`), never a `fetch()` call.
+    vpConnections: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        memoryEnabled: v.boolean(),
+        tasksEnabled: v.boolean(),
+        messagesEnabled: v.boolean(),
+        notesEnabled: v.boolean(),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"]),
+    // vpToolInvocations — audit trail of every VantagePeers tool call an
+    // agent made, ALWAYS written by `engine/vpConnection.invokeVpTool` in the
+    // SAME transaction family as the call itself.
+    vpToolInvocations: defineTable({
+        orgId: v.string(),
+        agentId: v.id("agents"),
+        tool: v.union(v.literal("memory"), v.literal("tasks"), v.literal("messages"), v.literal("notes")),
+        createdAt: v.number(),
+    })
+        .index("by_org", ["orgId"])
+        .index("by_org_agent", ["orgId", "agentId"]),
+    // vpTenantFixture — TEST-ONLY stand-in for "VantagePeers' own tenant
+    // table" (component/testFixtures/vpTool.ts). This engine never owns
+    // VantagePeers' schema (component isolation) -- this fixture plays the
+    // CALLER-side function a real `vpFunctionHandle` would point to, so
+    // `component/engine/vpConnection.test.ts` can prove a VP tool write
+    // lands in the invoking agent's own org tenant (and that a mismatched
+    // orgId is refused) without needing a second real Convex deployment in
+    // the test harness. Not part of the public contract.
+    vpTenantFixture: defineTable({
+        orgId: v.string(),
+        tool: v.union(v.literal("memory"), v.literal("tasks"), v.literal("messages"), v.literal("notes")),
+        argsJson: v.string(),
+        createdAt: v.number(),
+    }).index("by_org", ["orgId"]),
 });

package/dist/component/testFixtures/delegationDemoWorkflow.d.ts

@@ -0,0 +1,18 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+export declare const workflow: WorkflowManager;
+export declare const start: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    awaitedEventName: string;
+}, Promise<{
+    workflowId: string;
+}>>;
+export declare const delegationDemoWorkflowV1: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
+    orgId: import("convex/values").VString<string, "required">;
+    awaitedEventName: import("convex/values").VString<string, "required">;
+}>, import("@convex-dev/workflow").WorkflowId>;
+export declare const recordDelegationResolvedByEventInternal: import("convex/server").RegisteredMutation<"internal", {
+    resultSummary?: string | undefined;
+    orgId: string;
+    status: "completed" | "cancelled" | "failed";
+    awaitedEventName: string;
+}, Promise<null>>;

package/dist/component/testFixtures/delegationDemoWorkflow.js

@@ -0,0 +1,76 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import { v } from "convex/values";
+import { components, internal } from "../_generated/api.js";
+import { internalMutation, mutation } from "../_generated/server.js";
+import { requireOrgId } from "../lib/auth.js";
+// testFixtures/delegationDemoWorkflow — TEST-ONLY reference PARENT-side
+// recipient for delegation (C6), ported from
+// convex/engine/delegationDemoWorkflow.ts. This is exactly the "bespoke
+// workflow" shape `engine/wakeup.ts`'s own comment describes ("any
+// workflow -- a session, a durable job, or a bespoke one -- can be the wake
+// target"): it parks on `step.awaitEvent` and, once
+// `engine.wakeup.onWorkComplete` fires `sendEvent` (via
+// `engine.delegation.delegateToSubagent` -> `engine.wakeup.enqueue`, the
+// SAME public action C2/C3 ships), it patches the SAME `delegationRuns`
+// row `delegateToSubagent` created -- proving A paused and was woken by
+// B's completion, with zero polling.
+export const workflow = new WorkflowManager(components.workflow);
+export const start = mutation({
+    args: { orgId: v.string(), awaitedEventName: v.string() },
+    returns: v.object({ workflowId: v.string() }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const workflowId = await workflow.start(ctx, internal.testFixtures.delegationDemoWorkflow.delegationDemoWorkflowV1, { orgId, awaitedEventName: args.awaitedEventName });
+        return { workflowId };
+    },
+});
+export const delegationDemoWorkflowV1 = workflow.define({
+    args: { orgId: v.string(), awaitedEventName: v.string() },
+    returns: v.null(),
+    handler: async (step, args) => {
+        // A pauses here. Resumes ONLY when engine.wakeup.onWorkComplete calls
+        // sendEvent with this exact name -- no loop, no timer.
+        const result = await step.awaitEvent({
+            name: args.awaitedEventName,
+            validator: v.object({
+                status: v.union(v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+                resultSummary: v.optional(v.string()),
+            }),
+        });
+        await step.runMutation(internal.testFixtures.delegationDemoWorkflow.recordDelegationResolvedByEventInternal, {
+            orgId: args.orgId,
+            awaitedEventName: args.awaitedEventName,
+            status: result.status,
+            resultSummary: result.resultSummary,
+        });
+        return null;
+    },
+});
+// recordDelegationResolvedByEventInternal — looks up the delegationRuns row
+// created for THIS (orgId, awaitedEventName) pair via `by_org_awaitedEvent`
+// (no `.filter()`) and patches it. Kept as one mutation (rather than two
+// round trips from the workflow step) so the lookup and patch land in the
+// same transaction.
+export const recordDelegationResolvedByEventInternal = internalMutation({
+    args: {
+        orgId: v.string(),
+        awaitedEventName: v.string(),
+        status: v.union(v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+        resultSummary: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const row = await ctx.db
+            .query("delegationRuns")
+            .withIndex("by_org_awaitedEvent", (q) => q.eq("orgId", args.orgId).eq("awaitedEventName", args.awaitedEventName))
+            .first();
+        if (!row)
+            return null;
+        await ctx.db.patch(row._id, {
+            status: args.status,
+            resultSummary: args.resultSummary,
+            updatedAt: Date.now(),
+        });
+        return null;
+    },
+});

package/dist/component/testFixtures/sandboxDemoWorkflow.d.ts

@@ -0,0 +1,19 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import type { Id } from "../_generated/dataModel.js";
+export declare const workflow: WorkflowManager;
+export declare const start: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    awaitedEventName: string;
+}, Promise<{
+    workflowId: string;
+    resultId: Id<"wakeupDemoResults">;
+}>>;
+export declare const recordWokenInternal: import("convex/server").RegisteredMutation<"internal", {
+    resultSummary?: string | undefined;
+    status: "completed" | "failed";
+    resultId: import("convex/values").GenericId<"wakeupDemoResults">;
+}, Promise<null>>;
+export declare const sandboxDemoWorkflowV1: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
+    resultId: import("convex/values").VId<import("convex/values").GenericId<"wakeupDemoResults">, "required">;
+    awaitedEventName: import("convex/values").VString<string, "required">;
+}>, import("@convex-dev/workflow").WorkflowId>;

package/dist/component/testFixtures/sandboxDemoWorkflow.js

@@ -0,0 +1,69 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import { v } from "convex/values";
+import { components, internal } from "../_generated/api.js";
+import { internalMutation, mutation } from "../_generated/server.js";
+import { requireOrgId } from "../lib/auth.js";
+// testFixtures/sandboxDemoWorkflow — TEST-ONLY reference recipient for the
+// C5 sandbox bridge, ported from convex/engine/sandboxDemoWorkflow.ts, same
+// shape/role as testFixtures/wakeupDemoWorkflow.ts (C2). A real consumer's
+// own workflow parks on `step.awaitEvent({ name: <awaitedEventName passed
+// to engine/sandboxCallback.startRun> })` and does nothing else. Proves
+// (component/sandboxCallback.componentPackaging.test.ts) the ONLY way this
+// resumes is a signed, deduplicated callback reaching
+// `engine/sandboxCallback.processCallback` (or the self-built timeout) --
+// no poll, no interval, no direct call.
+export const workflow = new WorkflowManager(components.workflow);
+export const start = mutation({
+    args: { orgId: v.string(), awaitedEventName: v.string() },
+    returns: v.object({
+        workflowId: v.string(),
+        resultId: v.id("wakeupDemoResults"),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        // Reuses wakeupDemoResults -- same test-observation shape (enqueuedAt /
+        // wokenAt / observedStatus), decoupled from the wake-up-pool path by
+        // definition since nothing here touches wakeableWork.
+        const resultId = await ctx.db.insert("wakeupDemoResults", { orgId, enqueuedAt: Date.now() });
+        const workflowId = await workflow.start(ctx, internal.testFixtures.sandboxDemoWorkflow.sandboxDemoWorkflowV1, { resultId, awaitedEventName: args.awaitedEventName });
+        return { workflowId, resultId };
+    },
+});
+export const recordWokenInternal = internalMutation({
+    args: {
+        resultId: v.id("wakeupDemoResults"),
+        status: v.union(v.literal("completed"), v.literal("failed")),
+        resultSummary: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.db.patch(args.resultId, {
+            wokenAt: Date.now(),
+            observedStatus: args.status,
+            observedResultSummary: args.resultSummary,
+        });
+        return null;
+    },
+});
+export const sandboxDemoWorkflowV1 = workflow.define({
+    args: { resultId: v.id("wakeupDemoResults"), awaitedEventName: v.string() },
+    returns: v.null(),
+    handler: async (step, args) => {
+        // Blocks here -- resumes ONLY when a signed, non-duplicate sandbox
+        // callback (or the self-built timeout) calls `workflow.sendEvent` with
+        // this exact name. No loop, no timer polling this workflow's state.
+        const result = await step.awaitEvent({
+            name: args.awaitedEventName,
+            validator: v.object({
+                status: v.union(v.literal("completed"), v.literal("failed")),
+                resultSummary: v.optional(v.string()),
+            }),
+        });
+        await step.runMutation(internal.testFixtures.sandboxDemoWorkflow.recordWokenInternal, {
+            resultId: args.resultId,
+            status: result.status,
+            resultSummary: result.resultSummary,
+        });
+        return null;
+    },
+});

package/dist/component/testFixtures/vpTool.d.ts

@@ -0,0 +1,4 @@
+export declare const writeToTenant: import("convex/server").RegisteredMutation<"internal", {
+    orgId: string;
+    argsJson: string;
+}, Promise<null>>;

package/dist/component/testFixtures/vpTool.js

@@ -0,0 +1,25 @@
+import { v } from "convex/values";
+import { internalMutation } from "../_generated/server.js";
+// testFixtures/vpTool — stand-in for a VantagePeers-owned mutation reached
+// via `createFunctionHandle` (same discipline as testFixtures/wakeupWork.ts
+// and durableJob's caller-step fixtures). Ported from
+// convex/testFixtures/vpTool.ts. This engine never owns VantagePeers'
+// schema, so its own `vpTenantFixture` table plays the role of "VP's own
+// tenant table" for `component/engine/vpConnection.test.ts`). Writes
+// EXACTLY the orgId it was handed -- it does not derive one from
+// `ctx.auth` -- so the caller (`engine.vpConnection.invokeVpTool`) is what
+// determines tenant isolation, which is precisely the property under test.
+export const writeToTenant = internalMutation({
+    args: { orgId: v.string(), argsJson: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const parsed = JSON.parse(args.argsJson);
+        await ctx.db.insert("vpTenantFixture", {
+            orgId: args.orgId,
+            tool: parsed.tool,
+            argsJson: args.argsJson,
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});

package/dist/component/testFixtures/wakeupDemoWorkflow.d.ts

@@ -0,0 +1,19 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import type { Id } from "../_generated/dataModel.js";
+export declare const workflow: WorkflowManager;
+export declare const start: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    awaitedEventName: string;
+}, Promise<{
+    workflowId: string;
+    resultId: Id<"wakeupDemoResults">;
+}>>;
+export declare const recordWokenInternal: import("convex/server").RegisteredMutation<"internal", {
+    resultSummary?: string | undefined;
+    status: "completed" | "cancelled" | "failed";
+    resultId: import("convex/values").GenericId<"wakeupDemoResults">;
+}, Promise<null>>;
+export declare const wakeupDemoWorkflowV1: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
+    resultId: import("convex/values").VId<import("convex/values").GenericId<"wakeupDemoResults">, "required">;
+    awaitedEventName: import("convex/values").VString<string, "required">;
+}>, import("@convex-dev/workflow").WorkflowId>;