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

package/dist/component/testFixtures/wakeupDemoWorkflow.js

@@ -0,0 +1,77 @@
+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/wakeupDemoWorkflow — TEST-ONLY reference recipient for the
+// wake-up mechanism (C2), ported from convex/engine/wakeupDemoWorkflow.ts.
+// A real consumer's own workflow does exactly this shape: call
+// `step.awaitEvent({ name: <same name passed to engine/wakeup.enqueue> })`
+// and do nothing else until it resolves. Proves (and is exercised by the
+// contract tests in component/wakeup.componentPackaging.test.ts) that the
+// ONLY way this resumes is `engine/wakeup.onWorkComplete`'s `sendEvent`
+// call -- there is no poll, no re-check, no scheduled interval anywhere in
+// this file. Also exercises `engine/awaitEventTimeout` by accepting the
+// blank `sandbox.timeout` event name as an alternate wake source.
+//
+// Versioned workflow discipline (workflow#35, I0 §7.1): ship
+// `...V2` rather than editing `wakeupDemoWorkflowV1` in place once
+// referenced by live work (not a live concern for a test fixture, kept for
+// parity with the app-level source it was ported from).
+export const workflow = new WorkflowManager(components.workflow);
+// start -- creates the demo result row, starts the demo workflow parked on
+// `step.awaitEvent`, and hands back both the `workflowId` (to pass as
+// `engine/wakeup.enqueue`'s `workflowId` arg) and the `resultId` (to poll
+// in tests -- polling the TEST OBSERVATION POINT is not the mechanism
+// under test; the mechanism is that `wokenAt` gets set with zero polling
+// FROM THE ENGINE SIDE, which finishAllScheduledFunctions proves).
+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);
+        const resultId = await ctx.db.insert("wakeupDemoResults", { orgId, enqueuedAt: Date.now() });
+        const workflowId = await workflow.start(ctx, internal.testFixtures.wakeupDemoWorkflow.wakeupDemoWorkflowV1, { 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"), v.literal("cancelled")),
+        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 wakeupDemoWorkflowV1 = workflow.define({
+    args: { resultId: v.id("wakeupDemoResults"), awaitedEventName: v.string() },
+    returns: v.null(),
+    handler: async (step, args) => {
+        // Blocks here -- resumes ONLY when engine/wakeup.onWorkComplete calls
+        // workflow.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.wakeupDemoWorkflow.recordWokenInternal, {
+            resultId: args.resultId,
+            status: result.status,
+            resultSummary: result.resultSummary,
+        });
+        return null;
+    },
+});

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

@@ -0,0 +1,8 @@
+export declare const succeeds: import("convex/server").RegisteredAction<"internal", {
+    payload?: string | undefined;
+    orgId: string;
+}, Promise<null>>;
+export declare const fails: import("convex/server").RegisteredAction<"internal", {
+    payload?: string | undefined;
+    orgId: string;
+}, Promise<never>>;

package/dist/component/testFixtures/wakeupWork.js

@@ -0,0 +1,21 @@
+import { v } from "convex/values";
+import { internalAction } from "../_generated/server.js";
+// testFixtures/wakeupWork — stand-ins for a CALLER'S OWN unit of work (an
+// action the caller passes to `engine/wakeup.enqueue` via
+// `createFunctionHandle`, same component-isolation discipline as
+// `testFixtures/callerSteps`). Exist ONLY to drive the component-level
+// wakeup contract tests. Ported from convex/testFixtures/wakeupWork.ts.
+export const succeeds = internalAction({
+    args: { orgId: v.string(), payload: v.optional(v.string()) },
+    returns: v.null(),
+    handler: async () => {
+        return null;
+    },
+});
+export const fails = internalAction({
+    args: { orgId: v.string(), payload: v.optional(v.string()) },
+    returns: v.null(),
+    handler: async () => {
+        throw new Error("simulated wakeup-work failure");
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/agent-engine",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "Reusable Convex component: durable agent engine. Agent = data aggregate (root sheet + child tables), never compiled code. Built on @convex-dev/workflow + @convex-dev/workpool (+ @convex-dev/agent). Eve parity by design.",
   "type": "module",
   "license": "UNLICENSED",
@@ -44,6 +44,7 @@
     "@convex-dev/sharded-counter": "^0.2.1",
     "@convex-dev/workflow": "0.4.4",
     "@convex-dev/workpool": "0.4.7",
+    "@vercel/sandbox": "^2.6.1",
     "ai": "6.0.35",
     "convex": "1.42.1",
     "convex-helpers": "0.1.103"