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

package/dist/component/engine/streams.js

@@ -0,0 +1,162 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server.js";
+import { requireOrgId } from "../lib/auth.js";
+const streamInfoResult = v.object({ tailIndex: v.number(), done: v.boolean() });
+const streamChunkResult = v.object({ index: v.number(), dataBase64: v.string() });
+async function getStreamDoc(ctx, orgId, runId, name) {
+    return await ctx.db
+        .query("worldStreams")
+        .withIndex("by_org_run_name", (q) => q.eq("orgId", orgId).eq("runId", runId).eq("name", name))
+        .unique();
+}
+export const writeChunk = mutation({
+    args: { orgId: v.string(), runId: v.string(), name: v.string(), dataBase64: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const now = Date.now();
+        let stream = await getStreamDoc(ctx, orgId, args.runId, args.name);
+        if (stream && stream.orgId !== orgId) {
+            stream = null;
+        }
+        if (!stream) {
+            const id = await ctx.db.insert("worldStreams", {
+                orgId,
+                runId: args.runId,
+                name: args.name,
+                chunkCount: 0,
+                done: false,
+                createdAt: now,
+                updatedAt: now,
+            });
+            stream = await ctx.db.get(id);
+        }
+        if (!stream) {
+            throw new Error("Stream row failed to materialise");
+        }
+        if (stream.done) {
+            throw new Error(`Cannot write to a closed stream: ${args.runId}/${args.name}`);
+        }
+        const index = stream.chunkCount;
+        await ctx.db.insert("worldStreamChunks", {
+            orgId,
+            runId: args.runId,
+            name: args.name,
+            index,
+            dataBase64: args.dataBase64,
+            createdAt: now,
+        });
+        await ctx.db.patch(stream._id, { chunkCount: index + 1, updatedAt: now });
+        return null;
+    },
+});
+export const closeStream = mutation({
+    args: { orgId: v.string(), runId: v.string(), name: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const now = Date.now();
+        let stream = await getStreamDoc(ctx, orgId, args.runId, args.name);
+        if (stream && stream.orgId !== orgId) {
+            stream = null;
+        }
+        if (!stream) {
+            const id = await ctx.db.insert("worldStreams", {
+                orgId,
+                runId: args.runId,
+                name: args.name,
+                chunkCount: 0,
+                done: true,
+                createdAt: now,
+                updatedAt: now,
+            });
+            stream = await ctx.db.get(id);
+        }
+        else {
+            await ctx.db.patch(stream._id, { done: true, updatedAt: now });
+        }
+        return null;
+    },
+});
+export const getStreamInfo = query({
+    args: { orgId: v.string(), runId: v.string(), name: v.string() },
+    returns: streamInfoResult,
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await getStreamDoc(ctx, orgId, args.runId, args.name);
+        if (!doc || doc.orgId !== orgId) {
+            return { tailIndex: -1, done: false };
+        }
+        return { tailIndex: doc.chunkCount - 1, done: doc.done };
+    },
+});
+export const listStreamNames = query({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.array(v.string()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldStreams")
+            .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", args.runId))
+            .collect();
+        return docs.filter((d) => d.orgId === orgId).map((d) => d.name);
+    },
+});
+export const listChunksPage = query({
+    args: {
+        orgId: v.string(),
+        runId: v.string(),
+        name: v.string(),
+        limit: v.number(),
+        cursor: v.union(v.string(), v.null()),
+    },
+    returns: v.object({
+        page: v.array(streamChunkResult),
+        isDone: v.boolean(),
+        continueCursor: v.string(),
+    }),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const startIndex = args.cursor === null ? 0 : Number(args.cursor);
+        const docs = await ctx.db
+            .query("worldStreamChunks")
+            .withIndex("by_org_run_name_index", (q) => q
+            .eq("orgId", orgId)
+            .eq("runId", args.runId)
+            .eq("name", args.name)
+            .gte("index", startIndex))
+            .order("asc")
+            .take(args.limit + 1);
+        const owned = docs.filter((d) => d.orgId === orgId);
+        const isDone = owned.length <= args.limit;
+        const page = isDone ? owned : owned.slice(0, args.limit);
+        return {
+            page: page.map((c) => ({ index: c.index, dataBase64: c.dataBase64 })),
+            isDone,
+            continueCursor: isDone ? "" : String(page[page.length - 1].index + 1),
+        };
+    },
+});
+export const listChunksFromIndex = query({
+    args: {
+        orgId: v.string(),
+        runId: v.string(),
+        name: v.string(),
+        startIndex: v.number(),
+        limit: v.number(),
+    },
+    returns: v.array(streamChunkResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldStreamChunks")
+            .withIndex("by_org_run_name_index", (q) => q
+            .eq("orgId", orgId)
+            .eq("runId", args.runId)
+            .eq("name", args.name)
+            .gte("index", args.startIndex))
+            .order("asc")
+            .take(args.limit);
+        return docs.filter((d) => d.orgId === orgId).map((c) => ({ index: c.index, dataBase64: c.dataBase64 }));
+    },
+});

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

