@vercel/factory 0.0.14 → 0.0.16

package/dist/eve/invoke.mjs

@@ -0,0 +1,254 @@
+import { changeIdSchema, repositoryIdsSchema, signalIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { agentRouteBindingSchema, parseAgentRouteBinding } from "../schema/agent-route.mjs";
+import { optionalTaskIdForSession, replyToForSession, repositoryIdsForSession } from "./task-session.mjs";
+import { routeTaskWork } from "../agent-routes.mjs";
+import { dispatchTask } from "../dispatch.mjs";
+import { startEveSession } from "./session-client.mjs";
+import { z } from "zod";
+import { defineTool } from "eve/tools";
+//#region src/eve/invoke.ts
+/**
+* A tool that lets one agent hand work to another, NMA-style: the caller
+* decides to invoke; trusted code owns the how. The handoff is recorded as a
+* factory task (single-winner dispatch, receipts), then a fresh session is
+* started on the target agent carrying only the task id — never the caller's
+* context. The session start is create-once on the task attempt, so a retried
+* launch cannot duplicate that attempt while a later attempt starts fresh.
+*/
+function createInvokeAgentTool(stores, options) {
+	const doFetch = options.fetch ?? fetch;
+	return defineTool({
+		description: `${options.description} Hands the work to a separate agent in a fresh session; you will not see its reasoning. Returns the handoff task id.`,
+		inputSchema: z.object({
+			repositoryIds: repositoryIdsSchema,
+			parentTaskId: taskIdSchema.optional().describe("Your own task, when this work continues it."),
+			changeId: changeIdSchema.optional().describe("The change the target agent should work on."),
+			channel: z.string().min(1).describe("Reply connector, e.g. github."),
+			address: z.string().min(1).describe("Reply address, e.g. acme/web#41."),
+			brief: z.string().min(1).max(4e3).describe("What the target agent needs to know. Facts and references only, not your reasoning.")
+		}),
+		async execute(input) {
+			const taskInput = {
+				repositoryIds: input.repositoryIds,
+				kind: options.route.taskKind,
+				work: routeTaskWork({
+					route: options.route,
+					title: input.brief.trim().slice(0, 256),
+					input: { brief: input.brief }
+				}),
+				changeId: input.changeId,
+				replyTo: {
+					channel: input.channel,
+					address: input.address
+				}
+			};
+			const task = await stores.tasks.create(input.parentTaskId === void 0 ? {
+				...taskInput,
+				origin: { operator: "factory" }
+			} : {
+				...taskInput,
+				origin: {},
+				parentTaskId: input.parentTaskId
+			});
+			const running = await dispatchTask(stores, {
+				taskId: task.id,
+				route: options.route,
+				maxLaunchAttempts: 1,
+				budget: options.budget?.(),
+				launch: async (dispatched) => {
+					const headers = new Headers(await options.headers?.(dispatched));
+					headers.set("content-type", "application/json");
+					const token = await options.token?.();
+					if (token !== void 0) headers.set("authorization", `Bearer ${token}`);
+					const message = [
+						`You are assigned factory task ${dispatched.id}.`,
+						input.changeId === void 0 ? null : `Change under review: ${input.changeId}.`,
+						`Reply address: ${input.channel} ${input.address}.`,
+						"",
+						input.brief,
+						"",
+						"Read the task with get_task first, do the work, and record the outcome with your factory tools."
+					].filter((line) => line !== null).join("\n");
+					return startEveSession({
+						agentUrl: options.targetUrl(),
+						agentName: "target agent",
+						headers,
+						message,
+						operationId: `factory-task:${dispatched.id}:${dispatched.attempt}`,
+						fetch: doFetch
+					});
+				}
+			});
+			return {
+				taskId: running.id,
+				kind: running.kind,
+				state: running.state
+			};
+		}
+	});
+}
+/**
+* Give a conversational agent one bounded delegation surface backed by the
+* application's route registry. The caller selects a declared route; trusted
+* code owns task creation, budget enforcement, and the fresh target session.
+*/
+function createDelegateAgentTool(stores, options) {
+	const doFetch = options.fetch ?? fetch;
+	const routeSummary = options.routes.routes.map((route) => `${route.id}@${route.version}: ${route.description}`).join("\n");
+	return defineTool({
+		description: "Delegate durable work to one registered specialist. Select only a listed route; the specialist runs independently and reports its result through Factory.\n" + routeSummary,
+		inputSchema: z.object({
+			route: agentRouteBindingSchema.describe("Exact route id and version listed in this tool's description."),
+			repositoryIds: repositoryIdsSchema.refine((repositoryIds) => new Set(repositoryIds).size === repositoryIds.length, "Repository ids must be unique."),
+			signalId: signalIdSchema.optional().describe("Pending external signal this delegation accepts."),
+			parentTaskId: taskIdSchema.optional().describe("Existing task this work continues."),
+			changeId: changeIdSchema.optional().describe("Existing change the specialist should inspect."),
+			channel: z.string().min(1).describe("Originating conversation channel."),
+			address: z.string().min(1).describe("Originating conversation reply address."),
+			brief: z.string().min(1).max(4e3).describe("Facts and desired outcome, without hidden reasoning.")
+		}),
+		async execute(input, ctx) {
+			const route = options.routes.get(input.route);
+			if (route === void 0) throw new Error(`Unknown agent route ${input.route.id}@${input.route.version}.`);
+			const replyTo = {
+				channel: input.channel,
+				address: input.address
+			};
+			const auth = ctx.session.auth.initiator;
+			const attributes = auth?.attributes;
+			const boundSignal = signalIdSchema.safeParse(attributes?.factorySignalId);
+			if (attributes?.factorySignalId !== void 0 && !boundSignal.success) throw new Error("Connector-authenticated Signal context is invalid.");
+			if (boundSignal.success && input.signalId !== void 0 && input.signalId !== boundSignal.data) throw new Error("Delegation must accept its authenticated Signal.");
+			const signalId = input.signalId ?? (boundSignal.success ? boundSignal.data : void 0);
+			const boundRepositoryIds = repositoryIdsForSession(auth);
+			if (boundRepositoryIds !== null && input.repositoryIds.some((id) => !boundRepositoryIds.includes(id))) throw new Error("Delegation includes a repository outside the connector-authenticated context.");
+			const boundReplyTo = replyToForSession(auth);
+			if (boundReplyTo !== null && (boundReplyTo.channel !== replyTo.channel || boundReplyTo.address !== replyTo.address)) throw new Error("Delegation reply address does not match the authenticated conversation.");
+			for (const repositoryId of input.repositoryIds) {
+				const repository = await stores.repositories.get(repositoryId);
+				if (repository === null || !repository.enabled) throw new Error(`Repository ${repositoryId} is not enabled in this factory.`);
+			}
+			const boundChange = changeIdSchema.safeParse(attributes?.factoryChangeId);
+			if (attributes?.factoryChangeId !== void 0 && !boundChange.success) throw new Error("Connector-authenticated change context is invalid.");
+			if (input.changeId !== void 0 && boundChange.success && input.changeId !== boundChange.data) throw new Error("Delegated change does not match the connector-authenticated context.");
+			const changeId = input.changeId ?? (boundChange.success ? boundChange.data : void 0);
+			if (changeId !== void 0) {
+				if (input.repositoryIds.length !== 1) throw new Error("Delegating work on an existing Change requires exactly one repository.");
+				const change = await stores.changes.get(changeId);
+				if (change === null || change.repositoryId !== input.repositoryIds[0] || change.state !== "verifying" && change.state !== "ready") throw new Error(`Change ${changeId} is not an open pull request in the selected repository.`);
+			}
+			if (signalId !== void 0) {
+				const signal = await stores.signals.get(signalId);
+				if (signal === null) throw new Error(`Signal ${signalId} does not exist.`);
+				if (boundSignal.success && (signal.triage?.attempt !== Number(attributes?.factorySignalAttempt) || signal.triage?.state !== "running" || signal.triage.sessionId !== void 0 && signal.triage.sessionId !== ctx.session.id)) throw new Error("Delegation requires the current running Signal triage attempt.");
+				if (!input.repositoryIds.includes(signal.repositoryId) || signal.replyTo.channel !== replyTo.channel || signal.replyTo.address !== replyTo.address) throw new Error("Delegation does not match the signal's authenticated repository and reply address.");
+				if (signal.outcome !== "pending" && signal.outcome !== "accepted") throw new Error(`Signal ${signal.id} is already ${signal.outcome}.`);
+			}
+			const acceptSignal = async () => {
+				if (signalId === void 0) return;
+				if ((await stores.signals.get(signalId))?.outcome === "accepted") return;
+				await stores.signals.decide(signalId, {
+					outcome: "accepted",
+					reason: `Foreman selected ${route.id}.`
+				});
+			};
+			let parentTaskId = input.parentTaskId;
+			const boundTaskId = optionalTaskIdForSession(auth);
+			if (boundTaskId !== null && boundReplyTo?.channel === "api") {
+				const boundTask = await stores.tasks.get(boundTaskId);
+				if (boundTask?.area === "conversation") {
+					if (parentTaskId !== void 0 && parentTaskId !== boundTask.id) throw new Error("Follow-up delegation must name its authenticated conversation task as parent.");
+					parentTaskId = boundTask.id;
+				}
+			}
+			const operator = ctx.session.auth.initiator?.principalId ?? "foreman";
+			const workflowResult = await options.workflow?.({
+				stores,
+				route,
+				repositoryIds: input.repositoryIds,
+				signalId,
+				parentTaskId,
+				changeId,
+				replyTo,
+				brief: input.brief,
+				operator,
+				dispatch: (task) => dispatchRouteTask(stores, options, doFetch, route, task, changeId, input.brief)
+			});
+			if (workflowResult !== void 0 && workflowResult !== null) {
+				await acceptSignal();
+				return workflowResult;
+			}
+			const taskInput = {
+				repositoryIds: input.repositoryIds,
+				kind: route.taskKind,
+				work: routeTaskWork({
+					route,
+					title: input.brief.trim().slice(0, 256),
+					input: { brief: input.brief }
+				}),
+				replyTo,
+				changeId,
+				...signalId === void 0 ? {} : { dedupeKey: `route:${signalId}:${route.id}:${route.version}` }
+			};
+			const task = await stores.tasks.create(parentTaskId !== void 0 ? {
+				...taskInput,
+				parentTaskId,
+				origin: {}
+			} : signalId !== void 0 ? {
+				...taskInput,
+				origin: { signalId }
+			} : {
+				...taskInput,
+				origin: { operator }
+			});
+			await acceptSignal();
+			const running = task.state === "queued" ? await dispatchRouteTask(stores, options, doFetch, route, task, changeId, input.brief) : task;
+			return {
+				taskId: running.id,
+				route: parseAgentRouteBinding({
+					id: route.id,
+					version: route.version
+				}),
+				agent: route.agent,
+				state: running.state
+			};
+		}
+	});
+}
+async function dispatchRouteTask(stores, options, doFetch, route, task, changeId, brief) {
+	return dispatchTask(stores, {
+		taskId: task.id,
+		route,
+		maxLaunchAttempts: options.maxLaunchAttempts?.(route) ?? 1,
+		budget: options.budget?.(route),
+		launch: async (dispatched) => {
+			if (options.launch) return options.launch({
+				task: dispatched,
+				route,
+				brief
+			});
+			const headers = new Headers(await options.headers?.(dispatched, route));
+			headers.set("content-type", "application/json");
+			const token = await options.token?.(route);
+			if (token !== void 0) headers.set("authorization", `Bearer ${token}`);
+			const message = [
+				`You are assigned factory task ${dispatched.id} through route ${route.id}.`,
+				changeId === void 0 ? null : `Change under review: ${changeId}.`,
+				brief,
+				"Read the task first and return exactly one bounded Factory outcome."
+			].filter((line) => line !== null).join("\n\n");
+			return startEveSession({
+				agentUrl: options.targetUrl(route),
+				agentName: route.agent,
+				headers,
+				message,
+				operationId: `factory-task:${dispatched.id}:${dispatched.attempt}`,
+				fetch: doFetch
+			});
+		}
+	});
+}
+//#endregion
+export { createDelegateAgentTool, createInvokeAgentTool };
+
+//# sourceMappingURL=invoke.mjs.map

package/dist/eve/invoke.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.mjs","names":[],"sources":["../../src/eve/invoke.ts"],"sourcesContent":["import { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport {\n  agentRouteBindingSchema,\n  parseAgentRouteBinding,\n  routeTaskWork,\n  type AgentRoute,\n  type AgentRouteBinding,\n  type AgentRouteRegistry,\n} from \"../agent-routes\";\nimport { dispatchTask, type DispatchBudget } from \"../dispatch\";\nimport type { MaybePromise, ReplyTo } from \"../schema/common\";\nimport {\n  changeIdSchema,\n  repositoryIdsSchema,\n  signalIdSchema,\n  taskIdSchema,\n  type ChangeId,\n  type RepositoryId,\n  type RepositoryIds,\n  type SignalId,\n  type TaskId,\n} from \"../schema/id\";\nimport type { ExecutionReference, Task, TaskKind, TaskState } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  optionalTaskIdForSession,\n  repositoryIdsForSession,\n  replyToForSession,\n} from \"./task-session\";\nimport { startEveSession } from \"./session-client\";\n\n/** Graph, receipt, and Task capabilities required by the fixed-route invocation tool. */\nexport type InvokeAgentToolStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** Durable capabilities required by route-based agent delegation. */\nexport type DelegateAgentToolStores = Pick<\n  FactoryStores,\n  \"changes\" | \"graphs\" | \"receipts\" | \"repositories\" | \"signals\" | \"tasks\" | \"work\"\n>;\n\n/** Configures one fixed agent handoff route and its authenticated Eve session boundary. */\nexport interface InvokeAgentToolOptions {\n  /** Application-selected exact route for this handoff. */\n  route: AgentRoute;\n  /** Model-facing description of what the target agent does and when to invoke it. */\n  description: string;\n  /**\n   * Base URL of the target agent's eve transport, e.g.\n   * `https://factory.example.com/eve/agents/verifier`. Resolved at call time so\n   * a deployment can derive it from its own origin.\n   */\n  targetUrl: () => string;\n  /** Bearer token for the target agent's eve channel, when it requires auth. */\n  token?: () => MaybePromise<string | undefined>;\n  /** Extra headers for the session request, e.g. a deployment protection bypass. */\n  headers?: (task: Task) => MaybePromise<HeadersInit>;\n  /**\n   * Reserve-before-execution limits for the handoff dispatch, resolved at\n   * call time. Without it, handoff tasks run outside the budget.\n   */\n  budget?: () => DispatchBudget | undefined;\n  fetch?: typeof fetch;\n}\n\n/** Scope, lineage, reply destination, and brief supplied to a fixed-route handoff. */\nexport interface InvokeAgentToolInput {\n  repositoryIds: RepositoryIds;\n  parentTaskId?: TaskId;\n  changeId?: ChangeId;\n  channel: string;\n  address: string;\n  brief: string;\n}\n\n/** Durable Task identity and lifecycle returned after a fixed-route handoff launches. */\nexport interface InvokeAgentToolResult {\n  readonly taskId: TaskId;\n  readonly kind: TaskKind;\n  readonly state: TaskState;\n}\n\n/** Eve tool that launches work through one configured exact agent route. */\nexport interface InvokeAgentTool extends ToolDefinition<\n  InvokeAgentToolInput,\n  InvokeAgentToolResult\n> {\n  execute(input: InvokeAgentToolInput, ctx: ToolContext): Promise<InvokeAgentToolResult>;\n}\n\ninterface DelegateAgentToolCommonOptions {\n  routes: AgentRouteRegistry;\n  /** Retry bound for application-owned routes with a reconciler; default is one launch. */\n  maxLaunchAttempts?: (route: AgentRoute) => number;\n  budget?: (route: AgentRoute) => DispatchBudget | undefined;\n  /** Application workflow policy that may replace single-task delegation. */\n  workflow?: DelegateWorkflowPolicy;\n}\n\n/** Identifies one validated delegated Task launch on its exact registered route. */\nexport interface DelegateAgentLaunchInput {\n  readonly task: Task;\n  readonly route: AgentRoute;\n  readonly brief: string;\n}\n\n/** Delegation mode whose application owns the provider launch boundary. */\ninterface DelegateAgentCustomLaunchOptions extends DelegateAgentToolCommonOptions {\n  /** Application execution boundary, after route, scope, approval, and budget validation. */\n  launch(input: DelegateAgentLaunchInput): Promise<ExecutionReference>;\n  targetUrl?: never;\n  token?: never;\n  headers?: never;\n  fetch?: never;\n}\n\n/** Delegation mode that starts a fresh session through an Eve HTTP endpoint. */\ninterface DelegateAgentEveLaunchOptions extends DelegateAgentToolCommonOptions {\n  launch?: never;\n  targetUrl(route: AgentRoute): string;\n  token?: (route: AgentRoute) => MaybePromise<string | undefined>;\n  headers?: (task: Task, route: AgentRoute) => MaybePromise<HeadersInit>;\n  fetch?: typeof fetch;\n}\n\n/** Configures route-based delegation with one explicit launch mode and workflow policy. */\nexport type DelegateAgentToolOptions =\n  | DelegateAgentCustomLaunchOptions\n  | DelegateAgentEveLaunchOptions;\n\n/** Exact route, scope, provenance, and brief supplied to bounded agent delegation. */\nexport interface DelegateAgentToolInput {\n  route: AgentRouteBinding;\n  repositoryIds: RepositoryIds;\n  signalId?: SignalId;\n  parentTaskId?: TaskId;\n  changeId?: ChangeId;\n  channel: string;\n  address: string;\n  brief: string;\n}\n\n/** Trusted context supplied to an application-owned delegation workflow policy. */\nexport interface DelegateWorkflowInput {\n  stores: DelegateAgentToolStores;\n  route: AgentRoute;\n  repositoryIds: readonly RepositoryId[];\n  signalId?: SignalId;\n  parentTaskId?: TaskId;\n  changeId?: ChangeId;\n  replyTo: ReplyTo;\n  brief: string;\n  operator: string;\n  dispatch(task: Task): Promise<Task>;\n}\n\n/** Identifies the durable work and exact agent route selected by a delegation policy. */\nexport interface DelegateWorkflowResult {\n  readonly taskId: TaskId;\n  readonly childTaskIds?: readonly TaskId[];\n  readonly route: AgentRouteBinding;\n  readonly agent: string;\n  readonly state: Task[\"state\"];\n}\n\n/** Eve tool that delegates durable work through a registered exact agent route. */\nexport interface DelegateAgentTool extends ToolDefinition<\n  DelegateAgentToolInput,\n  DelegateWorkflowResult\n> {\n  execute(input: DelegateAgentToolInput, ctx: ToolContext): Promise<DelegateWorkflowResult>;\n}\n\n/** Application policy that may replace ordinary single-Task delegation with a workflow. */\nexport type DelegateWorkflowPolicy = (\n  input: DelegateWorkflowInput,\n) => Promise<DelegateWorkflowResult | null>;\n\n/**\n * A tool that lets one agent hand work to another, NMA-style: the caller\n * decides to invoke; trusted code owns the how. The handoff is recorded as a\n * factory task (single-winner dispatch, receipts), then a fresh session is\n * started on the target agent carrying only the task id — never the caller's\n * context. The session start is create-once on the task attempt, so a retried\n * launch cannot duplicate that attempt while a later attempt starts fresh.\n */\nexport function createInvokeAgentTool(\n  stores: InvokeAgentToolStores,\n  options: InvokeAgentToolOptions,\n): InvokeAgentTool {\n  const doFetch = options.fetch ?? fetch;\n  return defineTool({\n    description: `${options.description} Hands the work to a separate agent in a fresh session; you will not see its reasoning. Returns the handoff task id.`,\n    inputSchema: z.object({\n      repositoryIds: repositoryIdsSchema,\n      parentTaskId: taskIdSchema.optional().describe(\"Your own task, when this work continues it.\"),\n      changeId: changeIdSchema.optional().describe(\"The change the target agent should work on.\"),\n      channel: z.string().min(1).describe(\"Reply connector, e.g. github.\"),\n      address: z.string().min(1).describe(\"Reply address, e.g. acme/web#41.\"),\n      brief: z\n        .string()\n        .min(1)\n        .max(4000)\n        .describe(\n          \"What the target agent needs to know. Facts and references only, not your reasoning.\",\n        ),\n    }),\n    async execute(input) {\n      const taskInput = {\n        repositoryIds: input.repositoryIds,\n        kind: options.route.taskKind,\n        work: routeTaskWork({\n          route: options.route,\n          title: input.brief.trim().slice(0, 256),\n          input: {\n            brief: input.brief,\n          },\n        }),\n        changeId: input.changeId,\n        replyTo: { channel: input.channel, address: input.address },\n      };\n      const task = await stores.tasks.create(\n        input.parentTaskId === undefined\n          ? { ...taskInput, origin: { operator: \"factory\" } }\n          : { ...taskInput, origin: {}, parentTaskId: input.parentTaskId },\n      );\n\n      const running = await dispatchTask(stores, {\n        taskId: task.id,\n        route: options.route,\n        // Handoffs are launched by the caller, not the sweep, so a refused\n        // session must fail now — no sweep would pick a re-queued handoff up.\n        maxLaunchAttempts: 1,\n        budget: options.budget?.(),\n        launch: async (dispatched) => {\n          const headers = new Headers(await options.headers?.(dispatched));\n          headers.set(\"content-type\", \"application/json\");\n          const token = await options.token?.();\n          if (token !== undefined) {\n            headers.set(\"authorization\", `Bearer ${token}`);\n          }\n          const message = [\n            `You are assigned factory task ${dispatched.id}.`,\n            input.changeId === undefined ? null : `Change under review: ${input.changeId}.`,\n            `Reply address: ${input.channel} ${input.address}.`,\n            \"\",\n            input.brief,\n            \"\",\n            \"Read the task with get_task first, do the work, and record the outcome with your factory tools.\",\n          ]\n            .filter((line) => line !== null)\n            .join(\"\\n\");\n          return startEveSession({\n            agentUrl: options.targetUrl(),\n            agentName: \"target agent\",\n            headers,\n            message,\n            operationId: `factory-task:${dispatched.id}:${dispatched.attempt}`,\n            fetch: doFetch,\n          });\n        },\n      });\n\n      return { taskId: running.id, kind: running.kind, state: running.state };\n    },\n  });\n}\n\n/**\n * Give a conversational agent one bounded delegation surface backed by the\n * application's route registry. The caller selects a declared route; trusted\n * code owns task creation, budget enforcement, and the fresh target session.\n */\nexport function createDelegateAgentTool(\n  stores: DelegateAgentToolStores,\n  options: DelegateAgentToolOptions,\n): DelegateAgentTool {\n  const doFetch = options.fetch ?? fetch;\n  const routeSummary = options.routes.routes\n    .map((route) => `${route.id}@${route.version}: ${route.description}`)\n    .join(\"\\n\");\n  return defineTool({\n    description:\n      \"Delegate durable work to one registered specialist. Select only a listed route; \" +\n      \"the specialist runs independently and reports its result through Factory.\\n\" +\n      routeSummary,\n    inputSchema: z.object({\n      route: agentRouteBindingSchema.describe(\n        \"Exact route id and version listed in this tool's description.\",\n      ),\n      repositoryIds: repositoryIdsSchema.refine(\n        (repositoryIds) => new Set(repositoryIds).size === repositoryIds.length,\n        \"Repository ids must be unique.\",\n      ),\n      signalId: signalIdSchema\n        .optional()\n        .describe(\"Pending external signal this delegation accepts.\"),\n      parentTaskId: taskIdSchema.optional().describe(\"Existing task this work continues.\"),\n      changeId: changeIdSchema\n        .optional()\n        .describe(\"Existing change the specialist should inspect.\"),\n      channel: z.string().min(1).describe(\"Originating conversation channel.\"),\n      address: z.string().min(1).describe(\"Originating conversation reply address.\"),\n      brief: z\n        .string()\n        .min(1)\n        .max(4000)\n        .describe(\"Facts and desired outcome, without hidden reasoning.\"),\n    }),\n    async execute(input, ctx) {\n      const route = options.routes.get(input.route);\n      if (route === undefined) {\n        throw new Error(`Unknown agent route ${input.route.id}@${input.route.version}.`);\n      }\n      const replyTo = { channel: input.channel, address: input.address };\n      const auth = ctx.session.auth.initiator;\n      const attributes = auth?.attributes;\n      const boundSignal = signalIdSchema.safeParse(attributes?.factorySignalId);\n      if (attributes?.factorySignalId !== undefined && !boundSignal.success)\n        throw new Error(\"Connector-authenticated Signal context is invalid.\");\n      if (\n        boundSignal.success &&\n        input.signalId !== undefined &&\n        input.signalId !== boundSignal.data\n      )\n        throw new Error(\"Delegation must accept its authenticated Signal.\");\n      const signalId = input.signalId ?? (boundSignal.success ? boundSignal.data : undefined);\n      const boundRepositoryIds = repositoryIdsForSession(auth);\n      if (\n        boundRepositoryIds !== null &&\n        input.repositoryIds.some((id) => !boundRepositoryIds.includes(id))\n      ) {\n        throw new Error(\n          \"Delegation includes a repository outside the connector-authenticated context.\",\n        );\n      }\n      const boundReplyTo = replyToForSession(auth);\n      if (\n        boundReplyTo !== null &&\n        (boundReplyTo.channel !== replyTo.channel || boundReplyTo.address !== replyTo.address)\n      ) {\n        throw new Error(\"Delegation reply address does not match the authenticated conversation.\");\n      }\n      for (const repositoryId of input.repositoryIds) {\n        const repository = await stores.repositories.get(repositoryId);\n        if (repository === null || !repository.enabled) {\n          throw new Error(`Repository ${repositoryId} is not enabled in this factory.`);\n        }\n      }\n      const boundChange = changeIdSchema.safeParse(attributes?.factoryChangeId);\n      if (attributes?.factoryChangeId !== undefined && !boundChange.success) {\n        throw new Error(\"Connector-authenticated change context is invalid.\");\n      }\n      if (\n        input.changeId !== undefined &&\n        boundChange.success &&\n        input.changeId !== boundChange.data\n      ) {\n        throw new Error(\"Delegated change does not match the connector-authenticated context.\");\n      }\n      const changeId = input.changeId ?? (boundChange.success ? boundChange.data : undefined);\n      if (changeId !== undefined) {\n        if (input.repositoryIds.length !== 1) {\n          throw new Error(\"Delegating work on an existing Change requires exactly one repository.\");\n        }\n        const change = await stores.changes.get(changeId);\n        if (\n          change === null ||\n          change.repositoryId !== input.repositoryIds[0] ||\n          (change.state !== \"verifying\" && change.state !== \"ready\")\n        ) {\n          throw new Error(\n            `Change ${changeId} is not an open pull request in the selected repository.`,\n          );\n        }\n      }\n      if (signalId !== undefined) {\n        const signal = await stores.signals.get(signalId);\n        if (signal === null) throw new Error(`Signal ${signalId} does not exist.`);\n        if (\n          boundSignal.success &&\n          (signal.triage?.attempt !== Number(attributes?.factorySignalAttempt) ||\n            signal.triage?.state !== \"running\" ||\n            (signal.triage.sessionId !== undefined && signal.triage.sessionId !== ctx.session.id))\n        )\n          throw new Error(\"Delegation requires the current running Signal triage attempt.\");\n        if (\n          !input.repositoryIds.includes(signal.repositoryId) ||\n          signal.replyTo.channel !== replyTo.channel ||\n          signal.replyTo.address !== replyTo.address\n        ) {\n          throw new Error(\n            \"Delegation does not match the signal's authenticated repository and reply address.\",\n          );\n        }\n        if (signal.outcome !== \"pending\" && signal.outcome !== \"accepted\") {\n          throw new Error(`Signal ${signal.id} is already ${signal.outcome}.`);\n        }\n      }\n      const acceptSignal = async () => {\n        if (signalId === undefined) return;\n        const signal = await stores.signals.get(signalId);\n        if (signal?.outcome === \"accepted\") return;\n        await stores.signals.decide(signalId, {\n          outcome: \"accepted\",\n          reason: `Foreman selected ${route.id}.`,\n        });\n      };\n      let parentTaskId = input.parentTaskId;\n      const boundTaskId = optionalTaskIdForSession(auth);\n      if (boundTaskId !== null && boundReplyTo?.channel === \"api\") {\n        const boundTask = await stores.tasks.get(boundTaskId);\n        if (boundTask?.area === \"conversation\") {\n          if (parentTaskId !== undefined && parentTaskId !== boundTask.id)\n            throw new Error(\n              \"Follow-up delegation must name its authenticated conversation task as parent.\",\n            );\n          parentTaskId = boundTask.id;\n        }\n      }\n      const initiator = ctx.session.auth.initiator;\n      const operator = initiator?.principalId ?? \"foreman\";\n      const workflowResult = await options.workflow?.({\n        stores,\n        route,\n        repositoryIds: input.repositoryIds,\n        signalId,\n        parentTaskId,\n        changeId,\n        replyTo,\n        brief: input.brief,\n        operator,\n        dispatch: (task) =>\n          dispatchRouteTask(stores, options, doFetch, route, task, changeId, input.brief),\n      });\n      if (workflowResult !== undefined && workflowResult !== null) {\n        await acceptSignal();\n        return workflowResult;\n      }\n      const taskInput = {\n        repositoryIds: input.repositoryIds,\n        kind: route.taskKind,\n        work: routeTaskWork({\n          route: route,\n          title: input.brief.trim().slice(0, 256),\n          input: { brief: input.brief },\n        }),\n        replyTo,\n        changeId,\n        ...(signalId === undefined\n          ? {}\n          : { dedupeKey: `route:${signalId}:${route.id}:${route.version}` }),\n      };\n      const task = await stores.tasks.create(\n        parentTaskId !== undefined\n          ? { ...taskInput, parentTaskId, origin: {} }\n          : signalId !== undefined\n            ? { ...taskInput, origin: { signalId } }\n            : { ...taskInput, origin: { operator } },\n      );\n      await acceptSignal();\n      const running =\n        task.state === \"queued\"\n          ? await dispatchRouteTask(stores, options, doFetch, route, task, changeId, input.brief)\n          : task;\n      return {\n        taskId: running.id,\n        route: parseAgentRouteBinding({ id: route.id, version: route.version }),\n        agent: route.agent,\n        state: running.state,\n      };\n    },\n  });\n}\n\nasync function dispatchRouteTask(\n  stores: DelegateAgentToolStores,\n  options: DelegateAgentToolOptions,\n  doFetch: typeof fetch,\n  route: AgentRoute,\n  task: Task,\n  changeId: ChangeId | undefined,\n  brief: string,\n): Promise<Task> {\n  return dispatchTask(stores, {\n    taskId: task.id,\n    route,\n    maxLaunchAttempts: options.maxLaunchAttempts?.(route) ?? 1,\n    budget: options.budget?.(route),\n    launch: async (dispatched) => {\n      if (options.launch) return options.launch({ task: dispatched, route, brief });\n      const headers = new Headers(await options.headers?.(dispatched, route));\n      headers.set(\"content-type\", \"application/json\");\n      const token = await options.token?.(route);\n      if (token !== undefined) headers.set(\"authorization\", `Bearer ${token}`);\n      const message = [\n        `You are assigned factory task ${dispatched.id} through route ${route.id}.`,\n        changeId === undefined ? null : `Change under review: ${changeId}.`,\n        brief,\n        \"Read the task first and return exactly one bounded Factory outcome.\",\n      ]\n        .filter((line) => line !== null)\n        .join(\"\\n\\n\");\n      return startEveSession({\n        agentUrl: options.targetUrl(route),\n        agentName: route.agent,\n        headers,\n        message,\n        operationId: `factory-task:${dispatched.id}:${dispatched.attempt}`,\n        fetch: doFetch,\n      });\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/eve/session-client.d.mts

@@ -0,0 +1,186 @@
+import { ExecutionReference } from "../schema/task.mjs";
+import { MaybePromise } from "../schema/common.mjs";
+//#region src/eve/session-client.d.ts
+/** The minimal event shape consumed from an Eve session stream. */
+interface EveSessionEvent {
+  /** Eve protocol event discriminator. */
+  type: string;
+  /** Provider payload retained as unknown until the consuming operation validates required fields. */
+  data?: unknown;
+}
+/** Identifies and bounds a direct read of one Eve session event stream. */
+interface EveSessionStreamInput {
+  /** Base URL of the selected Eve agent. */
+  agentUrl: string;
+  /** Exact provider session whose ordered event log is read. */
+  sessionId: string;
+  /** Authentication and Factory binding headers for the stream request. */
+  headers: HeadersInit;
+  /** Cancellation or deadline signal that bounds the stream read. */
+  signal: AbortSignal;
+  /** Inclusive provider event index, or `-1` for the latest event. */
+  startIndex: number;
+  /** Whether the stream waits for events appended after the current end. */
+  follow: boolean;
+}
+/** Injectable reader for an Eve session's ordered event stream. */
+type EveSessionStream = (input: EveSessionStreamInput) => AsyncIterable<EveSessionEvent>;
+/** Configures an idempotent request to start or reconnect to an Eve session. */
+interface StartEveSessionOptions {
+  /** Base URL of the selected Eve agent; trailing slashes are ignored. */
+  agentUrl: string;
+  /** Initial user message serialized into Eve's session-create request. */
+  message: unknown;
+  /** Stable application idempotency key reused when reconnecting the same logical launch. */
+  operationId: string;
+  /** Authentication and Factory binding headers, resolved immediately before the request. */
+  headers?: MaybePromise<HeadersInit>;
+  /**
+   * HTTP implementation. Defaults to `globalThis.fetch`. Transport rejections propagate; a launch
+   * adapter that owns durable recovery must translate ambiguous acceptance at its boundary.
+   */
+  fetch?: typeof globalThis.fetch;
+  /** Request deadline in milliseconds. Defaults to 20,000. */
+  timeoutMs?: number;
+  /** Human-readable agent name included in refusal diagnostics. Defaults to `Eve agent`. */
+  agentName?: string;
+}
+/**
+ * Starts or reconnects to one Eve session through its idempotent HTTP boundary.
+ *
+ * @remarks
+ * This call sends one POST to the selected agent's `/eve/v1/session` endpoint. Reusing
+ * `operationId` asks Eve to return the same logical session rather than create duplicate work.
+ * The returned execution reference identifies provider acceptance only; Factory dispatch must
+ * still persist it, and the agent must later complete or otherwise advance its Task.
+ *
+ * An HTTP refusal throws a regular error with the status. A successful response without a usable
+ * session ID throws `ExecutionLaunchPendingError`, because the provider may have accepted work and
+ * recovery must use the same operation ID. Request timeouts and transport failures propagate
+ * unchanged because this transport helper does not own a durable retry loop. A launcher that can
+ * recover the same running attempt must translate an ambiguous transport failure to
+ * `ExecutionLaunchPendingError` at that boundary and retry with the same operation ID.
+ *
+ * @param options - Agent URL, initial message, stable operation ID, and optional request controls.
+ * @returns An Eve execution reference containing the accepted session ID.
+ * @throws `ExecutionLaunchPendingError` after an accepted response without a session ID, and a
+ * regular error on timeout, transport failure, HTTP refusal, or invalid input.
+ * @see The shipped `docs/recipes/eve-agent.md` recipe for the complete dispatch boundary.
+ *
+ * @example
+ * ```ts
+ * import { startEveSession, taskHeaders } from "@vercel/factory";
+ * import type { TaskAttemptRef } from "@vercel/factory/execution";
+ *
+ * declare const task: TaskAttemptRef;
+ * const execution = await startEveSession({
+ *   agentUrl: "https://factory.example/eve/agents/worker",
+ *   message: `Work Task ${task.taskId}`,
+ *   operationId: `factory-task:${task.taskId}:${task.attempt}`,
+ *   headers: taskHeaders(task),
+ * });
+ * ```
+ */
+declare function startEveSession(options: StartEveSessionOptions): Promise<ExecutionReference>;
+/** Configures forwarding an authorized HTTP request to one exact Eve session. */
+interface ForwardEveSessionRequestOptions {
+  /** Base URL of the selected Eve agent; trailing slashes are ignored. */
+  agentUrl: string;
+  /** Exact provider session that owns the forwarded Factory API request. */
+  sessionId: string;
+  /** Empty for the session endpoint, otherwise an absolute path/query suffix within it; fragments are refused. */
+  path: string;
+  /** Incoming request supplying method, abort signal, and POST body. */
+  source: Request;
+  /** Authentication and Factory binding headers, resolved immediately before forwarding. */
+  headers?: MaybePromise<HeadersInit>;
+  /** HTTP implementation. Defaults to `globalThis.fetch`. */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * Forwards one authorized Factory API request to its exact Eve session.
+ *
+ * @remarks
+ * The caller must authenticate and authorize the source request before invoking this helper. It
+ * forwards the source method, abort signal, and POST body using the supplied binding headers, then
+ * returns Eve's response unchanged. It does not interpret non-success status codes, retry the
+ * request, or update Factory Task state, so callers retain operation-specific response and replay
+ * handling.
+ *
+ * @param options - Exact Eve session, path, authorized source request, and transport controls.
+ * @returns The unconsumed response from the Eve session endpoint.
+ * @throws When a nonempty path is not absolute, resolves outside the session, contains a fragment,
+ * or the request transport fails.
+ */
+declare function forwardEveSessionRequest(options: ForwardEveSessionRequestOptions): Promise<Response>;
+/** Configures cancellation and provider-stream confirmation for one exact Eve session. */
+interface CancelEveSessionOptions {
+  /** Base URL of the selected Eve agent; trailing slashes are ignored. */
+  agentUrl: string;
+  /** Exact provider session to cancel and observe. */
+  sessionId: string;
+  /** Authentication and Factory binding headers used for cancellation and confirmation. */
+  headers?: MaybePromise<HeadersInit>;
+  /** HTTP implementation. Defaults to `globalThis.fetch`. */
+  fetch?: typeof globalThis.fetch;
+  /** Cancellation request deadline in milliseconds. Defaults to 10,000. */
+  requestTimeoutMs?: number;
+  /** Provider-stream confirmation deadline in milliseconds. Defaults to 5,000. */
+  confirmationTimeoutMs?: number;
+  /** Injectable ordered event reader. Defaults to the Eve client stream. */
+  stream?: EveSessionStream;
+}
+/**
+ * Requests cancellation and confirms that the exact Eve session has stopped running.
+ *
+ * @remarks
+ * A successful cancellation response is not sufficient by itself. Unless Eve reports
+ * `no_active_turn`, this helper follows from the latest provider event and returns only after
+ * observing `session.waiting`, `session.completed`, or `session.failed`. A refusal, timeout, stream
+ * failure, or non-confirming event throws; the caller should keep canonical Task cancellation and
+ * retry or inspect this same session rather than assume it stopped.
+ *
+ * This helper does not transition or settle a Factory Task. Use the higher-level execution
+ * cancellation flow when Task lifecycle and usage must be persisted together.
+ *
+ * @param options - Exact Eve session plus request and confirmation bounds.
+ * @returns After the provider confirms that the session has no active turn.
+ * @throws On HTTP refusal, request or confirmation timeout, stream failure, or missing confirmation.
+ */
+declare function cancelEveSession(options: CancelEveSessionOptions): Promise<void>;
+/** Configures a bounded scan for the response from the latest completed Eve turn. */
+interface ReadCompletedEveTurnOptions {
+  /** Base URL of the selected Eve agent; trailing slashes are ignored. */
+  agentUrl: string;
+  /** Exact provider session whose finite event history is scanned. */
+  sessionId: string;
+  /** Authentication and Factory binding headers for the stream request. */
+  headers?: MaybePromise<HeadersInit>;
+  /** Event-stream read deadline in milliseconds. Defaults to 10,000. */
+  timeoutMs?: number;
+  /** Maximum events inspected before returning `null`. Defaults to 10,000. */
+  maxEvents?: number;
+  /** HTTP implementation used by the default bounded stream reader. Defaults to `globalThis.fetch`. */
+  fetch?: typeof globalThis.fetch;
+  /** Injectable ordered event reader; it must propagate transport failures to preserve certainty. */
+  stream?: EveSessionStream;
+}
+/**
+ * Reads the response from the latest fully completed Eve turn, if one exists.
+ *
+ * @remarks
+ * This performs a bounded, non-following scan from the start of the session. It returns a nonempty
+ * completed message only when the matching latest turn reaches `turn.completed`; failed,
+ * cancelled, incomplete, over-limit, or message-less turns return `null`. The operation is
+ * read-only and safe to repeat. The default reader verifies that it reached Eve's advertised
+ * durable tail before accepting output. Transport and timeout failures are propagated so callers
+ * can distinguish unavailable or truncated history from a confirmed lack of completed output.
+ *
+ * @param options - Exact Eve session plus stream deadline and event bound.
+ * @returns The latest completed turn response, or `null` when no bounded complete response exists.
+ * @throws When the event stream cannot be read or its deadline expires.
+ */
+declare function readCompletedEveTurn(options: ReadCompletedEveTurnOptions): Promise<string | null>;
+//#endregion
+export { CancelEveSessionOptions, EveSessionEvent, EveSessionStream, EveSessionStreamInput, ForwardEveSessionRequestOptions, ReadCompletedEveTurnOptions, StartEveSessionOptions, cancelEveSession, forwardEveSessionRequest, readCompletedEveTurn, startEveSession };
+//# sourceMappingURL=session-client.d.mts.map