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

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

@@ -0,0 +1,33 @@
+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;
+    cost: number;
+    workFunctionHandle: string;
+}, Promise<Id<"wakeableWork">>>;
+export declare const enqueueInternal: import("convex/server").RegisteredMutation<"internal", {
+    payload?: string | undefined;
+    orgId: string;
+    workflowId: string;
+    awaitedEventName: string;
+    workFunctionHandle: string;
+}, Promise<Id<"wakeableWork">>>;
+export declare const cancel: import("convex/server").RegisteredMutation<"public", {
+    orgId: string;
+    wakeableWorkId: import("convex/values").GenericId<"wakeableWork">;
+}, Promise<null>>;
+export declare const getStatus: import("convex/server").RegisteredQuery<"public", {
+    orgId: string;
+    wakeableWorkId: import("convex/values").GenericId<"wakeableWork">;
+}, Promise<{
+    status: "completed" | "cancelled" | "pending" | "failed";
+    resultSummary: string | undefined;
+}>>;
+export declare const onWorkComplete: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workpool").OnCompleteArgs, null>;

package/dist/component/engine/wakeup.js

@@ -0,0 +1,228 @@
+import { Workpool } from "@convex-dev/workpool";
+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.
+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(),
+        agentId: v.id("agents"),
+        scope: v.string(),
+        cost: v.number(),
+        reason: v.string(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        workFunctionHandle: v.string(),
+        payload: v.optional(v.string()),
+    },
+    returns: v.id("wakeableWork"),
+    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,
+            agentId: args.agentId,
+            scope: args.scope,
+            cost: args.cost,
+            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.`);
+        }
+        return await ctx.runMutation(internal.engine.wakeup.enqueueInternal, {
+            orgId,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            workFunctionHandle: args.workFunctionHandle,
+            payload: args.payload,
+        });
+    },
+});
+// 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(),
+        workflowId: v.string(),
+        awaitedEventName: v.string(),
+        workFunctionHandle: v.string(),
+        payload: v.optional(v.string()),
+    },
+    returns: v.id("wakeableWork"),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        if (args.workflowId.length === 0) {
+            throw new Error("Validation: workflowId must not be empty");
+        }
+        if (args.awaitedEventName.length === 0) {
+            throw new Error("Validation: awaitedEventName must not be empty");
+        }
+        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", {
+            orgId,
+            workflowId: args.workflowId,
+            awaitedEventName: args.awaitedEventName,
+            workId: "",
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        });
+        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;
+    },
+});
+// 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") },
+    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")
+            return null;
+        await wakeupPool.cancel(ctx, row.workId);
+        return null;
+    },
+});
+export const getStatus = query({
+    args: { orgId: v.string(), wakeableWorkId: v.id("wakeableWork") },
+    returns: v.object({
+        status: v.union(v.literal("pending"), v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+        resultSummary: v.optional(v.string()),
+    }),
+    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 };
+    },
+});
+// ---------------------------------------------------------------------
+// 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") });
+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 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 workflow.sendEvent(ctx, {
+            workflowId: row.workflowId,
+            name: row.awaitedEventName,
+            validator: v.object({
+                status: v.union(v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+                resultSummary: v.optional(v.string()),
+            }),
+            value: { status, resultSummary },
+        });
+    },
+});

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

@@ -0,0 +1,11 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+export declare const resolveManifestInternal: import("convex/server").RegisteredQuery<"internal", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<null>>;
+export declare const recordTurnStartedInternal: import("convex/server").RegisteredMutation<"internal", {
+    sessionId: import("convex/values").GenericId<"sessions">;
+}, Promise<null>>;
+export declare const workflow: WorkflowManager;
+export declare const sessionWorkflowV1: import("convex/server").RegisteredMutation<"internal", import("@convex-dev/workflow").WorkflowArgs<{
+    sessionId: import("convex/values").VId<import("convex/values").GenericId<"sessions">, "required">;
+}>, import("@convex-dev/workflow").WorkflowId>;

package/dist/component/engine/workflows.js

@@ -0,0 +1,84 @@
+import { WorkflowManager } from "@convex-dev/workflow";
+import { v } from "convex/values";
+import { components, internal } from "../_generated/api.js";
+import { internalMutation, internalQuery } from "../_generated/server.js";
+// The durable, VERSIONED session workflow. This is what makes
+// `sessions.start` open a session PILOTED by `@convex-dev/workflow` rather
+// than a bare event table.
+//
+// Trust model at this boundary: the workflow engine runs with NO end-user
+// identity and NO client-supplied orgId (component isolation, same
+// discipline as component/engine/durableJob.ts and component/lib/auth.ts).
+// Every internal step below reads orgId from the `sessions` row itself --
+// never from an argument a workflow step could be handed by a caller.
+// Internal (server-to-server only) variants of the resolver/session
+// mutations, used by the workflow step handlers below. The workflow engine
+// runs with no end-user identity, so these read/write scoped strictly by
+// the orgId already recorded on the session row -- never trusting a
+// client-supplied orgId.
+export const resolveManifestInternal = internalQuery({
+    args: { sessionId: v.id("sessions") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const session = await ctx.db.get(args.sessionId);
+        if (!session)
+            throw new Error("Session not found");
+        const agent = await ctx.db.get(session.agentId);
+        if (!agent || agent.orgId !== session.orgId) {
+            throw new Error("Agent not found");
+        }
+        // Resolution result is consumed by the caller via the public
+        // engine/resolvers:resolveManifest query; this internal step exists to
+        // prove (and test) that the reread happens at each boundary.
+        return null;
+    },
+});
+export const recordTurnStartedInternal = internalMutation({
+    args: { sessionId: v.id("sessions") },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const session = await ctx.db.get(args.sessionId);
+        if (!session)
+            throw new Error("Session not found");
+        await ctx.db.insert("sessionEvents", {
+            orgId: session.orgId,
+            sessionId: args.sessionId,
+            name: "turn.started",
+            payload: undefined,
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});
+// Versioned workflow discipline (workflow#35): "if you change much
+// of anything in a workflow while there are ongoing workflows, they'll
+// fail." We never edit a workflow function in place once sessions
+// reference it -- a breaking change ships as `sessionWorkflowV2`, and the
+// deploy is preceded by draining v1 sessions (0 rows with
+// sessions.workflowVersion == "v1" and status == "running"). Same
+// discipline as `engine/durableJob.ts:durableJobWorkflowV1`.
+export const workflow = new WorkflowManager(components.workflow);
+// sessionWorkflowV1 -- the durable session loop. At `session.started` and
+// at every `turn.started` boundary it rereads the agent aggregate (never
+// cached, never compiled) via `resolveManifestInternal`. Tool approvals
+// pause the workflow via `step.awaitEvent`, guarded by the self-built
+// timeout (workflow#177) once that surface is ported into this component.
+export const sessionWorkflowV1 = workflow.define({
+    args: { sessionId: v.id("sessions") },
+    returns: v.null(),
+    handler: async (step, args) => {
+        // session.started boundary: read the aggregate once at start.
+        await step.runQuery(internal.engine.workflows.resolveManifestInternal, {
+            sessionId: args.sessionId,
+        });
+        // turn.started boundary: re-read on every turn so an agent/skill edit
+        // made mid-session is visible at the very next turn, with zero deploy.
+        await step.runMutation(internal.engine.workflows.recordTurnStartedInternal, {
+            sessionId: args.sessionId,
+        });
+        await step.runQuery(internal.engine.workflows.resolveManifestInternal, {
+            sessionId: args.sessionId,
+        });
+        return null;
+    },
+});