@vercel/factory 0.0.13 → 0.0.15

package/dist/eve/invoke.mjs

@@ -0,0 +1,241 @@
+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 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 (input.signalId !== void 0) {
+				const signal = await stores.signals.get(input.signalId);
+				if (signal === null) throw new Error(`Signal ${input.signalId} does not exist.`);
+				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") await stores.signals.decide(signal.id, {
+					outcome: "accepted",
+					reason: `Foreman selected ${route.id}.`
+				});
+				else if (signal.outcome !== "accepted") throw new Error(`Signal ${signal.id} is already ${signal.outcome}.`);
+			}
+			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: input.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) 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,
+				...input.signalId === void 0 ? {} : { dedupeKey: `route:${input.signalId}:${route.id}:${route.version}` }
+			};
+			const task = await stores.tasks.create(parentTaskId !== void 0 ? {
+				...taskInput,
+				parentTaskId,
+				origin: {}
+			} : input.signalId !== void 0 ? {
+				...taskInput,
+				origin: { signalId: input.signalId }
+			} : {
+				...taskInput,
+				origin: { operator }
+			});
+			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 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 (input.signalId !== undefined) {\n        const signal = await stores.signals.get(input.signalId);\n        if (signal === null) throw new Error(`Signal ${input.signalId} does not exist.`);\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\") {\n          await stores.signals.decide(signal.id, {\n            outcome: \"accepted\",\n            ...{\n              reason: `Foreman selected ${route.id}.`,\n            },\n          });\n        } else if (signal.outcome !== \"accepted\") {\n          throw new Error(`Signal ${signal.id} is already ${signal.outcome}.`);\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: input.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) return workflowResult;\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        ...(input.signalId === undefined\n          ? {}\n          : { dedupeKey: `route:${input.signalId}:${route.id}:${route.version}` }),\n      };\n      const task = await stores.tasks.create(\n        parentTaskId !== undefined\n          ? { ...taskInput, parentTaskId, origin: {} }\n          : input.signalId !== undefined\n            ? { ...taskInput, origin: { signalId: input.signalId } }\n            : { ...taskInput, origin: { operator } },\n      );\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,68 @@
+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 {
+  type: string;
+  data?: unknown;
+}
+/** Identifies and bounds a direct read of one Eve session event stream. */
+interface EveSessionStreamInput {
+  agentUrl: string;
+  sessionId: string;
+  headers: HeadersInit;
+  signal: AbortSignal;
+  startIndex: number;
+  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 {
+  agentUrl: string;
+  message: unknown;
+  operationId: string;
+  headers?: MaybePromise<HeadersInit>;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  agentName?: string;
+}
+/** Start or reconnect to an Eve session through its idempotent HTTP boundary. */
+declare function startEveSession(options: StartEveSessionOptions): Promise<ExecutionReference>;
+/** Configures forwarding an authorized HTTP request to one exact Eve session. */
+interface ForwardEveSessionRequestOptions {
+  agentUrl: string;
+  sessionId: string;
+  path: string;
+  source: Request;
+  headers?: MaybePromise<HeadersInit>;
+  fetch?: typeof globalThis.fetch;
+}
+/** Forward one authorized Factory API request to its exact Eve session. */
+declare function forwardEveSessionRequest(options: ForwardEveSessionRequestOptions): Promise<Response>;
+/** Configures cancellation and provider-stream confirmation for one exact Eve session. */
+interface CancelEveSessionOptions {
+  agentUrl: string;
+  sessionId: string;
+  headers?: MaybePromise<HeadersInit>;
+  fetch?: typeof globalThis.fetch;
+  requestTimeoutMs?: number;
+  confirmationTimeoutMs?: number;
+  stream?: EveSessionStream;
+}
+/** Request cancellation and confirm the exact Eve session has stopped running. */
+declare function cancelEveSession(options: CancelEveSessionOptions): Promise<void>;
+/** Configures a bounded scan for the response from the latest completed Eve turn. */
+interface ReadCompletedEveTurnOptions {
+  agentUrl: string;
+  sessionId: string;
+  headers?: MaybePromise<HeadersInit>;
+  timeoutMs?: number;
+  maxEvents?: number;
+  stream?: EveSessionStream;
+}
+/** Read the response from the latest fully completed Eve turn, if one exists. */
+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

package/dist/eve/session-client.mjs

@@ -0,0 +1,131 @@
+import { ExecutionLaunchPendingError } from "../dispatch.mjs";
+import { Client } from "eve/client";
+//#region src/eve/session-client.ts
+/** Start or reconnect to an Eve session through its idempotent HTTP boundary. */
+async function startEveSession(options) {
+	const response = await (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session`, {
+		method: "POST",
+		headers: jsonHeaders(await options.headers),
+		body: JSON.stringify({
+			message: options.message,
+			operationId: options.operationId
+		}),
+		signal: AbortSignal.timeout(options.timeoutMs ?? 2e4),
+		redirect: "error"
+	});
+	if (!response.ok) {
+		await response.body?.cancel();
+		throw new Error(`${options.agentName ?? "Eve agent"} refused the session: ${response.status}`);
+	}
+	const body = await response.json().catch(() => null);
+	if (typeof body === "object" && body !== null && "sessionId" in body && typeof body.sessionId === "string" && body.sessionId !== "") return {
+		provider: "eve",
+		sessionId: body.sessionId
+	};
+	throw new ExecutionLaunchPendingError(`${options.agentName ?? "Eve agent"} accepted the request but returned no session ID`);
+}
+/** Forward one authorized Factory API request to its exact Eve session. */
+async function forwardEveSessionRequest(options) {
+	if (!options.path.startsWith("/") || options.path.startsWith("//")) throw new Error("Eve session forwarding requires an absolute path suffix.");
+	return (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session/${encodeURIComponent(options.sessionId)}${options.path}`, {
+		method: options.source.method,
+		headers: jsonHeaders(await options.headers),
+		...options.source.method === "POST" ? { body: await options.source.text() } : {},
+		signal: options.source.signal,
+		redirect: "error"
+	});
+}
+/** Request cancellation and confirm the exact Eve session has stopped running. */
+async function cancelEveSession(options) {
+	const headers = await options.headers;
+	const response = await (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session/${encodeURIComponent(options.sessionId)}/cancel`, {
+		method: "POST",
+		headers: jsonHeaders(headers),
+		body: "{}",
+		redirect: "error",
+		signal: AbortSignal.timeout(options.requestTimeoutMs ?? 1e4)
+	});
+	if (!response.ok) {
+		await response.body?.cancel();
+		throw new Error(`Eve execution cancellation refused: ${response.status}`);
+	}
+	const result = await response.json().catch(() => null);
+	if (typeof result === "object" && result !== null && "status" in result && result.status === "no_active_turn") return;
+	const signal = AbortSignal.timeout(options.confirmationTimeoutMs ?? 5e3);
+	for await (const event of (options.stream ?? streamEveSession)({
+		agentUrl: options.agentUrl,
+		sessionId: options.sessionId,
+		headers: headers ?? {},
+		signal,
+		startIndex: -1,
+		follow: true
+	})) {
+		if ([
+			"session.waiting",
+			"session.completed",
+			"session.failed"
+		].includes(event.type)) return;
+		break;
+	}
+	throw new Error("Eve execution cancellation is not yet confirmed by the provider stream");
+}
+/** Read the response from the latest fully completed Eve turn, if one exists. */
+async function readCompletedEveTurn(options) {
+	const headers = await options.headers ?? {};
+	let response = null;
+	let turnId;
+	let completed = false;
+	let count = 0;
+	for await (const event of (options.stream ?? streamEveSession)({
+		agentUrl: options.agentUrl,
+		sessionId: options.sessionId,
+		headers,
+		signal: AbortSignal.timeout(options.timeoutMs ?? 1e4),
+		startIndex: 0,
+		follow: false
+	})) {
+		if (++count > (options.maxEvents ?? 1e4)) return null;
+		const data = eventData(event);
+		if (event.type === "turn.started") {
+			turnId = typeof data.turnId === "string" ? data.turnId : void 0;
+			response = null;
+			completed = false;
+		}
+		if (event.type === "message.completed" && data.turnId === turnId && typeof data.message === "string") response = data.message;
+		if (event.type === "turn.completed" && data.turnId === turnId) completed = true;
+		if ([
+			"turn.failed",
+			"turn.cancelled",
+			"session.failed"
+		].includes(event.type)) completed = false;
+	}
+	return completed && response?.trim() ? response : null;
+}
+async function* streamEveSession(input) {
+	const client = new Client({
+		host: input.agentUrl.replace(/\/+$/u, ""),
+		headers: Object.fromEntries(new Headers(input.headers).entries()),
+		redirect: "error"
+	});
+	for await (const event of client.sessions.attach(input.sessionId).stream({
+		startIndex: input.startIndex,
+		follow: input.follow,
+		streamReconnectPolicy: { reconnect: false },
+		signal: input.signal
+	})) yield {
+		type: event.type,
+		..."data" in event ? { data: event.data } : {}
+	};
+}
+function eventData(event) {
+	return typeof event.data === "object" && event.data !== null && !Array.isArray(event.data) ? event.data : {};
+}
+function jsonHeaders(input) {
+	const headers = new Headers(input);
+	if (!headers.has("content-type")) headers.set("content-type", "application/json");
+	return Object.fromEntries(headers.entries());
+}
+//#endregion
+export { cancelEveSession, forwardEveSessionRequest, readCompletedEveTurn, startEveSession };
+
+//# sourceMappingURL=session-client.mjs.map

package/dist/eve/session-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-client.mjs","names":[],"sources":["../../src/eve/session-client.ts"],"sourcesContent":["import { Client } from \"eve/client\";\nimport { ExecutionLaunchPendingError } from \"../dispatch\";\nimport type { MaybePromise } from \"../schema/common\";\nimport type { ExecutionReference } from \"../schema/task\";\n\n/** The minimal event shape consumed from an Eve session stream. */\nexport interface EveSessionEvent {\n  type: string;\n  data?: unknown;\n}\n\n/** Identifies and bounds a direct read of one Eve session event stream. */\nexport interface EveSessionStreamInput {\n  agentUrl: string;\n  sessionId: string;\n  headers: HeadersInit;\n  signal: AbortSignal;\n  startIndex: number;\n  follow: boolean;\n}\n\n/** Injectable reader for an Eve session's ordered event stream. */\nexport type EveSessionStream = (input: EveSessionStreamInput) => AsyncIterable<EveSessionEvent>;\n\n/** Configures an idempotent request to start or reconnect to an Eve session. */\nexport interface StartEveSessionOptions {\n  agentUrl: string;\n  message: unknown;\n  operationId: string;\n  headers?: MaybePromise<HeadersInit>;\n  fetch?: typeof globalThis.fetch;\n  timeoutMs?: number;\n  agentName?: string;\n}\n\n/** Start or reconnect to an Eve session through its idempotent HTTP boundary. */\nexport async function startEveSession(\n  options: StartEveSessionOptions,\n): Promise<ExecutionReference> {\n  const response = await (options.fetch ?? globalThis.fetch)(\n    `${options.agentUrl.replace(/\\/+$/u, \"\")}/eve/v1/session`,\n    {\n      method: \"POST\",\n      headers: jsonHeaders(await options.headers),\n      body: JSON.stringify({ message: options.message, operationId: options.operationId }),\n      signal: AbortSignal.timeout(options.timeoutMs ?? 20_000),\n      redirect: \"error\",\n    },\n  );\n  if (!response.ok) {\n    await response.body?.cancel();\n    throw new Error(`${options.agentName ?? \"Eve agent\"} refused the session: ${response.status}`);\n  }\n  const body: unknown = await response.json().catch(() => null);\n  if (\n    typeof body === \"object\" &&\n    body !== null &&\n    \"sessionId\" in body &&\n    typeof body.sessionId === \"string\" &&\n    body.sessionId !== \"\"\n  ) {\n    return { provider: \"eve\", sessionId: body.sessionId };\n  }\n  throw new ExecutionLaunchPendingError(\n    `${options.agentName ?? \"Eve agent\"} accepted the request but returned no session ID`,\n  );\n}\n\n/** Configures forwarding an authorized HTTP request to one exact Eve session. */\nexport interface ForwardEveSessionRequestOptions {\n  agentUrl: string;\n  sessionId: string;\n  path: string;\n  source: Request;\n  headers?: MaybePromise<HeadersInit>;\n  fetch?: typeof globalThis.fetch;\n}\n\n/** Forward one authorized Factory API request to its exact Eve session. */\nexport async function forwardEveSessionRequest(\n  options: ForwardEveSessionRequestOptions,\n): Promise<Response> {\n  if (!options.path.startsWith(\"/\") || options.path.startsWith(\"//\")) {\n    throw new Error(\"Eve session forwarding requires an absolute path suffix.\");\n  }\n  return (options.fetch ?? globalThis.fetch)(\n    `${options.agentUrl.replace(/\\/+$/u, \"\")}/eve/v1/session/${encodeURIComponent(options.sessionId)}${options.path}`,\n    {\n      method: options.source.method,\n      headers: jsonHeaders(await options.headers),\n      ...(options.source.method === \"POST\" ? { body: await options.source.text() } : {}),\n      signal: options.source.signal,\n      redirect: \"error\",\n    },\n  );\n}\n\n/** Configures cancellation and provider-stream confirmation for one exact Eve session. */\nexport interface CancelEveSessionOptions {\n  agentUrl: string;\n  sessionId: string;\n  headers?: MaybePromise<HeadersInit>;\n  fetch?: typeof globalThis.fetch;\n  requestTimeoutMs?: number;\n  confirmationTimeoutMs?: number;\n  stream?: EveSessionStream;\n}\n\n/** Request cancellation and confirm the exact Eve session has stopped running. */\nexport async function cancelEveSession(options: CancelEveSessionOptions): Promise<void> {\n  const headers = await options.headers;\n  const response = await (options.fetch ?? globalThis.fetch)(\n    `${options.agentUrl.replace(/\\/+$/u, \"\")}/eve/v1/session/${encodeURIComponent(options.sessionId)}/cancel`,\n    {\n      method: \"POST\",\n      headers: jsonHeaders(headers),\n      body: \"{}\",\n      redirect: \"error\",\n      signal: AbortSignal.timeout(options.requestTimeoutMs ?? 10_000),\n    },\n  );\n  if (!response.ok) {\n    await response.body?.cancel();\n    throw new Error(`Eve execution cancellation refused: ${response.status}`);\n  }\n  const result: unknown = await response.json().catch(() => null);\n  if (\n    typeof result === \"object\" &&\n    result !== null &&\n    \"status\" in result &&\n    result.status === \"no_active_turn\"\n  ) {\n    return;\n  }\n  const signal = AbortSignal.timeout(options.confirmationTimeoutMs ?? 5_000);\n  for await (const event of (options.stream ?? streamEveSession)({\n    agentUrl: options.agentUrl,\n    sessionId: options.sessionId,\n    headers: headers ?? {},\n    signal,\n    startIndex: -1,\n    follow: true,\n  })) {\n    if ([\"session.waiting\", \"session.completed\", \"session.failed\"].includes(event.type)) return;\n    break;\n  }\n  throw new Error(\"Eve execution cancellation is not yet confirmed by the provider stream\");\n}\n\n/** Configures a bounded scan for the response from the latest completed Eve turn. */\nexport interface ReadCompletedEveTurnOptions {\n  agentUrl: string;\n  sessionId: string;\n  headers?: MaybePromise<HeadersInit>;\n  timeoutMs?: number;\n  maxEvents?: number;\n  stream?: EveSessionStream;\n}\n\n/** Read the response from the latest fully completed Eve turn, if one exists. */\nexport async function readCompletedEveTurn(\n  options: ReadCompletedEveTurnOptions,\n): Promise<string | null> {\n  const headers = (await options.headers) ?? {};\n  let response: string | null = null;\n  let turnId: string | undefined;\n  let completed = false;\n  let count = 0;\n  for await (const event of (options.stream ?? streamEveSession)({\n    agentUrl: options.agentUrl,\n    sessionId: options.sessionId,\n    headers,\n    signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),\n    startIndex: 0,\n    follow: false,\n  })) {\n    if (++count > (options.maxEvents ?? 10_000)) return null;\n    const data = eventData(event);\n    if (event.type === \"turn.started\") {\n      turnId = typeof data.turnId === \"string\" ? data.turnId : undefined;\n      response = null;\n      completed = false;\n    }\n    if (\n      event.type === \"message.completed\" &&\n      data.turnId === turnId &&\n      typeof data.message === \"string\"\n    ) {\n      response = data.message;\n    }\n    if (event.type === \"turn.completed\" && data.turnId === turnId) completed = true;\n    if ([\"turn.failed\", \"turn.cancelled\", \"session.failed\"].includes(event.type)) {\n      completed = false;\n    }\n  }\n  return completed && response?.trim() ? response : null;\n}\n\nasync function* streamEveSession(input: EveSessionStreamInput): AsyncIterable<EveSessionEvent> {\n  const client = new Client({\n    host: input.agentUrl.replace(/\\/+$/u, \"\"),\n    headers: Object.fromEntries(new Headers(input.headers).entries()),\n    redirect: \"error\",\n  });\n  for await (const event of client.sessions.attach(input.sessionId).stream({\n    startIndex: input.startIndex,\n    follow: input.follow,\n    streamReconnectPolicy: { reconnect: false },\n    signal: input.signal,\n  })) {\n    yield { type: event.type, ...(\"data\" in event ? { data: event.data } : {}) };\n  }\n}\n\nfunction eventData(event: EveSessionEvent): Record<string, unknown> {\n  return typeof event.data === \"object\" && event.data !== null && !Array.isArray(event.data)\n    ? (event.data as Record<string, unknown>)\n    : {};\n}\n\nfunction jsonHeaders(input?: HeadersInit): Record<string, string> {\n  const headers = new Headers(input);\n  if (!headers.has(\"content-type\")) headers.set(\"content-type\", \"application/json\");\n  return Object.fromEntries(headers.entries());\n}\n"],"mappings":"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"}

package/dist/eve/task-execution.mjs

@@ -0,0 +1,18 @@
+import { factoryTaskAttemptAttribute, factoryTaskAttribute, taskBindingForSession } from "./task-session.mjs";
+//#region src/eve/task-execution.ts
+async function requireTaskExecution(stores, ctx, requestedTaskId) {
+	const auth = ctx.session?.auth;
+	const binding = taskBindingForSession(auth?.initiator);
+	if (binding.taskId !== requestedTaskId) throw new Error("Task does not match the authenticated session");
+	for (const key of [factoryTaskAttribute, factoryTaskAttemptAttribute]) {
+		const current = auth?.current?.attributes[key];
+		if (current !== void 0 && current !== auth?.initiator?.attributes[key]) throw new Error("Task binding does not match the current authentication");
+	}
+	const task = await stores.tasks.get(binding.taskId);
+	if (task?.state !== "running" || task.attempt !== binding.attempt || task.execution?.provider !== "eve" || task.execution.sessionId !== ctx.session.id) throw new Error("Task execution is missing, inactive, or replaced");
+	return task;
+}
+//#endregion
+export { requireTaskExecution };
+
+//# sourceMappingURL=task-execution.mjs.map

package/dist/eve/task-execution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-execution.mjs","names":[],"sources":["../../src/eve/task-execution.ts"],"sourcesContent":["import type { SessionContext } from \"eve/context\";\nimport type { TaskId } from \"../schema/id\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  factoryTaskAttribute,\n  factoryTaskAttemptAttribute,\n  taskBindingForSession,\n} from \"./task-session\";\n\nexport async function requireTaskExecution(\n  stores: Pick<FactoryStores, \"tasks\">,\n  ctx: Pick<SessionContext, \"session\">,\n  requestedTaskId: TaskId,\n) {\n  const auth = ctx.session?.auth;\n  const binding = taskBindingForSession(auth?.initiator);\n  if (binding.taskId !== requestedTaskId) {\n    throw new Error(\"Task does not match the authenticated session\");\n  }\n  for (const key of [factoryTaskAttribute, factoryTaskAttemptAttribute]) {\n    const current = auth?.current?.attributes[key];\n    if (current !== undefined && current !== auth?.initiator?.attributes[key]) {\n      throw new Error(\"Task binding does not match the current authentication\");\n    }\n  }\n  const task = await stores.tasks.get(binding.taskId);\n  if (\n    task?.state !== \"running\" ||\n    task.attempt !== binding.attempt ||\n    task.execution?.provider !== \"eve\" ||\n    task.execution.sessionId !== ctx.session.id\n  ) {\n    throw new Error(\"Task execution is missing, inactive, or replaced\");\n  }\n  return task;\n}\n"],"mappings":";;AASA,eAAsB,qBACpB,QACA,KACA,iBACA;CACA,MAAM,OAAO,IAAI,SAAS;CAC1B,MAAM,UAAU,sBAAsB,MAAM,SAAS;CACrD,IAAI,QAAQ,WAAW,iBACrB,MAAM,IAAI,MAAM,+CAA+C;CAEjE,KAAK,MAAM,OAAO,CAAC,sBAAsB,2BAA2B,GAAG;EACrE,MAAM,UAAU,MAAM,SAAS,WAAW;EAC1C,IAAI,YAAY,KAAA,KAAa,YAAY,MAAM,WAAW,WAAW,MACnE,MAAM,IAAI,MAAM,wDAAwD;CAE5E;CACA,MAAM,OAAO,MAAM,OAAO,MAAM,IAAI,QAAQ,MAAM;CAClD,IACE,MAAM,UAAU,aAChB,KAAK,YAAY,QAAQ,WACzB,KAAK,WAAW,aAAa,SAC7B,KAAK,UAAU,cAAc,IAAI,QAAQ,IAEzC,MAAM,IAAI,MAAM,kDAAkD;CAEpE,OAAO;AACT"}

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

@@ -0,0 +1,87 @@
+import { RepositoryId, TaskId } from "../schema/id.mjs";
+import { ReplyTo } from "../schema/common.mjs";
+import { TaskAttemptRef } from "../schema/execution.mjs";
+import { AuthFn } from "eve/channels/auth";
+import { SessionContext } from "eve/context";
+//#region src/eve/task-session.d.ts
+/** HTTP header that carries the authenticated Factory Task ID into an Eve session. */
+declare const factoryTaskHeader = "x-factory-task-id";
+/** Eve authentication attribute that stores the bound Factory Task ID. */
+declare const factoryTaskAttribute = "factoryTaskId";
+/** HTTP header that carries the Task attempt fence into an Eve session. */
+declare const factoryTaskAttemptHeader = "x-factory-task-attempt";
+/** Eve authentication attribute that stores the bound Task attempt fence. */
+declare const factoryTaskAttemptAttribute = "factoryTaskAttempt";
+/** HTTP header that carries the authenticated repository authorization envelope. */
+declare const factoryRepositoryIdsHeader = "x-factory-repository-ids";
+/** HTTP header that carries the authenticated conversation reply channel. */
+declare const factoryReplyChannelHeader = "x-factory-reply-channel";
+/** HTTP header that carries the authenticated conversation reply address. */
+declare const factoryReplyAddressHeader = "x-factory-reply-address";
+/** Eve authentication attribute that stores the authorized repository IDs. */
+declare const factoryRepositoryIdsAttribute = "factoryRepositoryIds";
+/** Eve authentication attribute that stores the conversation reply channel. */
+declare const factoryReplyChannelAttribute = "factoryReplyChannel";
+/** Eve authentication attribute that stores the conversation reply address. */
+declare const factoryReplyAddressAttribute = "factoryReplyAddress";
+type SessionInitiator = SessionContext["session"]["auth"]["initiator"];
+type AuthenticatedSessionInitiator = NonNullable<SessionInitiator>;
+/** The repository authorization envelope and reply destination bound to a conversation. */
+interface FactoryConversationSessionBinding {
+  repositoryIds: readonly RepositoryId[];
+  replyTo: ReplyTo;
+}
+/** Test whether authenticated Eve session state declares a Factory Task binding. */
+declare function hasFactoryTaskBinding(auth: SessionInitiator): boolean;
+/** Encode a Task ID and attempt fence as headers for an Eve session request. */
+declare function taskHeaders(task: TaskAttemptRef): Record<string, string>;
+/** Encode a conversation's repository scope and reply destination as Eve request headers. */
+declare function conversationHeaders(input: {
+  repositoryIds: readonly RepositoryId[];
+  replyTo: ReplyTo;
+}): Record<string, string>;
+/** Add a validated Task ID and attempt fence to an authenticated Eve initiator. */
+declare function taskSessionAuth(auth: AuthenticatedSessionInitiator, task: TaskAttemptRef): AuthenticatedSessionInitiator;
+/** Require valid Factory Task headers and bind them into the authenticated Eve initiator. */
+declare function withFactoryTask(authenticate: AuthFn<Request>): AuthFn<Request>;
+/** Bind optional Task and conversation headers while rejecting partial or malformed context. */
+declare function withOptionalFactoryTask(authenticate: AuthFn<Request>): AuthFn<Request>;
+/** Read the required Factory Task ID from authenticated Eve session state. */
+declare function requireTaskIdForSession(auth: SessionInitiator): TaskId;
+/** Read an optional Task ID from authenticated session state, rejecting malformed values. */
+declare function optionalTaskIdForSession(auth: SessionInitiator): TaskId | null;
+/** Read the complete, attempt-fenced Task binding established by Factory authentication. */
+declare function taskBindingForSession(auth: SessionInitiator): TaskAttemptRef;
+/** Read the repository authorization envelope, or null when the session has none. */
+declare function repositoryIdsForSession(auth: SessionInitiator): readonly RepositoryId[] | null;
+/** Read the authenticated reply destination, or null when the session has none. */
+declare function replyToForSession(auth: SessionInitiator): ReplyTo | null;
+/** Read the complete conversation binding, rejecting partial authentication state. */
+declare function conversationBindingForSession(auth: SessionInitiator): FactoryConversationSessionBinding | null;
+/** Authenticated conversation authority assembled from both initiator and current session state. */
+interface ConversationBinding {
+  replyTo: ReplyTo;
+  /**
+   * Repository envelopes the binding carries: the initiator's, plus the current
+   * auth's when it restates one. Admitted work must sit inside every envelope.
+   */
+  repositoryEnvelopes: readonly (readonly RepositoryId[])[];
+  parentTask?: TaskAttemptRef;
+}
+/**
+ * Read and validate the conversation binding carried on a session's auth pair.
+ * The initiator's attributes are authoritative; any binding attribute the
+ * current auth restates must agree with them. This is the only reader of the
+ * binding attribute encoding; callers never touch `attributes` themselves.
+ *
+ * Distinct from `conversationBindingForSession`, which reads the initiator
+ * alone: admission needs every envelope the pair carries, so that work cannot
+ * be admitted into a repository only one side of the pair authorizes.
+ */
+declare function conversationBinding(auth: {
+  initiator: AuthenticatedSessionInitiator;
+  current: AuthenticatedSessionInitiator;
+}): ConversationBinding;
+//#endregion
+export { ConversationBinding, FactoryConversationSessionBinding, conversationBinding, conversationBindingForSession, conversationHeaders, factoryReplyAddressAttribute, factoryReplyAddressHeader, factoryReplyChannelAttribute, factoryReplyChannelHeader, factoryRepositoryIdsAttribute, factoryRepositoryIdsHeader, factoryTaskAttemptAttribute, factoryTaskAttemptHeader, factoryTaskAttribute, factoryTaskHeader, hasFactoryTaskBinding, optionalTaskIdForSession, replyToForSession, repositoryIdsForSession, requireTaskIdForSession, taskBindingForSession, taskHeaders, taskSessionAuth, withFactoryTask, withOptionalFactoryTask };
+//# sourceMappingURL=task-session.d.mts.map