@vercel/factory 0.0.14 → 0.0.16

package/dist/agent-routes.mjs

@@ -0,0 +1,91 @@
+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)
+	};
+}
+/**
+* Builds an immutable registry whose exact bindings are the routing authority.
+*
+* @remarks
+* Descriptions and permissions are inspectable guidance. They do not authorize execution and a
+* Task kind never selects a route. Persist the exact route binding on work and recover that same
+* binding after retries. Omitted versions and permissions become `1` and an empty array.
+*
+* @param inputs - Application-owned routes available to workflow and agent policy.
+* @returns A registry supporting exact lookup and descriptive Task-kind listing.
+* @throws A Zod validation error for an invalid route or an error for duplicate `id@version` keys.
+*
+* @example
+* ```ts
+* import { defineAgentRoutes } from "@vercel/factory/workflows";
+*
+* const routes = defineAgentRoutes([
+*   {
+*     id: "incident-worker",
+*     agent: "worker",
+*     taskKind: "incident",
+*     description: "Investigate one admitted incident.",
+*     permissions: ["read-repository"],
+*   },
+* ]);
+* const route = routes.routes[0];
+* ```
+*/
+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  /** Stable lowercase route identifier selected by workflows. */\n  readonly id: string;\n  /** Positive exact version. Defaults to `1` during registration. */\n  readonly version?: number;\n  /** Internally addressable Eve agent name used by the application launcher. */\n  readonly agent: string;\n  /** Descriptive Task kind created for work on this route; it does not control routing. */\n  readonly taskKind: TaskKind;\n  /** Model-facing explanation of when this route is appropriate. */\n  readonly description: string;\n  /** Inspectable capability labels; the application still enforces actual authorization. */\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  /** Immutable validated routes in registration order. */\n  readonly routes: readonly Route[];\n  /**\n   * Returns only the exact route binding supplied; never defaults a version.\n   *\n   * @param binding - Exact route ID and version to resolve.\n   * @returns The registered route, or `undefined` when that exact version is absent.\n   */\n  get<const Binding extends AgentRouteBinding>(\n    binding: Binding,\n  ): (Route & Readonly<Binding>) | undefined;\n  /**\n   * Lists every registered route for a descriptive Task kind in registration order.\n   *\n   * @param kind - Descriptive Task kind to filter by.\n   * @returns Matching routes; an empty array when none were registered.\n   */\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/**\n * Builds an immutable registry whose exact bindings are the routing authority.\n *\n * @remarks\n * Descriptions and permissions are inspectable guidance. They do not authorize execution and a\n * Task kind never selects a route. Persist the exact route binding on work and recover that same\n * binding after retries. Omitted versions and permissions become `1` and an empty array.\n *\n * @param inputs - Application-owned routes available to workflow and agent policy.\n * @returns A registry supporting exact lookup and descriptive Task-kind listing.\n * @throws A Zod validation error for an invalid route or an error for duplicate `id@version` keys.\n *\n * @example\n * ```ts\n * import { defineAgentRoutes } from \"@vercel/factory/workflows\";\n *\n * const routes = defineAgentRoutes([\n *   {\n *     id: \"incident-worker\",\n *     agent: \"worker\",\n *     taskKind: \"incident\",\n *     description: \"Investigate one admitted incident.\",\n *     permissions: [\"read-repository\"],\n *   },\n * ]);\n * const route = routes.routes[0];\n * ```\n */\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;;AA+C9B,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,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"}