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

package/dist/component/schema.js

@@ -8,8 +8,8 @@ import { v } from "convex/values";
 // root, which only backs THIS repo's own dev/test deployment.
 //
 // SCOPE (T2-QUATER: durableJob only. T2-QUINQUIES, this pass: WIDENS the
-// boundary to the SESSIONS surface Hestia's EveVantage V4 conversation
-// thread needs — session start/turn, streamed reasoning/tool-call events,
+// boundary to the SESSIONS surface a downstream conversation-thread
+// consumer needs — session start/turn, streamed reasoning/tool-call events,
 // toolApprovals response, replay on reconnect, dynamic resolver — see
 // README "What's callable"). Still DELIBERATELY NARROW: `skills`,
 // `connections`, `subagents`, `habits`, `sandboxConfig`, `modelKeys`,
@@ -20,10 +20,8 @@ import { v } from "convex/values";
 // can read (component isolation: this package cannot read a consumer app's
 // OWN `agents` table across the component boundary).
 export default defineSchema({
-    // durableJobs — GENERIC durable step-batch primitive (I1, SYNTHESE.md
-    // §5/§7). See convex/engine/durableJob.ts (repo root) for the full
-    // contract description; this table definition is byte-identical to the
-    // one there.
+    // durableJobs — GENERIC durable step-batch primitive. See
+    // engine/durableJob.ts for the full contract description.
     durableJobs: defineTable({
         orgId: v.string(),
         kind: v.string(),
@@ -65,8 +63,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"))), // intentional divergence from Eve (bring-your-own-key); optional so it stays additive/backwards-compatible with rows created before this field existed
+        maxSubagents: v.optional(v.number()), // eve: agent-definition.ts:163-179, default 100
+        maxInputTokensPerSession: v.optional(v.union(v.number(), v.literal(false))), // eve: :195, false = unlimited
         status: v.union(v.literal("draft"), v.literal("live"), v.literal("archived")),
         createdBy: v.string(),
         createdAt: v.number(),
@@ -90,20 +93,19 @@ export default defineSchema({
         .index("by_org", ["orgId"])
         .index("by_org_agent", ["orgId", "agentId"])
         .index("by_org_agent_tool", ["orgId", "agentId", "toolName"]),
-    // sessions — one conversation container per `sessions.start` call. This
-    // pass deliberately does NOT tie a session to a `@convex-dev/workflow`
-    // run (unlike the repo-root, app-level `convex/engine/sessions.ts`
-    // prototype this was ported from) — long-task durability is already
-    // covered by `engine/durableJob.ts`; a consumer that needs a durable
-    // workflow driving turns can wire one on top using `durableJob.start`
-    // 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.
+    // sessions — one conversation container per `sessions.start` call.
+    // "intentional divergence from Eve": a session is piloted by a VERSIONED
+    // `@convex-dev/workflow` run (engine/workflows.ts: sessionWorkflowV1), so
+    // a turn survives a deploy. `workflowId`/`workflowVersion` are optional:
+    // rows written before that workflow existed stay valid without a backfill,
+    // and a consumer driving turns itself may leave them unset.
     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(),
     })
@@ -122,16 +124,341 @@ export default defineSchema({
         orgId: v.string(),
         sessionId: v.id("sessions"),
         name: v.union(v.literal("session.started"), v.literal("turn.started"), v.literal("turn.reasoning"), v.literal("turn.toolCall.requested"), v.literal("turn.toolCall.completed"), 
-        // "notre ligne" (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2):
+        // "intentional divergence from Eve" (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2):
         // explicit terminal state for a one-turn approval REFUSAL, distinct
         // from "turn.toolCall.completed" (tool actually ran). Without this,
         // 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")),
+        // anyway", which is the wrong default a consumer had to code around.
+        v.literal("turn.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved"), 
+        // Blank event auto-inserted by `engine/awaitEventTimeout.fire`
+        // (workflow#177: Convex provides no native timeout for
+        // `step.awaitEvent`). See 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"]),
+    // ---------------------------------------------------------------------
+    // WAKE-UP WITHOUT POLLING. See engine/wakeup.ts and
+    // 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"]),
+    // ---------------------------------------------------------------------
+    // MANDATES — "intentional divergence from Eve": bounded authority. See
+    // engine/mandates.ts and engine/wakeup.ts, where `enqueue` funds through
+    // `mandates.spendInternal` before any work can enter the wakeup pool.
+    // ---------------------------------------------------------------------
+    // mandates — a cap 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"]),
+    // ---------------------------------------------------------------------
+    // HABITS — "intentional divergence from Eve": a habit is a DYNAMIC cron
+    // per agent/org, which is what turns a chat into an employee. See
+    // engine/habits.ts; `crons` is a 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"]),
+    // ---------------------------------------------------------------------
+    // SANDBOX BRIDGE — the same pause/wake mechanism serves both the sandbox
+    // and agent-to-agent delegation. See engine/sandboxCallback.ts.
+    //
+    // BOUNDARY, and why it is where it is: the "use node" action
+    // that actually talks to `@vercel/sandbox` CANNOT live inside 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"]),
+    // ---------------------------------------------------------------------
+    // DELEGATION — an agent delegating to another agent uses THE SAME
+    // pause/wake system as the sandbox bridge: one system to maintain, not
+    // two. See engine/delegation.ts and engine/vpConnection.ts: every
+    // delegation/clone path terminates in exactly one call to this
+    // component's own public `engine/wakeup.enqueue`, never in 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"])
+        // 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 — the 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 — teamwork. The
+    // four VantagePeers tools (memory, tasks, messages, notes) wired as a
+    // CONNECTION of the agent aggregate, an intentional divergence from Eve. 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/callerSteps.js

@@ -56,7 +56,7 @@ export const alwaysSucceeds = internalMutation({
         return null;
     },
 });
-// Fails on every attempt -- used to prove "abandon after N échecs". Attempt
+// Fails on every attempt -- used to prove abandonment after N failures. Attempt
 // count is observable via `getAttemptCount` even though every DB write this
 // function might otherwise make would be rolled back by the throw.
 export const alwaysFails = internalMutation({

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,75 @@
+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. 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 this component 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
+// sandbox bridge, same shape/role as testFixtures/wakeupDemoWorkflow.ts.
+// 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;
+    },
+});