@vantageos/agent-engine 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/component/testFixtures/callerSteps.js

@@ -0,0 +1,90 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "../_generated/server";
+// testFixtures/callerSteps — stand-ins for a CALLER'S OWN step function
+// (the thing a real consumer, e.g. VantagePeers, would define in ITS OWN
+// app and pass to `engine/durableJob.start` as `stepFunctionHandle` via
+// `createFunctionHandle`). These exist ONLY to drive the contract tests in
+// convex/engineDurableJob.test.ts -- they are not part of the public
+// surface (see examples/vantage-peers-long-task for the real, documented
+// integration a consumer would write).
+//
+// Attempt counts are tracked IN-MEMORY (module-level Map), not via a DB
+// write, because a mutation that throws rolls back every write made in its
+// OWN transaction -- including a "record that I was called" insert made
+// just before the throw. In-memory state survives the rollback since it is
+// plain JS state, not part of the Convex transaction.
+const attemptCounts = new Map();
+function bump(jobId, stepIndex) {
+    const key = `${jobId}:${stepIndex}`;
+    const next = (attemptCounts.get(key) ?? 0) + 1;
+    attemptCounts.set(key, next);
+    return next;
+}
+export const getAttemptCount = internalQuery({
+    args: { jobId: v.id("durableJobs"), stepIndex: v.number() },
+    returns: v.number(),
+    handler: async (_ctx, args) => {
+        return attemptCounts.get(`${args.jobId}:${args.stepIndex}`) ?? 0;
+    },
+});
+// TEST-ONLY: `convexTest()` reuses deterministic, low-cardinality document
+// IDs across SEPARATE test instances within the same process, so this
+// module-level Map must be cleared between tests to avoid one test's
+// counters leaking into the next via a colliding `${jobId}:${stepIndex}`
+// key. Called from `beforeEach` in engineDurableJob.test.ts.
+export const resetAttemptCounts = internalMutation({
+    args: {},
+    returns: v.null(),
+    handler: async () => {
+        attemptCounts.clear();
+        return null;
+    },
+});
+// Records one row per SUCCESSFUL invocation so tests can assert exactly
+// which step indices actually completed (idempotent-replay assertions).
+export const alwaysSucceeds = internalMutation({
+    args: { orgId: v.string(), jobId: v.id("durableJobs"), stepIndex: v.number() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        bump(args.jobId, args.stepIndex);
+        await ctx.db.insert("callerStepInvocations", {
+            orgId: args.orgId,
+            jobId: args.jobId,
+            stepIndex: args.stepIndex,
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});
+// Fails on every attempt -- used to prove "abandon after N échecs". 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({
+    args: { orgId: v.string(), jobId: v.id("durableJobs"), stepIndex: v.number() },
+    returns: v.null(),
+    handler: async (_ctx, args) => {
+        bump(args.jobId, args.stepIndex);
+        throw new Error(`simulated failure at step ${args.stepIndex}`);
+    },
+});
+// Fails on the FIRST attempt of ANY step, then succeeds on every
+// subsequent attempt of that same step -- used to prove retry-then-succeed
+// still advances the cursor (not just outright failure), exercising the
+// `maxAttemptsPerStep > 1` path distinctly from `alwaysFails`.
+export const failsFirstAttemptThenSucceeds = internalMutation({
+    args: { orgId: v.string(), jobId: v.id("durableJobs"), stepIndex: v.number() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const attemptNumber = bump(args.jobId, args.stepIndex);
+        if (attemptNumber === 1) {
+            throw new Error(`simulated single failure at step ${args.stepIndex}`);
+        }
+        await ctx.db.insert("callerStepInvocations", {
+            orgId: args.orgId,
+            jobId: args.jobId,
+            stepIndex: args.stepIndex,
+            createdAt: Date.now(),
+        });
+        return null;
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/agent-engine",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "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",
@@ -21,6 +21,9 @@
     "./convex.config.js": {
       "types": "./dist/component/convex.config.d.ts",
       "default": "./dist/component/convex.config.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
     }
   },
   "scripts": {
@@ -35,6 +38,10 @@
   },
   "dependencies": {
     "@convex-dev/agent": "0.6.4",
+    "@convex-dev/aggregate": "^0.2.2",
+    "@convex-dev/crons": "^0.2.2",
+    "@convex-dev/rate-limiter": "^0.3.2",
+    "@convex-dev/sharded-counter": "^0.2.1",
     "@convex-dev/workflow": "0.4.4",
     "@convex-dev/workpool": "0.4.7",
     "ai": "6.0.35",