@vercel/factory 0.0.15 → 0.0.16

package/docs/recipes/task-messaging.md

@@ -0,0 +1,215 @@
+# Process a typed Task message
+
+Task messages are trusted application APIs with deny-by-default authorization. This recipe sends a
+typed parent-to-child message, stores a decision before applying its effect, and acknowledges the
+message only after the effect commits.
+
+Task messaging coordinates durable work around Eve sessions; it is not another Eve transport. An
+application exposes narrowly authorized message operations through its own tools or workflow code,
+and the Eve agent remains bound to its current Task attempt. Start with
+[Run an Eve agent as a Factory Task](./eve-agent.md) before adding inter-Task messages.
+
+## Run the recipe
+
+Save this as `task-messaging.mts` in an ESM project with `@vercel/factory`, `eve`, and `zod`
+installed.
+
+<!-- runnable-example:start -->
+
+```ts
+import type { ToolContext } from "eve/tools";
+import { z } from "zod";
+import {
+  factoryTaskAttemptAttribute,
+  factoryTaskAttribute,
+  requireTaskExecution,
+} from "@vercel/factory";
+import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+import {
+  defineTaskMessageProtocol,
+  defineTaskMessageProtocols,
+  processTaskMessage,
+  taskBoundMessagePolicy,
+  taskMessageInput,
+} from "@vercel/factory/tasks";
+import { defineWorkflow, defineWorkflows, taskWork } from "@vercel/factory/workflows";
+
+const noteProtocol = defineTaskMessageProtocol({
+  id: "review-note",
+  version: 1,
+  payload: z.strictObject({ note: z.string().min(1) }),
+});
+const messageWorkflow = defineWorkflow({
+  id: "process-review-note",
+  version: 1,
+  input: z.null(),
+  output: z.strictObject({ handled: z.boolean() }),
+});
+const driver = createInMemoryDriver();
+let nowMs = Date.parse("2026-09-10T12:00:00.000Z");
+const openStores = () =>
+  createStores({
+    driver,
+    now: () => new Date(nowMs).toISOString(),
+    workflows: defineWorkflows([messageWorkflow]),
+    messages: {
+      protocols: defineTaskMessageProtocols([noteProtocol]),
+      authorize: taskBoundMessagePolicy,
+    },
+  });
+const stores = openStores();
+const base = {
+  repositoryIds: ["repo_recipe05"] as const,
+  kind: "example",
+  origin: { operator: "local:recipe" },
+  replyTo: { channel: "local", address: "task-messaging" },
+  work: taskWork({ title: "Process a review note", input: null, workflow: messageWorkflow }),
+} as const;
+const root = await stores.tasks.create({ ...base, dedupeKey: "message-root" });
+const child = await stores.tasks.create({
+  ...base,
+  parentTaskId: root.id,
+  dedupeKey: "message-child",
+});
+await stores.tasks.transition(root.id, "running");
+await stores.tasks.transition(child.id, "running");
+const runningRoot = await stores.tasks.recordExecution(root.id, {
+  execution: { provider: "eve", sessionId: "ses_message_root" },
+});
+const runningChild = await stores.tasks.recordExecution(child.id, {
+  execution: { provider: "eve", sessionId: "ses_message_child" },
+});
+
+function toolContext(task: typeof runningRoot): ToolContext {
+  if (task.execution?.provider !== "eve") throw new Error("Expected an Eve execution");
+  return {
+    session: {
+      id: task.execution.sessionId,
+      auth: {
+        initiator: {
+          attributes: {
+            [factoryTaskAttribute]: task.id,
+            [factoryTaskAttemptAttribute]: String(task.attempt),
+          },
+        },
+      },
+    },
+  } as unknown as ToolContext;
+}
+
+const rootContext = toolContext(runningRoot);
+const authenticatedRoot = await requireTaskExecution(stores, rootContext, runningRoot.id);
+const rootPrincipal = {
+  id: `eve:${rootContext.session.id}`,
+  taskId: authenticatedRoot.id,
+};
+const childContext = toolContext(runningChild);
+const authenticatedChild = await requireTaskExecution(stores, childContext, runningChild.id);
+const childPrincipal = {
+  id: `eve:${childContext.session.id}`,
+  taskId: authenticatedChild.id,
+};
+
+const sendInput = taskMessageInput(noteProtocol, {
+  operationId: "review-note-1",
+  fromTaskId: root.id,
+  toTaskId: child.id,
+  expectAttempt: root.attempt,
+  payload: { note: "Check the retry boundary" },
+});
+const sent = await stores.messages.send({
+  principal: rootPrincipal,
+  message: sendInput,
+});
+const duplicate = await stores.messages.send({
+  principal: rootPrincipal,
+  message: sendInput,
+});
+if (duplicate.id !== sent.id) throw new Error("Expected idempotent message admission");
+
+let unauthorizedReadRejected = false;
+try {
+  await stores.messages.pending({
+    principal: rootPrincipal,
+    toTaskId: child.id,
+  });
+} catch {
+  unauthorizedReadRejected = true;
+}
+const externalEffects = new Set<string>();
+let decisionCalls = 0;
+let applyCalls = 0;
+let interruptAfterCommit = true;
+const processNext = (currentStores: typeof stores) =>
+  processTaskMessage({
+    stores: currentStores,
+    principal: childPrincipal,
+    task: { taskId: authenticatedChild.id, attempt: authenticatedChild.attempt },
+    leaseMs: 1_000,
+    workflow: messageWorkflow.binding,
+    protocol: noteProtocol,
+    decisionSchema: z.strictObject({ handled: z.boolean() }),
+    now: () => new Date(nowMs).toISOString(),
+    async decide({ message }) {
+      decisionCalls += 1;
+      return { handled: message.payload.note === "Check the retry boundary" };
+    },
+    async apply({ decision, effectKey }) {
+      if (!decision.handled) throw new Error("Expected the note to be handled");
+      applyCalls += 1;
+      externalEffects.add(effectKey);
+      if (interruptAfterCommit) {
+        interruptAfterCommit = false;
+        throw new Error("process interrupted after the external effect committed");
+      }
+    },
+  });
+
+let interruptionObserved = false;
+try {
+  await processNext(stores);
+} catch (error) {
+  interruptionObserved =
+    error instanceof Error && error.message.includes("interrupted after the external effect");
+}
+const restartedStores = openStores();
+const stillLeased = await processNext(restartedStores);
+nowMs += 1_001;
+const processed = await processNext(restartedStores);
+const replay = await processNext(restartedStores);
+if (
+  !unauthorizedReadRejected ||
+  !interruptionObserved ||
+  stillLeased.status !== "idle" ||
+  processed.status !== "processed" ||
+  processed.decision.handled !== true ||
+  decisionCalls !== 1 ||
+  applyCalls !== 2 ||
+  externalEffects.size !== 1 ||
+  replay.status !== "idle"
+) {
+  throw new Error("Expected authorized, interruption-safe message processing");
+}
+
+console.log(JSON.stringify({ messageId: sent.id, status: processed.status }));
+```
+
+<!-- runnable-example:end -->
+
+## What it proves
+
+The supplied policy allows direct parent-child sends and recipient-local reads and processing. A
+stable source operation ID makes retries return the same immutable message. The example interrupts
+processing after the external effect commits, opens the stores again, waits for the claim lease to
+expire, and recovers without recomputing the durable decision. `apply` repeats with the same effect
+key, so the simulated external system records one effect.
+
+Leases do not make external systems exactly-once: `apply` may repeat after interruption. Production
+effects must remain idempotent by `effectKey`. An Eve-facing wrapper should call
+`requireTaskExecution` and derive its message principal from that authenticated Task and session,
+as the recipe does; never accept the principal from model input.
+
+Message admission does not wake an idle recipient by itself. After a successful send, publish an
+application-owned queue wakeup or run message processing on a schedule. If the recipient is
+deliberately inactive, use `stores.work.waitForMessages` and `stores.work.resume` around that
+workflow phase.

