@vercel/factory 0.0.13 → 0.0.15

package/README.md

@@ -5,8 +5,314 @@ persistence, agent tools, and provider adapters for durable, auditable software
 
 The FDK extends Eve incrementally. Durable workflows retain authority over policy, budgets,
 state transitions, retries, and external effects while agents and coding harnesses return bounded
-results. The V1 reference runtime uses Postgres, Blob, AI SDK `HarnessAgent`, and Vercel Sandbox,
+results. The V1 reference runtime uses Blob, AI SDK `HarnessAgent`, and Vercel Sandbox,
 with independent verification and human-owned merges.
 
 See the [repository README](../../README.md) for development instructions and the
 [architecture](../../docs/factory-architecture.md) for the complete contract.
+
+## Public import paths
+
+Use the narrowest capability entry point that owns an API. This keeps optional integrations and
+browser/server boundaries visible and keeps dependencies aligned with the capability in use.
+
+Factory targets Eve agents, and `eve` is a required peer dependency. Eve-specific APIs live with
+their semantic owner instead of under a parallel `/eve` namespace.
+
+| Import path                                                     | Use for                                                                               |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `@vercel/factory`                                               | Configuration, shared primitives, and generic Eve sessions, hooks, and Task tools     |
+| `@vercel/factory/tasks`                                         | Tasks, graphs, messages, effects, and their stores                                    |
+| `@vercel/factory/workflows`                                     | Workflow definitions, work contracts, and agent routes                                |
+| `@vercel/factory/execution`                                     | Provider-neutral dispatch, execution lifecycle, and sweeps                            |
+| `@vercel/factory/planning`                                      | Provider-neutral planner contracts and runtime                                        |
+| `@vercel/factory/budgets`                                       | Budget schemas, capacity policy, settlement, and maintenance sweeps                   |
+| `@vercel/factory/signals`                                       | Signal records, intake creation, decisions, and lifecycle                             |
+| `@vercel/factory/receipts`                                      | Immutable audit records, costs, identifiers, and append inputs                        |
+| `@vercel/factory/storage`, `/storage/blob`, `/storage/postgres` | Store engine and optional persistence adapters                                        |
+| `@vercel/factory/communication`                                 | Inbound normalization, routing, and outbox contracts                                  |
+| `@vercel/factory/client`, `/api`, `/next`                       | Browser client, server handlers, and Next.js integration                              |
+| `@vercel/factory/changes`                                       | Change lifecycle, verification, and multi-repository coordination                     |
+| `@vercel/factory/findings`                                      | Finding records, remediation, fingerprints, and agent reporting                       |
+| `@vercel/factory/code-review`                                   | Review policy, contracts, and agent tools                                             |
+| `@vercel/factory/pull-requests`                                 | Publication and merge-conflict contracts and tools                                    |
+| `@vercel/factory/work-triage`                                   | Existing-work lookup and its agent tool                                               |
+| `@vercel/factory/delivery-metrics`                              | Delivery ledger metrics and repository health                                         |
+| `@vercel/factory/presets/software-development`                  | Supplied software-development policy and Eve composition                              |
+| `@vercel/factory/integrations/github`                           | GitHub API helpers and communication, review, publication, label, and triage adapters |
+| `@vercel/factory/integrations/slack`                            | Slack communication delivery adapter                                                  |
+| `@vercel/factory/integrations/deepsec`                          | DeepSec normalization and its Eve scanner tool                                        |
+| `@vercel/factory/integrations/vercel`                           | Vercel Queue and trusted Git transport adapters                                       |
+| `@vercel/factory/sandbox`                                       | Optional isolated execution integration                                               |
+
+The package root owns common configuration, cross-cutting primitives, and generic Eve integration
+that have no narrower capability owner. This package is pre-1.0: replaced paths and names are
+removed during alpha API cleanup rather than retained as deprecated aliases. Each public
+declaration has one canonical owner. The browser client and server API re-export shared HTTP wire
+contracts at both consumption boundaries from the same source declarations.
+
+Ordinary public values and functions use `camelCase`; type-like declarations, constructors, and UI
+components use `PascalCase`; fixed constant-style values may use `UPPER_CASE`. Schemas use a
+`thingSchema` / `Thing` pair; configuration objects, operation results, and error classes use
+`*Options`, `*Result`, and `*Error`. Factories use `create*`, while declarative validators and
+registries use `define*`. Provider and protocol payload keys retain their required wire spelling.
+Oxlint is the repository's sole JavaScript and TypeScript linter and enforces the allowed
+identifier shapes. Declaration-specific casing follows the conventions above in code and review.
+
+## Reusable runtime integration
+
+The package root exposes provider-neutral integration helpers that have no narrower capability owner:
+
+- `repositoryIdForSlug` and `ensureConfiguredRepository` provide deterministic repository identity
+  and allowlist-bound admission. The caller supplies normalized `defaultBranch` and `dependsOn`
+  metadata from its own configuration; the package does not infer either value.
+- `redactedErrorMessage` and `redactedErrorDetails` remove common credential forms and supplied
+  secret values from diagnostics.
+
+The supplied software-development runtime is an explicit composition rather than part of the
+kernel. Domain operations and their Eve tools live under their owning capability paths. The
+`@vercel/factory/presets/software-development` entry point contains the supplied approval,
+completion, communication, recovery, dispatch, and delegation behavior plus the DeepSec scan brief.
+It also composes generic Task tools with the Change outcome tool. Applications inject repository
+policy, planner behavior, launchers, credentials, budget, wakeup publication, and retry and batch
+limits.
+
+Capability APIs use their semantic owner paths, while external-provider APIs stay opt-in under
+`@vercel/factory/integrations/<provider>`:
+
+- `@vercel/factory` binds Task or conversation scope to authenticated Eve sessions through
+  semantic readers, owns the generic start, forward, cancel, and completed-turn lifecycle, and
+  supplies generic delegation and Task tools. It also materializes browser-safe transcript
+  projections through injected origin and header policy.
+- Capability entry points expose agent tools beside the corresponding domain operation. For
+  example, `@vercel/factory/changes` records a Change and `@vercel/factory/code-review` exposes
+  review tools. The software-development preset composes the common Task and Change tools.
+- Provider-specific Eve tool factories that implement a Factory capability stay on that
+  capability path and identify the provider in their symbol name.
+- `@vercel/factory/storage/blob` includes content-addressed, Task-bound artifact storage with digest
+  verification in addition to the Blob store driver. Applications inject or namespace its narrow
+  Blob client when one project contains multiple factory state domains.
+- `@vercel/factory/sandbox` supplies the retry-safe execution ledger, abort propagation, harness
+  continuation adapter, workspace contract, and scoped Vercel Sandbox lifecycle. Applications
+  inject prompt construction, evidence interpretation, pricing, credentials, repository seeding,
+  and the configured harness/model registry.
+- `@vercel/factory/integrations/github` normalizes addressed review comments, question replies,
+  and repository identity alongside the GitHub API helpers. It also validates GitHub App token
+  scope; supplies bounded committed-tree publication, a Git Data/pull-request client, and checkout
+  primitives; and owns the standalone GitHub adapters for communication delivery, review
+  reporting, pull-request publication and labels, and existing-work triage. Applications still
+  choose credentials and authorize repositories.
+- `@vercel/factory/integrations/slack` delivers communication events through an injected Slack
+  client.
+- `@vercel/factory/integrations/deepsec` owns DeepSec output normalization and its provider-centric
+  Eve scanner tool.
+- `@vercel/factory/integrations/vercel` configures hosted Vercel Queue wakeups. It validates
+  messages, provides stable idempotency keys and fixture isolation, and exports
+  `createVercelGitHubGitTransport` to read and publish Git bundles through fresh trusted sandboxes,
+  keeping credentials out of agent sandboxes.
+  Reads require read-only tokens; bundles include full history with a 50 MiB limit.
+  The application supplies queue transport, logging, and repository-scoped credentials.
+- `@vercel/factory/api` exports the bounded sandbox snapshot and workspace-diff assembly used by
+  optional inspection adapters; sandbox discovery, base-blob retrieval, and repository
+  authorization remain application-owned.
+
+These APIs deliberately stop before application policy: configured repositories, credentials,
+agent routes, budgets, prompts, approval rules, and provider account choices remain in the concrete
+factory.
+
+The communication and execution capabilities supply policy injection points such as
+`createTaskCommunicationReconciler` and the stall sweep's optional cancellation callback. Omitting
+`approval` from the configuration selects a neutral allow-by-default policy; factories should
+select a policy explicitly. A software factory opts into
+`defaultSoftwareDevelopmentApprovalPolicy`, the supplied delegation and completion policies, and
+the software presentation and dispatch behavior from
+`@vercel/factory/presets/software-development`. Generated projects make those choices explicitly.
+
+Every Task requires `work` (title, bounded JSON input, completion criteria, exact workflow
+ID/version, and optional exact agent route), plus engine-owned root and parent membership.
+`taskWork` defaults to the generic `task@1` JSON contract; explicit workflow registrations supply
+Zod input/output contracts. `stores.graphs` owns per-root dependencies, and `stores.work.complete`
+records validated output. Task kind is descriptive, not execution or success authority.
+
+`stores.messages` and `processTaskMessage` provide authorized immutable messages, bounded inbox
+leases, and durable decisions before idempotent effects. Access defaults to deny; supplied
+assignment/handoff protocols and task-bound policy require explicit application configuration.
+These are direct trusted APIs, not HTTP endpoints or an enabled recursive planner. See the
+[Task contract](../../docs/factory-architecture.md#task) for bounds, recovery, and race limitations.
+
+This is a breaking Task contract with no compatibility path. Old stored Task snapshots fail the
+new required schema validation; there is no separate legacy-rejection mechanism. No live data is changed by this source update; rollout must explicitly
+choose data migration or reset before deployment.
+
+## Local Task primitives
+
+Copy the following three blocks together into a TypeScript ES module with top-level await. This isolated example
+uses an in-memory driver and a synthetic repository ID: no model, provider, HTTP endpoint, or live
+planner is called. Production applications supply persistent storage and authenticated principals;
+never derive a principal's Task binding from a message payload.
+
+### Register a workflow
+
+`taskWork({ title, input })` constructs generic `task@1` work. A custom contract requires explicit
+registration and an exact binding; including `defaultTaskWorkflow` keeps generic work available
+in the same registry. Registration alone starts nothing.
+
+```ts
+import { z } from "zod";
+import {
+  assignmentPayloadSchema,
+  assignmentTaskMessageProtocol,
+  createDefaultTaskMessageProtocols,
+  processTaskMessage,
+  taskBoundMessagePolicy,
+} from "@vercel/factory/tasks";
+import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+import {
+  defaultTaskWorkflow,
+  defineWorkflow,
+  defineWorkflows,
+  taskWork,
+} from "@vercel/factory/workflows";
+
+const countWords = defineWorkflow({
+  id: "word-count",
+  version: 1,
+  input: z.strictObject({ text: z.string().min(1).describe("Text to count.") }),
+  output: z.strictObject({ words: z.number().int().nonnegative().describe("Word count.") }),
+});
+const driver = createInMemoryDriver();
+const stores = createStores({
+  driver,
+  workflows: defineWorkflows([defaultTaskWorkflow, countWords]),
+  messages: { protocols: createDefaultTaskMessageProtocols(), authorize: taskBoundMessagePolicy },
+});
+const scope = { repositoryIds: ["repo_example"], replyTo: { channel: "local", address: "demo" } };
+const parent = await stores.tasks.create({
+  ...scope,
+  kind: "analysis",
+  origin: { operator: "local:demo" },
+  work: taskWork({ title: "Count words in supplied text" }),
+  dedupeKey: "demo:root",
+});
+```
+
+### Create children and canonical dependencies
+
+The engine derives each child's root from its one parent. Dependencies belong to `stores.graphs`,
+not Task snapshots. Editing requires the observed graph revision and a queued, unsealed Task.
+Transitioning to running seals edges and requires every prerequisite to have succeeded.
+
+```ts
+const childScope = { ...scope, origin: {}, parentTaskId: parent.id };
+const preparation = await stores.tasks.create({
+  ...childScope,
+  kind: "analysis",
+  work: taskWork({ title: "Prepare input" }),
+  dedupeKey: "demo:prepare",
+});
+const worker = await stores.tasks.create({
+  ...childScope,
+  kind: "analysis",
+  dedupeKey: "demo:count",
+  work: {
+    ...taskWork({
+      title: "Count words",
+      input: { text: "Hello from Factory" },
+      workflow: countWords,
+    }),
+    completionCriteria: ["Return the number of whitespace-separated words"],
+  },
+});
+const graph = await stores.graphs.get(parent.rootTaskId);
+if (!graph) throw new Error("Task graph must exist after admission");
+await stores.graphs.setDependencies({
+  rootTaskId: parent.rootTaskId,
+  taskId: worker.id,
+  dependencies: [preparation.id],
+  expectedRevision: graph.revision,
+});
+await stores.tasks.transition(parent.id, "running");
+await stores.work.waitForMessages({
+  task: { taskId: parent.id, attempt: parent.attempt },
+  phase: "children",
+});
+await stores.tasks.transition(preparation.id, "running");
+await stores.work.complete({
+  task: { taskId: preparation.id, attempt: preparation.attempt },
+  output: { prepared: true },
+});
+await stores.tasks.transition(worker.id, "running");
+```
+
+These Tasks have no agent route: local workflow code owns execution. For agent work,
+`routeTaskWork({ route, title, input })` adds an exact route but still selects generic `task@1`.
+For typed agent work, add `route: parseAgentRouteBinding({ id, version })` to work constructed with
+the custom workflow binding, or use the exact route returned by a registry. See the
+[route example](../../docs/factory-architecture.md#task); recovery must use that exact route, not
+kind or latest version.
+
+### Send and process one message
+
+The explicit policy above permits parent-child sends and recipient-local processing, not discard.
+Stable operation IDs deduplicate sends. `processTaskMessage` stores a validated decision before
+`apply`; this example's only effect is idempotent Task completion with that output.
+
+```ts
+await stores.messages.send({
+  principal: { id: "local:parent", taskId: parent.id },
+  message: {
+    operationId: "assign-count",
+    fromTaskId: parent.id,
+    toTaskId: worker.id,
+    expectAttempt: parent.attempt,
+    type: assignmentTaskMessageProtocol.binding,
+    payload: { instructions: "Count the words in your work input." },
+  },
+});
+const result = await processTaskMessage({
+  stores,
+  principal: { id: "local:worker", taskId: worker.id },
+  task: { taskId: worker.id, attempt: worker.attempt },
+  leaseMs: 30_000,
+  workflow: countWords.binding,
+  protocol: assignmentTaskMessageProtocol,
+  decisionSchema: countWords.output,
+  async decide({ task, message }) {
+    if (message.type.id !== "assignment" || message.type.version !== 1) {
+      throw new Error("Expected assignment@1");
+    }
+    assignmentPayloadSchema.parse(message.payload);
+    const { text } = countWords.input.parse(task.work.input);
+    return { words: text.trim() ? text.trim().split(/\s+/u).length : 0 };
+  },
+  async apply({ task, decision }) {
+    await stores.work.complete({
+      task: { taskId: task.id, attempt: task.attempt },
+      output: decision,
+    });
+  },
+});
+if (result.status === "processed") {
+  await stores.work.complete({
+    task: { taskId: parent.id, attempt: parent.attempt },
+    output: { childTaskId: worker.id, output: result.decision },
+  });
+}
+```
+
+`idle` means empty or already leased, not necessarily drained. In durable application code, retry
+processing against the same store and stable identities; a whole-script rerun is not a recovery loop.
+External writes in `apply` must honor its `effectKey` (derive stable subkeys for multiple writes).
+Lease assertions cannot fence external systems or eliminate cancellation races. Recovery after
+success/failure requires the exact durable decision; cancelled Tasks cannot replay effects.
+Inboxes hold at most 256 pending messages and leases last at most five minutes. Supplied
+`assignment@1` / `handoff@1` protocols do not install a recursive planner or change lifecycle
+on receipt. Without explicit message configuration, access is denied. See the
+[message contract](../../docs/factory-architecture.md#task-messages) for recovery and discard rules.
+
+## Operator clients
+
+`@vercel/factory/client` exposes the browser-safe `FactoryClient`, operator request/response
+schemas, durable `taskStates`, `Transcript`, and `followSessionStream`. It is shared by the
+reference web UI and TUI. Supply a fixed factory origin and, for non-browser callers, an async `headers` callback for
+authentication. Server handlers and their dependencies remain under `@vercel/factory/api`.

package/dist/agent-routes.d.mts

@@ -0,0 +1,69 @@
+import { AgentRouteBinding, AgentRouteBindingInput, agentRouteBindingSchema, parseAgentRouteBinding } from "./schema/agent-route.mjs";
+import { JsonValue, TaskWork } from "./schema/work.mjs";
+import { TaskKind } from "./schema/task.mjs";
+import { z } from "zod";
+//#region src/agent-routes.d.ts
+/** Validates an exact-version route from workflow work to one configured agent. */
+declare const agentRouteSchema: z.core.$ZodBranded<z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodDefault<z.ZodNumber>;
+  agent: z.ZodString;
+  taskKind: z.ZodType<TaskKind, unknown, z.core.$ZodTypeInternals<TaskKind, unknown>>;
+  description: z.ZodString;
+  permissions: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>, "AgentRouteBinding", "out">;
+/** Canonical `id@version` lookup key for one exact agent route. */
+type AgentRouteKey<Id extends string = string, Version extends number = number> = `${Id}@${Version}`;
+/** Validated immutable route describing an agent, Task kind, purpose, and permissions. */
+type AgentRoute = Readonly<Omit<z.infer<typeof agentRouteSchema>, "permissions"> & {
+  readonly permissions: readonly string[];
+}>;
+/** Caller input accepted when registering an agent route, before defaults are applied. */
+interface AgentRouteInput {
+  readonly id: string;
+  readonly version?: number;
+  readonly agent: string;
+  readonly taskKind: TaskKind;
+  readonly description: string;
+  readonly permissions?: readonly string[];
+}
+/** Task work with a required exact agent-route binding. */
+type RoutedTaskWork<Input extends JsonValue = JsonValue, Route extends AgentRouteBinding = AgentRouteBinding> = Omit<TaskWork<Input>, "route"> & {
+  readonly route: Route;
+};
+/** Named fields for constructing generic work bound to an exact agent route. */
+interface RouteTaskWorkOptions<Route extends AgentRouteBinding = AgentRouteBinding, Input extends JsonValue = JsonValue> {
+  readonly route: Route;
+  readonly title: string;
+  readonly input?: Input;
+  readonly workflow?: never;
+  readonly completionCriteria?: never;
+}
+/** Produces the canonical `id@version` lookup key for a route binding. */
+declare function routeKey<const Binding extends AgentRouteBinding>(binding: Binding): AgentRouteKey<Binding["id"], Binding["version"]>;
+/** Constructs generic Task work bound to the selected exact agent route. */
+declare function routeTaskWork<const Route extends AgentRouteBinding, const Input extends JsonValue = JsonValue>(options: RouteTaskWorkOptions<Route, Input>): RoutedTaskWork<Input, AgentRouteBinding<Route["id"], Route["version"]>>;
+type RegisteredAgentRoute<Input extends AgentRouteInput> = Input extends AgentRouteInput ? AgentRouteBinding<Input["id"], Input extends {
+  readonly version: infer Version extends number;
+} ? Version : 1> & Readonly<Omit<Input, "version" | "permissions"> & {
+  readonly version: Input extends {
+    readonly version: infer Version extends number;
+  } ? Version : 1;
+  readonly permissions: readonly string[];
+}> : never;
+/** Immutable registry for exact agent-route lookup and unambiguous admission selection. */
+interface AgentRouteRegistry<out Route extends AgentRoute = AgentRoute> {
+  readonly routes: readonly Route[];
+  /** Returns only the exact route binding supplied; never defaults a version. */
+  get<const Binding extends AgentRouteBinding>(binding: Binding): (Route & Readonly<Binding>) | undefined;
+  /** Lists every registered route for a descriptive Task kind in registration order. */
+  listForTaskKind<const Kind extends string>(kind: Kind): readonly (Route & {
+    readonly taskKind: Kind;
+  })[];
+}
+type RegisteredAgentRoutes<Input extends readonly AgentRouteInput[]> = [Input[number]] extends [never] ? AgentRoute : RegisteredAgentRoute<Input[number]>;
+/** Descriptions inform judgment; exact registered bindings remain the authority. */
+declare function defineAgentRoutes<const Input extends readonly AgentRouteInput[]>(inputs: Input): AgentRouteRegistry<RegisteredAgentRoutes<Input>>;
+//#endregion
+export { AgentRoute, type AgentRouteBinding, type AgentRouteBindingInput, AgentRouteInput, AgentRouteKey, AgentRouteRegistry, RouteTaskWorkOptions, RoutedTaskWork, agentRouteBindingSchema, agentRouteSchema, defineAgentRoutes, parseAgentRouteBinding, routeKey, routeTaskWork };
+//# sourceMappingURL=agent-routes.d.mts.map

package/dist/agent-routes.mjs

@@ -0,0 +1,64 @@
+import { agentRouteBindingSchema, parseAgentRouteBinding } from "./schema/agent-route.mjs";
+import { taskWork } from "./schema/work.mjs";
+import { taskKindSchema } from "./schema/task.mjs";
+import { z } from "zod";
+//#region src/agent-routes.ts
+/** Validates an exact-version route from workflow work to one configured agent. */
+const agentRouteSchema = z.strictObject({
+	id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/u).describe("Stable route selected by a conversational agent or workflow."),
+	version: z.number().int().positive().default(1).describe("Exact version of this agent route; defaults to 1 at registration."),
+	agent: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/u).describe("Internally addressable Eve agent that executes this route."),
+	taskKind: taskKindSchema.describe("Factory task kind created for this route."),
+	description: z.string().min(1).max(500).describe("Model-facing guidance for when this route is appropriate."),
+	permissions: z.array(z.string().min(1)).readonly().default([]).describe("Inspectable capabilities granted to the target agent.")
+}).brand();
+/** Produces the canonical `id@version` lookup key for a route binding. */
+function routeKey(binding) {
+	return `${binding.id}@${binding.version}`;
+}
+const routeBinding = (route) => Object.freeze(parseAgentRouteBinding({
+	id: route.id,
+	version: route.version
+}));
+function routeTaskWork(options) {
+	const { route, title, input = {} } = options;
+	return {
+		...taskWork({
+			title,
+			input
+		}),
+		route: routeBinding(route)
+	};
+}
+/** Descriptions inform judgment; exact registered bindings remain the authority. */
+function defineAgentRoutes(inputs) {
+	const routes = Object.freeze(inputs.map((input) => {
+		const route = agentRouteSchema.parse(input);
+		return Object.freeze({
+			...route,
+			permissions: Object.freeze([...route.permissions])
+		});
+	}));
+	const byBinding = /* @__PURE__ */ new Map();
+	const byTaskKind = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = routeKey(route);
+		if (byBinding.has(key)) throw new Error(`Agent route ${key} is registered more than once.`);
+		byBinding.set(key, route);
+		const matchingRoutes = byTaskKind.get(route.taskKind) ?? [];
+		byTaskKind.set(route.taskKind, Object.freeze([...matchingRoutes, route]));
+	}
+	return Object.freeze({
+		routes,
+		get(binding) {
+			return byBinding.get(routeKey(routeBinding(binding)));
+		},
+		listForTaskKind(kind) {
+			return byTaskKind.get(kind) ?? Object.freeze([]);
+		}
+	});
+}
+//#endregion
+export { agentRouteBindingSchema, agentRouteSchema, defineAgentRoutes, parseAgentRouteBinding, routeKey, routeTaskWork };
+
+//# sourceMappingURL=agent-routes.mjs.map