@@ -2,6 +2,6 @@ export declare const respond: import("convex/server").RegisteredMutation<"public
     updatePolicy?: "always" | "once" | "never" | undefined;
     orgId: string;
     toolName: string;
-    sessionId: import("convex/values").GenericId<"sessions">;
+    sessionId: string;
     decision: "approved" | "denied";
 }, Promise<null>>;

package/dist/component/engine/toolApprovals.js

@@ -1,33 +1,12 @@
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
-import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/toolApprovals — respond to a pending approval request
-// (`tool.approval.requested`, raised by `sessions.requestToolCall`).
-//
-// TWO DISTINCT AXES (VP k17ea6x3tht8xa3rxm139t23gx8ajkf3, defaut 2 --
-// these were conflated pre-alpha.5, which is the defect this fixes):
-//
-//   1. `decision` -- the RESPONSE to THIS ONE pending approval request,
-//      for THIS turn only. Vocabulary aligned with Eve's `ApprovalStatus`
-//      (packages/eve/src/public/definitions/approval.ts: "approved" |
-//      "denied" | ...) -- eve parity, cited verbatim, not "intentional divergence from Eve".
-//      `"denied"` means: this turn's tool call is refused, full stop. It
-//      does NOT change the agent's standing policy for the tool, and it
-//      must NOT be interpreted as "tool skipped, turn completed anyway" --
-//      it appends a `turn.toolCall.denied` sessionEvent instead of letting
-//      the caller silently proceed to `completeToolCall`.
-//
-//   2. `updatePolicy` -- optional, persists a NEW standing policy
-//      (always | once | never, eve parity: eve/tools/approval helpers) for
-//      this (agent, tool) pair going forward, upserted on
-//      `by_org_agent_tool`. Independent of `decision`: a human can deny
-//      this turn's call AND leave the policy untouched (ask again next
-//      time), or approve this turn AND simultaneously flip the policy to
-//      "always"/"never" so future calls don't pause.
+import { requireOrgId } from "../lib/auth.js";
+import { insertEvent, loadSessionRun } from "./sessions.js";
+import { agentIdOfRun } from "./world.js";
 export const respond = mutation({
     args: {
         orgId: v.string(),
-        sessionId: v.id("sessions"),
+        sessionId: v.string(),
         toolName: v.string(),
         decision: v.union(v.literal("approved"), v.literal("denied")),
         updatePolicy: v.optional(v.union(v.literal("always"), v.literal("once"), v.literal("never"))),
@@ -35,15 +14,15 @@ export const respond = mutation({
     returns: v.null(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const session = await ctx.db.get(args.sessionId);
-        assertSameOrg(orgId, session, "Session not found");
+        const run = await loadSessionRun(ctx, orgId, args.sessionId);
+        const agentId = agentIdOfRun(ctx, run);
         const now = Date.now();
         if (args.updatePolicy !== undefined) {
             const existing = await ctx.db
                 .query("toolApprovals")
                 .withIndex("by_org_agent_tool", (q) => q
                 .eq("orgId", orgId)
-                .eq("agentId", session.agentId)
+                .eq("agentId", agentId)
                 .eq("toolName", args.toolName))
                 .unique();
             if (existing) {
@@ -55,7 +34,7 @@ export const respond = mutation({
             else {
                 await ctx.db.insert("toolApprovals", {
                     orgId,
-                    agentId: session.agentId,
+                    agentId,
                     toolName: args.toolName,
                     approval: args.updatePolicy,
                     createdAt: now,
@@ -63,26 +42,22 @@ export const respond = mutation({
                 });
             }
         }
-        await ctx.db.insert("sessionEvents", {
+        await insertEvent(ctx, {
             orgId,
-            sessionId: args.sessionId,
+            run,
             name: "tool.approval.resolved",
             payload: JSON.stringify({
                 toolName: args.toolName,
                 decision: args.decision,
                 updatedPolicy: args.updatePolicy ?? null,
             }),
-            createdAt: now,
         });
         if (args.decision === "denied") {
-            // Explicit refusal state for THIS turn's tool call -- never a
-            // silent "turn.toolCall.completed". See module doc above.
-            await ctx.db.insert("sessionEvents", {
+            await insertEvent(ctx, {
                 orgId,
-                sessionId: args.sessionId,
+                run,
                 name: "turn.toolCall.denied",
                 payload: JSON.stringify({ toolName: args.toolName }),
-                createdAt: now,
             });
         }
         return null;

package/dist/component/engine/vpConnection.js

@@ -2,29 +2,7 @@ import { v } from "convex/values";
 import { action, internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 import { internal } from "../_generated/api.js";
-// engine/vpConnection — teamwork. The four VantagePeers tools
-// (memory, tasks, messages, notes) are wired as a CONNECTION of the agent
-// aggregate -- intentional divergence from Eve, same slot family as `connections` (MCP/OpenAPI).
-// Four toggles, ON by default.
-//
-// DIRECT ACCESS, NO NETWORK IN THE HOT PATH: `invokeVpTool` dispatches via a
-// caller-supplied Convex function handle (`createFunctionHandle`), the same
-// discipline `engine/wakeup.ts` and `engine/durableJob.ts` already use for
-// `workFunctionHandle` / `stepFunctionHandle` -- an in-process function
-// reference resolved by `ctx.runMutation`, never an HTTP request: this file
-// contains zero occurrences of the literal fetch call.
-//
-// orgId discipline (component/lib/auth.ts): every PUBLIC function takes
-// `orgId` as an explicit ARGUMENT (auth does not propagate across a
-// component boundary). `orgId` is passed EXPLICITLY to the target function
-// handle (never trusting the target's own `ctx.auth`) -- this is the
-// isolation guarantee the org-scoped write depends on: the target function
-// is expected to write scoped to the `orgId` it was HANDED, not to derive
-// one itself.
 const vpTool = v.union(v.literal("memory"), v.literal("tasks"), v.literal("messages"), v.literal("notes"));
-// defaultToggles — four switches, all ticked by default. A
-// missing `vpConnections` row means "use these defaults", so every agent
-// starts with all four VP tools available with zero extra setup.
 export const defaultToggles = {
     memoryEnabled: true,
     tasksEnabled: true,
@@ -43,7 +21,6 @@ const vpConnectionDoc = v.object({
     createdAt: v.number(),
     updatedAt: v.number(),
 });
-// get — the raw connection row, if a human ever touched the toggles.
 export const get = query({
     args: { orgId: v.string(), agentId: v.id("agents") },
     returns: v.union(vpConnectionDoc, v.null()),
@@ -57,8 +34,6 @@ export const get = query({
             .unique();
     },
 });
-// getToggles — resolves the effective toggle state (row if present, else
-// the checked-by-default set) for a given agent.
 export const getToggles = query({
     args: { orgId: v.string(), agentId: v.id("agents") },
     returns: v.object({
@@ -85,8 +60,6 @@ export const getToggles = query({
             : defaultToggles;
     },
 });
-// setToggles — upserts the four switches (an explicit human choice to turn
-// one off; still ON by default until touched).
 export const setToggles = mutation({
     args: {
         orgId: v.string(),
@@ -134,15 +107,6 @@ function toggleFor(toggles, tool) {
                 ? toggles.messagesEnabled
                 : toggles.notesEnabled;
 }
-// invokeVpTool — the direct-access dispatch. `vpFunctionHandle` is an
-// opaque handle string obtained via `createFunctionHandle` against a
-// mutation the VantagePeers tenant exposes (same-app or cross-app handle,
-// per Convex's own `createFunctionHandle` contract -- never a URL, never an
-// HTTP fetch call). The engine passes `orgId` EXPLICITLY as an argument
-// (never trusting the target's own `ctx.auth`, since this may cross an
-// app/component boundary) -- this is the isolation guarantee the org-scoped
-// write depends on: the target function is expected to write scoped to the
-// `orgId` it was HANDED, not to derive one itself.
 export const invokeVpTool = action({
     args: {
         orgId: v.string(),
@@ -164,10 +128,6 @@ export const invokeVpTool = action({
         if (!toggleFor(toggles, args.tool)) {
             throw new Error(`VantagePeers tool "${args.tool}" is disabled for this agent`);
         }
-        // In-process dispatch by function handle -- NOT an HTTP fetch call, NOT
-        // an HTTP hop. `orgId` is threaded explicitly so the write lands in the
-        // CALLING agent's org tenant regardless of which org's identity (if
-        // any) the target function's own `ctx.auth` would otherwise resolve.
         await ctx.runMutation(args.vpFunctionHandle, { orgId, argsJson: args.argsJson });
         await ctx.runMutation(internal.engine.vpConnection.recordInvocationInternal, {
             orgId,

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

@@ -1,33 +1,31 @@
 import { Workpool } from "@convex-dev/workpool";
-import type { Id } from "../_generated/dataModel.js";
 export declare const wakeupPool: Workpool;
 export declare const enqueue: import("convex/server").RegisteredAction<"public", {
     payload?: string | undefined;
     orgId: string;
-    workflowId: string;
     agentId: import("convex/values").GenericId<"agents">;
     awaitedEventName: string;
     scope: string;
     reason: string;
+    workflowId: string;
     cost: number;
     workFunctionHandle: string;
-}, Promise<Id<"wakeableWork">>>;
+}, Promise<string>>;
 export declare const enqueueInternal: import("convex/server").RegisteredMutation<"internal", {
     payload?: string | undefined;
     orgId: string;
-    workflowId: string;
     awaitedEventName: string;
+    workflowId: string;
     workFunctionHandle: string;
-}, Promise<Id<"wakeableWork">>>;
+}, Promise<string>>;
 export declare const cancel: import("convex/server").RegisteredMutation<"public", {
     orgId: string;
-    wakeableWorkId: import("convex/values").GenericId<"wakeableWork">;
+    messageId: string;
 }, Promise<null>>;
 export declare const getStatus: import("convex/server").RegisteredQuery<"public", {
     orgId: string;
-    wakeableWorkId: import("convex/values").GenericId<"wakeableWork">;
+    messageId: string;
 }, Promise<{
-    status: "completed" | "cancelled" | "pending" | "failed";
-    resultSummary: string | undefined;
+    status: "failed" | "pending" | "delivered";
 }>>;
 export declare const onWorkComplete: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workpool").OnCompleteArgs, null>;

package/dist/component/engine/wakeup.js

@@ -3,77 +3,17 @@ import { v } from "convex/values";
 import { WorkflowManager } from "@convex-dev/workflow";
 import { components, internal } from "../_generated/api.js";
 import { action, internalMutation, mutation, query } from "../_generated/server.js";
-import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/wakeup — THE GENERIC WAKE-UP PRIMITIVE. An agent does not ask every
-// minute whether work has arrived: it is woken the instant the work resolves.
-// Mechanism: `enqueue` puts caller-supplied work (an action, referenced by
-// an opaque handle string
-// from `createFunctionHandle` in the CALLER's own app, same
-// component-isolation discipline as `durableJob.stepFunctionHandle`) into a
-// dedicated `@convex-dev/workpool` (`components.wakeupPool`, declared in
-// component/convex.config.ts). That pool's `onComplete` callback -- which
-// fires in its OWN transaction once the work resolves (workpool issue #133:
-// onComplete runs in a separate transaction; there is no native pause) --
-// calls `workflow.sendEvent(...)` against the CALLER-supplied
-// `workflowId`. Any workflow step parked on
-// `step.awaitEvent({ name: awaitedEventName })` resumes the INSTANT that
-// event lands -- no interval, no cron, no re-query loop. This fires for
-// success, failure, AND cancellation alike: see `onWorkComplete` below -- a
-// sleeping agent whose work silently died is worse than a polling one.
-//
-// Decoupled from `sessions`/`durableJobs` by design: any workflow (a
-// session, a durable job, or a bespoke one) can be the wake target by
-// handing us its own `workflowId` -- this table/module never reads either
-// of those tables.
-//
-// ---------------------------------------------------------------------
-// "intentional divergence from Eve"
-// ---------------------------------------------------------------------
-//
-// (A) orgId is an EXPLICIT ARGUMENT on every public function, never derived
-// from `ctx.auth` -- auth does NOT propagate across a component boundary
-// (see component/lib/auth.ts). The consumer app has already authenticated
-// its caller and resolved orgId on its OWN side before calling in.
-//
-// (B) MANDATE FUNDING CHOKE-POINT. `enqueue` is an
-// `action` because funding-then-starting is a TWO-TRANSACTION protocol a
-// single mutation cannot express: `mandates.spendInternal` must be able to
-// COMMIT an `approvalRequests` row on an overrun WITHOUT that commit being
-// rolled back by a subsequent throw in the same transaction (see the
-// transactional argument in `component/engine/mandates.ts:spendCore`,
-// proven by the MUST_BLOCK probe in `component/engine/mandates.test.ts`).
-// The action:
-//   1. validates `orgId` (the ARGUMENT the caller supplies -- see note A;
-//      this component never reads `ctx.auth`),
-//   2. runs `mandates.spendInternal` in its OWN transaction
-//      (`ctx.runMutation`),
-//   3. throws immediately if `!result.ok` -- refuses end-to-end. The
-//      approval-request row from step 2 has ALREADY committed, because it
-//      lives in a transaction that already returned before this throw runs.
-//   4. only on `result.ok === true` does it call `enqueueInternal` in a
-//      SECOND transaction to actually put the work in the pool.
-// There is no code path from "client wants work started" to "work enters
-// the pool" that does not pass through step 2 -- this is an "argument you
-// cannot fabricate" pattern: the only way to make
-// `enqueueInternal` run at all is to be `enqueue` itself, and `enqueue`
-// always calls `mandates.spendInternal` first. `spendInternal` takes
-// `orgId` as an argument rather than deriving it from `ctx.auth`, per the
-// boundary discipline in note A.
+import { requireOrgId } from "../lib/auth.js";
+import { enqueueMessage, getMessageById, setMessagePayload, settleMessageById } from "./queue.js";
+const WAKEUP_QUEUE_NAME = "engine_wakeup";
+function newWakeupIdempotencyKey() {
+    return crypto.randomUUID();
+}
+const QUEUE_ERR_NOT_FOUND = "Wakeable work not found";
 export const wakeupPool = new Workpool(components.wakeupPool, {
     maxParallelism: 10,
 });
-// Same WorkflowManager COMPONENT as engine/workflows.ts (components.workflow)
-// -- a fresh WorkflowManager instance bound to the same component is safe
-// to construct per-module; the manager itself holds no local state, it
-// only forwards to the component.
 const workflow = new WorkflowManager(components.workflow);
-// ---------------------------------------------------------------------
-// PUBLIC CONTRACT
-// ---------------------------------------------------------------------
-// enqueue — the ONLY client-facing entry point (an `action`, see note B
-// above). Funds the work through `mandates.spendInternal` in its
-// own transaction FIRST; only calls `enqueueInternal` (a second,
-// independent transaction) once that funding succeeded.
 export const enqueue = action({
     args: {
         orgId: v.string(),
@@ -86,12 +26,8 @@ export const enqueue = action({
         workFunctionHandle: v.string(),
         payload: v.optional(v.string()),
     },
-    returns: v.id("wakeableWork"),
+    returns: v.string(),
     handler: async (ctx, args) => {
-        // orgId is a caller-supplied ARGUMENT, validated here (not derived from
-        // ctx.auth -- component boundaries do not propagate auth, see note A
-        // and component/lib/auth.ts). Validated BEFORE the funding call so a
-        // missing orgId is refused with OUR message, not a downstream one.
         const orgId = requireOrgId(args.orgId);
         const result = await ctx.runMutation(internal.engine.mandates.spendInternal, {
             orgId,
@@ -101,9 +37,6 @@ export const enqueue = action({
             reason: args.reason,
         });
         if (!result.ok) {
-            // REFUSED end-to-end: the approval request already committed inside
-            // `mandates.spendInternal`'s own transaction (step above); no
-            // further transaction runs, so the work never enters the pool.
             throw new Error(`Mandate refused: agent ${args.agentId} has no remaining authority ` +
                 `for scope "${args.scope}" (cost ${args.cost}). Approval request ` +
                 `${result.approvalId} was created and is pending human review.`);
@@ -117,11 +50,6 @@ export const enqueue = action({
         });
     },
 });
-// enqueueInternal -- INTERNAL ONLY variant, kept for the two-transaction
-// funding protocol (`enqueue` calls this in its SECOND transaction
-// once `mandates.spendInternal` returned `{ ok: true }`, same split as the
-// app-level prototype). Unreachable from any client: Convex excludes
-// `internal.*` functions from the API surface shipped to clients.
 export const enqueueInternal = internalMutation({
     args: {
         orgId: v.string(),
@@ -130,7 +58,7 @@ export const enqueueInternal = internalMutation({
         workFunctionHandle: v.string(),
         payload: v.optional(v.string()),
     },
-    returns: v.id("wakeableWork"),
+    returns: v.string(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
         if (args.workflowId.length === 0) {
@@ -142,82 +70,81 @@ export const enqueueInternal = internalMutation({
         if (args.workFunctionHandle.length === 0) {
             throw new Error("Validation: workFunctionHandle must not be empty");
         }
-        const now = Date.now();
-        const wakeableWorkId = await ctx.db.insert("wakeableWork", {
+        const { messageId } = await enqueueMessage(ctx, {
             orgId,
-            workflowId: args.workflowId,
-            awaitedEventName: args.awaitedEventName,
-            workId: "",
-            status: "pending",
-            createdAt: now,
-            updatedAt: now,
+            queueName: WAKEUP_QUEUE_NAME,
+            payloadJson: JSON.stringify({
+                workflowId: args.workflowId,
+                awaitedEventName: args.awaitedEventName,
+                workId: "",
+            }),
+            idempotencyKey: newWakeupIdempotencyKey(),
+        });
+        const workId = await wakeupPool.enqueueAction(ctx, args.workFunctionHandle, { orgId, payload: args.payload }, { onComplete: internal.engine.wakeup.onWorkComplete, context: { orgId, messageId } });
+        await setMessagePayload(ctx, {
+            orgId,
+            messageId,
+            payloadJson: JSON.stringify({
+                workflowId: args.workflowId,
+                awaitedEventName: args.awaitedEventName,
+                workId,
+            }),
         });
-        const workId = await wakeupPool.enqueueAction(ctx, args.workFunctionHandle, { orgId, payload: args.payload }, { onComplete: internal.engine.wakeup.onWorkComplete, context: { wakeableWorkId } });
-        await ctx.db.patch(wakeableWorkId, { workId });
-        return wakeableWorkId;
+        return messageId;
     },
 });
-// Best-effort cancel -- lets a caller pull work back out of the pool before
-// it starts; the wake still fires (workpool reports `kind: "canceled"` to
-// `onComplete`, see below) so the awaiting workflow is never left hanging.
 export const cancel = mutation({
-    args: { orgId: v.string(), wakeableWorkId: v.id("wakeableWork") },
+    args: { orgId: v.string(), messageId: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const row = await ctx.db.get(args.wakeableWorkId);
-        assertSameOrg(orgId, row, "Wakeable work not found");
-        if (row.status !== "pending")
+        const msg = await getMessageById(ctx, { orgId, messageId: args.messageId });
+        if (!msg)
+            throw new Error(QUEUE_ERR_NOT_FOUND);
+        if (msg.status !== "pending")
             return null;
-        await wakeupPool.cancel(ctx, row.workId);
+        const { workId } = JSON.parse(msg.payloadJson);
+        await wakeupPool.cancel(ctx, workId);
+        await settleMessageById(ctx, { orgId, messageId: args.messageId, status: "failed" });
         return null;
     },
 });
 export const getStatus = query({
-    args: { orgId: v.string(), wakeableWorkId: v.id("wakeableWork") },
+    args: { orgId: v.string(), messageId: v.string() },
     returns: v.object({
-        status: v.union(v.literal("pending"), v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
-        resultSummary: v.optional(v.string()),
+        status: v.union(v.literal("pending"), v.literal("delivered"), v.literal("failed")),
     }),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const row = await ctx.db.get(args.wakeableWorkId);
-        assertSameOrg(orgId, row, "Wakeable work not found");
-        return { status: row.status, resultSummary: row.resultSummary };
+        const msg = await getMessageById(ctx, { orgId, messageId: args.messageId });
+        if (!msg)
+            throw new Error(QUEUE_ERR_NOT_FOUND);
+        const status = msg.status === "delivered" ? "delivered" : msg.status === "failed" ? "failed" : "pending";
+        return { status };
     },
 });
-// ---------------------------------------------------------------------
-// INTERNAL — the wake itself. Invoked ONLY by the workpool's own
-// completion machinery (defineOnComplete), never by a client and never on
-// a timer.
-// ---------------------------------------------------------------------
-// THE WAKE. This is the entire mechanism: onComplete -> sendEvent. It is a
-// mutation the workpool component calls exactly once per work item, in its
-// own transaction, at the moment the work resolves -- whichever way it
-// resolves. All three `result.kind`s below reach `sendEvent`: a workflow
-// asleep because its work vanished (failed/cancelled, no wake) would be
-// strictly worse than one that polls.
-const onWorkCompleteContext = v.object({ wakeableWorkId: v.id("wakeableWork") });
+const onWorkCompleteContext = v.object({ orgId: v.string(), messageId: v.string() });
 export const onWorkComplete = wakeupPool.defineOnComplete({
     context: onWorkCompleteContext,
     handler: async (ctx, { context, result }) => {
-        const row = await ctx.db.get(context.wakeableWorkId);
-        if (!row)
-            return; // work outlived its tracking row -- nothing to wake
+        const msg = await getMessageById(ctx, context);
+        if (!msg)
+            return;
+        const { workflowId, awaitedEventName } = JSON.parse(msg.payloadJson);
         const status = result.kind === "success"
             ? "completed"
             : result.kind === "failed"
                 ? "failed"
                 : "cancelled";
         const resultSummary = result.kind === "failed" ? result.error : undefined;
-        await ctx.db.patch(row._id, {
-            status,
-            resultSummary,
-            updatedAt: Date.now(),
+        await settleMessageById(ctx, {
+            orgId: context.orgId,
+            messageId: context.messageId,
+            status: status === "completed" ? "delivered" : "failed",
         });
         await workflow.sendEvent(ctx, {
-            workflowId: row.workflowId,
-            name: row.awaitedEventName,
+            workflowId: workflowId,
+            name: awaitedEventName,
             validator: v.object({
                 status: v.union(v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
                 resultSummary: v.optional(v.string()),