package/docs/recipes/typed-eve-result.md

@@ -0,0 +1,161 @@
+# Submit a typed workflow result from Eve
+
+The generic `finish_task` tool records `{ summary }` for the default `task@1` workflow. When an
+Eve agent must return a domain-specific result, define a narrow Eve tool that authenticates the
+current execution with `requireTaskExecution` and completes the exact registered workflow.
+
+## Run the recipe
+
+Save this as `typed-eve-result.mts` in an ESM project with `@vercel/factory`, `eve`, and `zod`
+installed.
+
+<!-- runnable-example:start -->
+
+```ts
+import { defineTool, type ToolContext } from "eve/tools";
+import { z } from "zod";
+import {
+  factoryTaskAttemptAttribute,
+  factoryTaskAttribute,
+  requireTaskExecution,
+  startEveSession,
+  taskHeaders,
+} from "@vercel/factory";
+import { dispatchTask } from "@vercel/factory/execution";
+import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+import { taskIdSchema } from "@vercel/factory/tasks";
+import {
+  defineWorkflow,
+  defineWorkflows,
+  parseAgentRouteBinding,
+  taskWork,
+} from "@vercel/factory/workflows";
+
+const greetingWorkflow = defineWorkflow({
+  id: "greeting",
+  version: 1,
+  input: z.strictObject({ name: z.string().min(1) }),
+  output: z.strictObject({
+    greeting: z.string().min(1),
+    language: z.enum(["en", "de"]),
+  }),
+});
+const route = parseAgentRouteBinding({ id: "greeter", version: 1 });
+const stores = createStores({
+  driver: createInMemoryDriver(),
+  workflows: defineWorkflows([greetingWorkflow]),
+});
+const base = {
+  repositoryIds: ["repo_typed01"] as const,
+  kind: "example",
+  origin: { operator: "local:recipe" },
+  replyTo: { channel: "local", address: "typed-eve-result" },
+} as const;
+const task = await stores.tasks.create({
+  ...base,
+  work: {
+    ...taskWork({
+      title: "Create a German greeting",
+      input: { name: "Factory" },
+      workflow: greetingWorkflow,
+    }),
+    route,
+  },
+});
+const otherTask = await stores.tasks.create({
+  ...base,
+  work: {
+    ...taskWork({
+      title: "A different greeting",
+      input: { name: "Eve" },
+      workflow: greetingWorkflow,
+    }),
+    route,
+  },
+});
+
+const running = await dispatchTask(stores, {
+  taskId: task.id,
+  route,
+  launch: (claimed) =>
+    startEveSession({
+      agentUrl: "https://factory.example/eve/agents/greeter",
+      message: `Greet ${greetingWorkflow.input.parse(claimed.work.input).name}`,
+      operationId: `factory-task:${claimed.id}:${claimed.attempt}`,
+      headers: taskHeaders({ taskId: claimed.id, attempt: claimed.attempt }),
+      fetch: async () => Response.json({ sessionId: "ses_typed_greeting" }),
+    }),
+});
+if (running.execution?.provider !== "eve") throw new Error("Expected an Eve execution");
+const context = {
+  session: {
+    id: running.execution.sessionId,
+    auth: {
+      initiator: {
+        attributes: {
+          [factoryTaskAttribute]: running.id,
+          [factoryTaskAttemptAttribute]: String(running.attempt),
+        },
+      },
+    },
+  },
+} as unknown as ToolContext;
+
+const submitGreeting = defineTool({
+  description: "Validate and submit the greeting produced for your current Factory Task.",
+  inputSchema: z.strictObject({
+    taskId: taskIdSchema,
+    greeting: greetingWorkflow.output.shape.greeting,
+    language: greetingWorkflow.output.shape.language,
+  }),
+  async execute({ taskId, greeting, language }, ctx) {
+    const authenticated = await requireTaskExecution(stores, ctx, taskId);
+    if (authenticated.execution?.provider !== "eve") {
+      throw new Error("Expected the authenticated Eve execution");
+    }
+    const completed = await stores.work.completeWorkflow({
+      task: { taskId: authenticated.id, attempt: authenticated.attempt },
+      workflow: greetingWorkflow.binding,
+      output: { greeting, language },
+      fence: { from: "running", execution: authenticated.execution },
+    });
+    return { submitted: true as const, taskId: completed.id };
+  },
+});
+
+let foreignTaskRejected = false;
+try {
+  await submitGreeting.execute(
+    { taskId: otherTask.id, greeting: "Hallo, Eve!", language: "de" },
+    context,
+  );
+} catch {
+  foreignTaskRejected = true;
+}
+await submitGreeting.execute(
+  { taskId: running.id, greeting: "Hallo, Factory!", language: "de" },
+  context,
+);
+const completed = await stores.tasks.get(running.id);
+const output = greetingWorkflow.output.parse(completed?.workResult?.output);
+if (
+  !foreignTaskRejected ||
+  completed?.state !== "succeeded" ||
+  output.greeting !== "Hallo, Factory!"
+) {
+  throw new Error("Expected authenticated, schema-validated workflow completion");
+}
+
+console.log(JSON.stringify({ state: completed.state, output }));
+```
+
+<!-- runnable-example:end -->
+
+Export the tool from the target agent's `tools/` directory, alongside `get_task`. Its input
+schema tells the model exactly what result to return, while the workflow registry validates the
+persisted output again. The completion fence checks the authenticated Task's running state and Eve
+execution atomically with the success transition, so a concurrent pause, cancellation, retry, or
+replacement execution cannot accept a stale result.
+
+Keep each historical workflow version registered while stored Tasks can still reference it. Create
+a new workflow and tool version when the result contract changes incompatibly.