package/dist/agent-routes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-routes.mjs","names":[],"sources":["../src/agent-routes.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { parseAgentRouteBinding, type AgentRouteBinding } from \"./schema/agent-route\";\nimport { taskKindSchema, type TaskKind } from \"./schema/task\";\nimport { taskWork, type JsonValue, type TaskWork } from \"./schema/work\";\n\nexport {\n  agentRouteBindingSchema,\n  parseAgentRouteBinding,\n  type AgentRouteBinding,\n  type AgentRouteBindingInput,\n} from \"./schema/agent-route\";\n\n/** Validates an exact-version route from workflow work to one configured agent. */\nexport const agentRouteSchema = z\n  .strictObject({\n    id: z\n      .string()\n      .regex(/^[a-z][a-z0-9-]{0,63}$/u)\n      .describe(\"Stable route selected by a conversational agent or workflow.\"),\n    version: z\n      .number()\n      .int()\n      .positive()\n      .default(1)\n      .describe(\"Exact version of this agent route; defaults to 1 at registration.\"),\n    agent: z\n      .string()\n      .regex(/^[a-z][a-z0-9-]{0,31}$/u)\n      .describe(\"Internally addressable Eve agent that executes this route.\"),\n    taskKind: taskKindSchema.describe(\"Factory task kind created for this route.\"),\n    description: z\n      .string()\n      .min(1)\n      .max(500)\n      .describe(\"Model-facing guidance for when this route is appropriate.\"),\n    permissions: z\n      .array(z.string().min(1))\n      .readonly()\n      .default([])\n      .describe(\"Inspectable capabilities granted to the target agent.\"),\n  })\n  .brand<\"AgentRouteBinding\">();\n\n/** Canonical `id@version` lookup key for one exact agent route. */\nexport type AgentRouteKey<\n  Id extends string = string,\n  Version extends number = number,\n> = `${Id}@${Version}`;\n/** Validated immutable route describing an agent, Task kind, purpose, and permissions. */\nexport type AgentRoute = Readonly<\n  Omit<z.infer<typeof agentRouteSchema>, \"permissions\"> & {\n    readonly permissions: readonly string[];\n  }\n>;\n/** Caller input accepted when registering an agent route, before defaults are applied. */\nexport interface AgentRouteInput {\n  readonly id: string;\n  readonly version?: number;\n  readonly agent: string;\n  readonly taskKind: TaskKind;\n  readonly description: string;\n  readonly permissions?: readonly string[];\n}\n/** Task work with a required exact agent-route binding. */\nexport type RoutedTaskWork<\n  Input extends JsonValue = JsonValue,\n  Route extends AgentRouteBinding = AgentRouteBinding,\n> = Omit<TaskWork<Input>, \"route\"> & { readonly route: Route };\n\n/** Named fields for constructing generic work bound to an exact agent route. */\nexport interface RouteTaskWorkOptions<\n  Route extends AgentRouteBinding = AgentRouteBinding,\n  Input extends JsonValue = JsonValue,\n> {\n  readonly route: Route;\n  readonly title: string;\n  readonly input?: Input;\n  readonly workflow?: never;\n  readonly completionCriteria?: never;\n}\n\n/** Produces the canonical `id@version` lookup key for a route binding. */\nexport function routeKey<const Binding extends AgentRouteBinding>(\n  binding: Binding,\n): AgentRouteKey<Binding[\"id\"], Binding[\"version\"]> {\n  return `${binding.id}@${binding.version}`;\n}\n\nconst routeBinding = <const Route extends AgentRouteBinding>(\n  route: Route,\n): AgentRouteBinding<Route[\"id\"], Route[\"version\"]> =>\n  Object.freeze(parseAgentRouteBinding({ id: route.id, version: route.version }));\n\n/** Constructs generic Task work bound to the selected exact agent route. */\nexport function routeTaskWork<\n  const Route extends AgentRouteBinding,\n  const Input extends JsonValue = JsonValue,\n>(\n  options: RouteTaskWorkOptions<Route, Input>,\n): RoutedTaskWork<Input, AgentRouteBinding<Route[\"id\"], Route[\"version\"]>>;\nexport function routeTaskWork(options: RouteTaskWorkOptions): RoutedTaskWork {\n  const { route, title, input = {} } = options;\n  return {\n    ...taskWork({ title, input }),\n    route: routeBinding(route),\n  };\n}\n\ntype RegisteredAgentRoute<Input extends AgentRouteInput> = Input extends AgentRouteInput\n  ? AgentRouteBinding<\n      Input[\"id\"],\n      Input extends { readonly version: infer Version extends number } ? Version : 1\n    > &\n      Readonly<\n        Omit<Input, \"version\" | \"permissions\"> & {\n          readonly version: Input extends { readonly version: infer Version extends number }\n            ? Version\n            : 1;\n          readonly permissions: readonly string[];\n        }\n      >\n  : never;\n\n/** Immutable registry for exact agent-route lookup and unambiguous admission selection. */\nexport interface AgentRouteRegistry<out Route extends AgentRoute = AgentRoute> {\n  readonly routes: readonly Route[];\n  /** Returns only the exact route binding supplied; never defaults a version. */\n  get<const Binding extends AgentRouteBinding>(\n    binding: Binding,\n  ): (Route & Readonly<Binding>) | undefined;\n  /** Lists every registered route for a descriptive Task kind in registration order. */\n  listForTaskKind<const Kind extends string>(\n    kind: Kind,\n  ): readonly (Route & { readonly taskKind: Kind })[];\n}\n\ntype RegisteredAgentRoutes<Input extends readonly AgentRouteInput[]> = [Input[number]] extends [\n  never,\n]\n  ? AgentRoute\n  : RegisteredAgentRoute<Input[number]>;\n\n/** Descriptions inform judgment; exact registered bindings remain the authority. */\nexport function defineAgentRoutes<const Input extends readonly AgentRouteInput[]>(\n  inputs: Input,\n): AgentRouteRegistry<RegisteredAgentRoutes<Input>> {\n  type Route = RegisteredAgentRoutes<Input>;\n  const routes = Object.freeze(\n    inputs.map((input) => {\n      const route = agentRouteSchema.parse(input);\n      return Object.freeze({ ...route, permissions: Object.freeze([...route.permissions]) });\n    }),\n  ) as readonly Route[];\n  const byBinding = new Map<string, Route>();\n  const byTaskKind = new Map<string, readonly Route[]>();\n  for (const route of routes) {\n    const key = routeKey(route);\n    if (byBinding.has(key)) {\n      throw new Error(`Agent route ${key} is registered more than once.`);\n    }\n    byBinding.set(key, route);\n    const matchingRoutes = byTaskKind.get(route.taskKind) ?? [];\n    byTaskKind.set(route.taskKind, Object.freeze([...matchingRoutes, route]));\n  }\n  return Object.freeze({\n    routes,\n    get<const Binding extends AgentRouteBinding>(binding: Binding) {\n      return byBinding.get(routeKey(routeBinding(binding))) as\n        | (Route & Readonly<Binding>)\n        | undefined;\n    },\n    listForTaskKind<const Kind extends string>(kind: Kind) {\n      return (byTaskKind.get(kind) ?? Object.freeze([])) as readonly (Route & {\n        readonly taskKind: Kind;\n      })[];\n    },\n  });\n}\n"],"mappings":";;;;;;AAaA,MAAa,mBAAmB,EAC7B,aAAa;CACZ,IAAI,EACD,OAAO,CAAC,CACR,MAAM,yBAAyB,CAAC,CAChC,SAAS,8DAA8D;CAC1E,SAAS,EACN,OAAO,CAAC,CACR,IAAI,CAAC,CACL,SAAS,CAAC,CACV,QAAQ,CAAC,CAAC,CACV,SAAS,mEAAmE;CAC/E,OAAO,EACJ,OAAO,CAAC,CACR,MAAM,yBAAyB,CAAC,CAChC,SAAS,4DAA4D;CACxE,UAAU,eAAe,SAAS,2CAA2C;CAC7E,aAAa,EACV,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,IAAI,GAAG,CAAC,CACR,SAAS,2DAA2D;CACvE,aAAa,EACV,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CACxB,SAAS,CAAC,CACV,QAAQ,CAAC,CAAC,CAAC,CACX,SAAS,uDAAuD;AACrE,CAAC,CAAC,CACD,MAA2B;;AAyC9B,SAAgB,SACd,SACkD;CAClD,OAAO,GAAG,QAAQ,GAAG,GAAG,QAAQ;AAClC;AAEA,MAAM,gBACJ,UAEA,OAAO,OAAO,uBAAuB;CAAE,IAAI,MAAM;CAAI,SAAS,MAAM;AAAQ,CAAC,CAAC;AAShF,SAAgB,cAAc,SAA+C;CAC3E,MAAM,EAAE,OAAO,OAAO,QAAQ,CAAC,MAAM;CACrC,OAAO;EACL,GAAG,SAAS;GAAE;GAAO;EAAM,CAAC;EAC5B,OAAO,aAAa,KAAK;CAC3B;AACF;;AAqCA,SAAgB,kBACd,QACkD;CAElD,MAAM,SAAS,OAAO,OACpB,OAAO,KAAK,UAAU;EACpB,MAAM,QAAQ,iBAAiB,MAAM,KAAK;EAC1C,OAAO,OAAO,OAAO;GAAE,GAAG;GAAO,aAAa,OAAO,OAAO,CAAC,GAAG,MAAM,WAAW,CAAC;EAAE,CAAC;CACvF,CAAC,CACH;CACA,MAAM,4BAAY,IAAI,IAAmB;CACzC,MAAM,6BAAa,IAAI,IAA8B;CACrD,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,MAAM,SAAS,KAAK;EAC1B,IAAI,UAAU,IAAI,GAAG,GACnB,MAAM,IAAI,MAAM,eAAe,IAAI,+BAA+B;EAEpE,UAAU,IAAI,KAAK,KAAK;EACxB,MAAM,iBAAiB,WAAW,IAAI,MAAM,QAAQ,KAAK,CAAC;EAC1D,WAAW,IAAI,MAAM,UAAU,OAAO,OAAO,CAAC,GAAG,gBAAgB,KAAK,CAAC,CAAC;CAC1E;CACA,OAAO,OAAO,OAAO;EACnB;EACA,IAA6C,SAAkB;GAC7D,OAAO,UAAU,IAAI,SAAS,aAAa,OAAO,CAAC,CAAC;EAGtD;EACA,gBAA2C,MAAY;GACrD,OAAQ,WAAW,IAAI,IAAI,KAAK,OAAO,OAAO,CAAC,CAAC;EAGlD;CACF,CAAC;AACH"}