package/docs/runtime-integration.md

@@ -0,0 +1,137 @@
+# Runtime composition
+
+`@vercel/factory` provides typed contracts and policy injection points. An application still owns
+its configured repositories, credentials, agent routes, budgets, prompts, approval policy, and
+provider accounts.
+
+## Kernel and supplied policy
+
+The package root owns common configuration, repository admission, credential-redacted diagnostics,
+generic Eve session integration, and declarations with no narrower capability owner. Kernel
+capabilities live on their own paths, including Tasks, workflows, execution, planning, budgets,
+signals, receipts, storage, and communication.
+
+The supplied software-development behavior is an explicit composition under
+`@vercel/factory/presets/software-development`. It combines approval, completion, communication,
+recovery, dispatch, and delegation policy with capability-owned Task and Change tools. Applications
+inject repository policy, planner behavior, launchers, credentials, budget, wakeup publication,
+and retry and batch limits.
+
+## Durable work
+
+Every Task contains explicit work: a title, bounded JSON input, completion criteria, an exact
+workflow ID and version, and an optional exact agent route. `taskWork` selects the generic `task@1`
+JSON contract. Custom input and output contracts require `defineWorkflow` and registration through
+`defineWorkflows`.
+
+Task kind is descriptive. It does not select execution or determine success. Canonical dependencies
+belong to `stores.graphs`, and `stores.work.complete` records validated output. A route-less Task is
+owned by local workflow code; agent work records an exact route and must recover that same binding.
+
+Task messages are trusted application APIs rather than HTTP endpoints. Message access defaults to
+deny. `taskBoundMessagePolicy` permits parent-child sends and recipient-local operations when an
+application explicitly configures the supplied protocols. Durable decisions are stored before
+idempotent effects, but leases cannot fence external systems or remove cancellation races.
+The runnable [Task messaging recipe](recipes/task-messaging.md) demonstrates that boundary and its
+effect-key requirement.
+
+## Where Eve fits
+
+Eve is the normal agent runtime. Factory does not implement the model loop or replace an Eve
+agent's `agent.ts`; it records the durable contract around each run and connects that contract to
+the Eve session.
+
+| Task execution mode | Use it for                                                               | What advances the Task                                                                                      |
+| ------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| Exact agent route   | Normal Eve agent work                                                    | `dispatchTask` starts an Eve session; authenticated Factory tools and hooks complete or recover the attempt |
+| Workflow owned      | Deterministic application or orchestrator logic with no provider session | Application code transitions and completes the Task                                                         |
+| Execution adapter   | Coding harnesses, sandboxes, and other provider sessions                 | The adapter returns evidence; workflow policy interprets it and completes or retries the Task               |
+
+For an Eve route, the application calls `startEveSession` with `taskHeaders`. The agent's Eve
+channel wraps its authentication with `withFactoryTask`, and its filesystem mounts tools from
+`createTaskTools` plus the hook from `createFactoryHooks`. The session is thereby bound to one Task
+ID and attempt. See the runnable [Eve agent integration recipe](recipes/eve-agent.md), followed by
+the [typed Eve result](recipes/typed-eve-result.md), [human input](recipes/human-input.md), and
+[dependent Eve agents](recipes/dependent-tasks.md) recipes.
+
+## Assemble the production loop
+
+A deployable factory needs an application-owned loop around the package primitives. Keep each
+boundary explicit so recovery can repeat one operation without guessing what happened elsewhere.
+
+| Boundary             | Production responsibility                                                                                                                    |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Persistence          | Construct one `createStores` instance with Blob or Postgres; register every workflow and message protocol version referenced by stored Tasks |
+| Route launchers      | Map each exact `routeKey` to a protected Eve agent URL; merge `taskHeaders` with deployment identity                                         |
+| Dispatch             | Run `sweepQueued` from a durable schedule and after events that can unblock work; pass budget and approval policy before launch              |
+| Agent completion     | Mount `withFactoryTask`, `createFactoryHooks`, and only the Task or domain tools that role needs                                             |
+| Questions            | Deliver persisted QuestionTasks through Foreman, authenticate replies to the original `replyTo`, then wake dispatch                          |
+| Recovery             | Let hooks requeue bounded Eve failures; sweep the exact stored route and retain attempt-derived operation IDs                                |
+| Cancellation         | Persist Task cancellation first, request provider cancellation second, and retry ambiguous provider stops                                    |
+| Messages and effects | Derive principals from authenticated sessions, publish recipient wakeups, and make external effects idempotent by effect key                 |
+| Operations           | Monitor failed launches, exhausted Tasks, unanswered questions, queue age, budget refusal, and outbox delivery                               |
+
+The dispatcher can run concurrently: its queued-to-running admission has one winner. Invoke it on
+a short schedule for repair and also from queue wakeups for latency. A useful wakeup contains no
+authority; the worker rereads canonical state, runs one bounded `sweepQueued` pass, and records or
+alerts on every `failed` result. Treat `skipped` results as named gates such as dependencies,
+approval, or workflow ownership rather than launch failures. Budget exhaustion fails the Task and
+appears as a `launch_failed` result, so operations should surface its persisted refusal reason.
+
+Budget reservation and approval happen before a route launcher creates an Eve session. Configure
+the policy in trusted application code, pass the current budget snapshot to dispatch, and expose
+approval actions only through an authenticated operator boundary. The agent should receive the
+approved Task contract and role-specific tools, never provider credentials or the ability to widen
+repository scope.
+
+## Storage and execution
+
+`@vercel/factory/storage` exposes the validating store engine and a non-durable in-memory driver.
+Persistent adapters are opt-in through `@vercel/factory/storage/blob` and
+`@vercel/factory/storage/postgres`.
+
+Recovery has three separate meanings. Reopening a persistent driver only restores access to the
+records. `stores.work.recover(rootTaskId)` then reads the canonical graph and repairs Task snapshots
+whose admitted graph nodes survived an interrupted creation write. It does not launch or resume a
+provider. Execution recovery separately inspects the Task's recorded provider execution and either
+reattaches when it is confirmed active or applies workflow-owned retry policy. The runnable
+[persistence and restart recovery recipe](recipes/persistence-recovery.md) demonstrates the first
+two boundaries with workflow-owned work; the retry recipe covers provider execution recovery.
+
+`@vercel/factory/execution` owns provider-neutral dispatch and execution lifecycle contracts.
+`@vercel/factory/sandbox` supplies retry-safe execution records, abort propagation, harness
+continuation, workspace contracts, and scoped Vercel Sandbox lifecycle. The application injects
+prompt construction, evidence interpretation, pricing, credentials, repository seeding, and its
+model and harness registry.
+
+The [custom workflow recipe](recipes/custom-workflow.md) demonstrates the adapter path for
+non-Eve execution. The [cancellation](recipes/cancellation.md) recipe covers adapter and Eve
+cancellation, while [retry recovery](recipes/retry-recovery.md) exercises Eve lifecycle hooks and
+scheduled replacement attempts.
+
+## Provider adapters
+
+External-provider APIs stay opt-in under `@vercel/factory/integrations/<provider>`:
+
+- GitHub provides intake normalization, App-token scope validation, checkout and publication
+  primitives, communication delivery, review reporting, labels, and work triage.
+- Slack delivers communication events through an injected client.
+- DeepSec normalizes scanner output and provides its Eve tool.
+- Vercel provides Queue wakeups and credential-isolated Git transport.
+
+Applications remain responsible for selecting credentials and authorizing repositories. Connector
+installation access never expands the application's repository allowlist.
+The Vercel-managed transport uses fresh trusted Sandboxes for reads and signed writes. They execute
+no repository code or model. Publication consumes credential-free bundles, applies exact remote-head
+leases, rechecks application authority at the mutation boundary, and returns the signed remote SHA.
+Do not attach managed Git fields to agent or harness Sandboxes. Applications still choose their
+pull-request creation adapter. In Vercel mode, initial Git Data and pull-request publication use one
+fresh repository-scoped managed Sandbox; Connect mode retains the installation-token publication path.
+
+## Operator boundary
+
+`@vercel/factory/client` is browser-safe and exposes `FactoryClient`, request and response schemas,
+Task states, transcripts, and session streaming. Server handlers and their dependencies live under
+`@vercel/factory/api`; Next.js integration lives under `@vercel/factory/next`.
+
+Return to the [consumer documentation index](index.md) to find exact import paths and declarations.

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@vercel/factory",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Schema, state machines, and kernel primitives for Agent Factory.",
+  "homepage": "https://github.com/vercel-labs/agent-factory/tree/main/packages/factory",
+  "bugs": "https://github.com/vercel-labs/agent-factory/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/agent-factory.git",
+    "directory": "packages/factory"
+  },
   "files": [
-    "dist"
+    "CHANGELOG.md",
+    "dist",
+    "docs"
   ],
   "type": "module",
   "sideEffects": false,
@@ -124,6 +133,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@types/json-schema": "^7.0.15",
+    "@types/node": "24.x",
     "diff": "8.0.2"
   },
   "devDependencies": {
@@ -131,13 +142,13 @@
     "@ai-sdk/harness-claude-code": "1.0.112",
     "@ai-sdk/sandbox-vercel": "1.0.108",
     "@electric-sql/pglite": "^0.5.7",
-    "@types/node": "24.x",
     "@vercel/blob": "^2.8.0",
     "@vercel/sandbox": "2.10.0-beta.0",
     "drizzle-orm": "^0.45.2",
-    "eve": "^0.46.1",
+    "eve": "^0.57.0",
     "tsdown": "^0.22.14",
     "typescript": "5.9.3",
+    "typescript-current": "npm:typescript@7.0.2",
     "vitest": "4.1.9",
     "zod": "4.4.3"
   },
@@ -147,7 +158,7 @@
     "@vercel/blob": "^2.6.0",
     "@vercel/sandbox": ">=2.10.0-beta.0 <4",
     "drizzle-orm": "^0.45.0",
-    "eve": "^0.46.0",
+    "eve": "^0.57.0",
     "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
@@ -177,6 +188,6 @@
     "lint": "oxlint --config ../../.oxlintrc.json --max-warnings 0 .",
     "lint:logs": "node ../../scripts/check-structured-logging.mjs src",
     "test": "vitest run",
-    "typecheck": "tsc"
+    "typecheck": "node node_modules/typescript/bin/tsc"
   }
 }