@vercel/factory 0.0.15 → 0.0.16

package/dist/eve/task-execution.mjs

@@ -1,6 +1,61 @@
 import { factoryTaskAttemptAttribute, factoryTaskAttribute, taskBindingForSession } from "./task-session.mjs";
 //#region src/eve/task-execution.ts
+/**
+* Requires the authenticated session's current running Eve Task execution and attempt.
+*
+* @remarks
+* `requestedTaskId` is a consistency check, not an authority source. This function reads the Task
+* and attempt established by `withFactoryTask`, rejects conflicting current-auth attributes, and
+* verifies that durable state still points to the same Eve session and attempt. Use it immediately
+* before a mutating tool applies effects or completes workflow output. A cancellation, retry, or
+* replacement session fences the stale caller out.
+*
+* The check does not complete the Task and does not make a following external side effect atomic
+* with Factory state. Pass the returned attempt and execution as the completion fence when writing
+* output.
+*
+* @param stores - Task store used to reread canonical execution state.
+* @param ctx - Eve tool or hook context containing initiator and current authentication.
+* @param requestedTaskId - Task ID from the tool input, required to match the authenticated binding.
+* @returns The currently running Task bound to this exact Eve session and attempt.
+* @throws When authentication is missing or malformed, the requested Task differs, or durable execution was replaced or stopped.
+* @see The shipped `docs/recipes/typed-eve-result.md` recipe for a complete typed tool.
+*
+* @example
+* ```ts
+* import { requireTaskExecution } from "@vercel/factory";
+* import type { FactoryStores } from "@vercel/factory/storage";
+* import type { TaskId } from "@vercel/factory/tasks";
+* import { defineWorkflow } from "@vercel/factory/workflows";
+* import type { ToolContext } from "eve/tools";
+* import { z } from "zod";
+*
+* declare const stores: FactoryStores;
+* declare const ctx: ToolContext;
+* declare const taskId: TaskId;
+* const workflow = defineWorkflow({
+*   id: "greeting",
+*   version: 1,
+*   input: z.object({ name: z.string() }),
+*   output: z.object({ message: z.string() }),
+* });
+*
+* const task = await requireTaskExecution(stores, ctx, taskId);
+* if (task.execution?.provider !== "eve") throw new Error("Expected Eve execution");
+* await stores.work.completeWorkflow({
+*   task: { taskId: task.id, attempt: task.attempt },
+*   workflow: workflow.binding,
+*   output: { message: "Hello" },
+*   fence: { from: "running", execution: task.execution },
+* });
+* ```
+*/
 async function requireTaskExecution(stores, ctx, requestedTaskId) {
+	const task = await requireTaskExecutionIdentity(stores, ctx, requestedTaskId);
+	if (task.state !== "running") throw new Error("Task execution is missing, inactive, or replaced");
+	return task;
+}
+async function requireTaskExecutionIdentity(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");
@@ -9,10 +64,10 @@ async function requireTaskExecution(stores, ctx, requestedTaskId) {
 		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");
+	if (task === null || 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 };
+export { requireTaskExecution, requireTaskExecutionIdentity };
 
 //# sourceMappingURL=task-execution.mjs.map

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

@@ -1 +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"}
+{"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\n/**\n * Requires the authenticated session's current running Eve Task execution and attempt.\n *\n * @remarks\n * `requestedTaskId` is a consistency check, not an authority source. This function reads the Task\n * and attempt established by `withFactoryTask`, rejects conflicting current-auth attributes, and\n * verifies that durable state still points to the same Eve session and attempt. Use it immediately\n * before a mutating tool applies effects or completes workflow output. A cancellation, retry, or\n * replacement session fences the stale caller out.\n *\n * The check does not complete the Task and does not make a following external side effect atomic\n * with Factory state. Pass the returned attempt and execution as the completion fence when writing\n * output.\n *\n * @param stores - Task store used to reread canonical execution state.\n * @param ctx - Eve tool or hook context containing initiator and current authentication.\n * @param requestedTaskId - Task ID from the tool input, required to match the authenticated binding.\n * @returns The currently running Task bound to this exact Eve session and attempt.\n * @throws When authentication is missing or malformed, the requested Task differs, or durable execution was replaced or stopped.\n * @see The shipped `docs/recipes/typed-eve-result.md` recipe for a complete typed tool.\n *\n * @example\n * ```ts\n * import { requireTaskExecution } from \"@vercel/factory\";\n * import type { FactoryStores } from \"@vercel/factory/storage\";\n * import type { TaskId } from \"@vercel/factory/tasks\";\n * import { defineWorkflow } from \"@vercel/factory/workflows\";\n * import type { ToolContext } from \"eve/tools\";\n * import { z } from \"zod\";\n *\n * declare const stores: FactoryStores;\n * declare const ctx: ToolContext;\n * declare const taskId: TaskId;\n * const workflow = defineWorkflow({\n *   id: \"greeting\",\n *   version: 1,\n *   input: z.object({ name: z.string() }),\n *   output: z.object({ message: z.string() }),\n * });\n *\n * const task = await requireTaskExecution(stores, ctx, taskId);\n * if (task.execution?.provider !== \"eve\") throw new Error(\"Expected Eve execution\");\n * await stores.work.completeWorkflow({\n *   task: { taskId: task.id, attempt: task.attempt },\n *   workflow: workflow.binding,\n *   output: { message: \"Hello\" },\n *   fence: { from: \"running\", execution: task.execution },\n * });\n * ```\n */\nexport async function requireTaskExecution(\n  stores: Pick<FactoryStores, \"tasks\">,\n  ctx: { session: Pick<SessionContext[\"session\"], \"id\" | \"auth\"> },\n  requestedTaskId: TaskId,\n) {\n  const task = await requireTaskExecutionIdentity(stores, ctx, requestedTaskId);\n  if (task.state !== \"running\") {\n    throw new Error(\"Task execution is missing, inactive, or replaced\");\n  }\n  return task;\n}\n\n// Completion replay also checks identity; its caller must restrict lifecycle states and effects.\nexport async function requireTaskExecutionIdentity(\n  stores: Pick<FactoryStores, \"tasks\">,\n  ctx: { session: Pick<SessionContext[\"session\"], \"id\" | \"auth\"> },\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 === null ||\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,qBACpB,QACA,KACA,iBACA;CACA,MAAM,OAAO,MAAM,6BAA6B,QAAQ,KAAK,eAAe;CAC5E,IAAI,KAAK,UAAU,WACjB,MAAM,IAAI,MAAM,kDAAkD;CAEpE,OAAO;AACT;AAGA,eAAsB,6BACpB,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,SAAS,QACT,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

@@ -33,7 +33,25 @@ interface FactoryConversationSessionBinding {
 }
 /** 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. */
+/**
+ * Encodes a Task ID and attempt fence as headers for a trusted Eve session request.
+ *
+ * @remarks
+ * These headers are a transport envelope, not standalone authorization. The receiving Eve route
+ * must authenticate the trusted caller and wrap that authentication with `withFactoryTask`.
+ *
+ * @param task - Exact Task and attempt claimed by dispatch.
+ * @returns Headers consumed by `withFactoryTask` on the target Eve channel.
+ *
+ * @example
+ * ```ts
+ * import { taskHeaders } from "@vercel/factory";
+ * import type { TaskAttemptRef } from "@vercel/factory/execution";
+ *
+ * declare const task: TaskAttemptRef;
+ * const headers = taskHeaders(task);
+ * ```
+ */
 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: {
@@ -42,7 +60,31 @@ declare function conversationHeaders(input: {
 }): 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. */
+/**
+ * Requires valid Factory Task headers and binds them into an authenticated Eve initiator.
+ *
+ * @remarks
+ * The wrapped authenticator runs first. If it returns no identity, that result is preserved. For
+ * an authenticated caller, both Factory headers are mandatory and validated before their Task ID
+ * and attempt are copied into session attributes. This records claimed identity; mutating tools
+ * call `requireTaskExecution` to recheck it against current durable Task state.
+ *
+ * Mount this wrapper only on routes reached through a trusted launcher that supplies
+ * `taskHeaders`. It does not independently verify that the caller may claim an arbitrary Task.
+ *
+ * @param authenticate - Existing Eve request authenticator for the trusted launcher.
+ * @returns An authenticator that adds the validated Factory Task binding.
+ * @throws `ForbiddenError` when either Task header is absent or malformed.
+ *
+ * @example
+ * ```ts
+ * import { withFactoryTask } from "@vercel/factory";
+ * import { localDev } from "eve/channels/auth";
+ * import { eveChannel } from "eve/channels/eve";
+ *
+ * export default eveChannel({ auth: [withFactoryTask(localDev())] });
+ * ```
+ */
 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>;

package/dist/eve/task-session.mjs

@@ -27,7 +27,25 @@ const factoryReplyAddressAttribute = "factoryReplyAddress";
 function hasFactoryTaskBinding(auth) {
 	return auth?.attributes[factoryTaskAttribute] !== void 0;
 }
-/** Encode a Task ID and attempt fence as headers for an Eve session request. */
+/**
+* Encodes a Task ID and attempt fence as headers for a trusted Eve session request.
+*
+* @remarks
+* These headers are a transport envelope, not standalone authorization. The receiving Eve route
+* must authenticate the trusted caller and wrap that authentication with `withFactoryTask`.
+*
+* @param task - Exact Task and attempt claimed by dispatch.
+* @returns Headers consumed by `withFactoryTask` on the target Eve channel.
+*
+* @example
+* ```ts
+* import { taskHeaders } from "@vercel/factory";
+* import type { TaskAttemptRef } from "@vercel/factory/execution";
+*
+* declare const task: TaskAttemptRef;
+* const headers = taskHeaders(task);
+* ```
+*/
 function taskHeaders(task) {
 	return {
 		[factoryTaskHeader]: task.taskId,
@@ -53,7 +71,31 @@ function taskSessionAuth(auth, task) {
 		}
 	};
 }
-/** Require valid Factory Task headers and bind them into the authenticated Eve initiator. */
+/**
+* Requires valid Factory Task headers and binds them into an authenticated Eve initiator.
+*
+* @remarks
+* The wrapped authenticator runs first. If it returns no identity, that result is preserved. For
+* an authenticated caller, both Factory headers are mandatory and validated before their Task ID
+* and attempt are copied into session attributes. This records claimed identity; mutating tools
+* call `requireTaskExecution` to recheck it against current durable Task state.
+*
+* Mount this wrapper only on routes reached through a trusted launcher that supplies
+* `taskHeaders`. It does not independently verify that the caller may claim an arbitrary Task.
+*
+* @param authenticate - Existing Eve request authenticator for the trusted launcher.
+* @returns An authenticator that adds the validated Factory Task binding.
+* @throws `ForbiddenError` when either Task header is absent or malformed.
+*
+* @example
+* ```ts
+* import { withFactoryTask } from "@vercel/factory";
+* import { localDev } from "eve/channels/auth";
+* import { eveChannel } from "eve/channels/eve";
+*
+* export default eveChannel({ auth: [withFactoryTask(localDev())] });
+* ```
+*/
 function withFactoryTask(authenticate) {
 	return async (request) => {
 		const auth = await authenticate(request);

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

@@ -1 +1 @@
-{"version":3,"file":"task-session.mjs","names":[],"sources":["../../src/eve/task-session.ts"],"sourcesContent":["import { repositoryIdSchema, taskIdSchema } from \"../schema/id\";\nimport { replyToSchema, type ReplyTo } from \"../schema/common\";\nimport { taskAttemptRef, type TaskAttemptRef } from \"../schema/execution\";\nimport type { RepositoryId, TaskId } from \"../schema/id\";\nimport { ForbiddenError, type AuthFn } from \"eve/channels/auth\";\nimport type { SessionContext } from \"eve/context\";\n\n/** HTTP header that carries the authenticated Factory Task ID into an Eve session. */\nexport const factoryTaskHeader = \"x-factory-task-id\";\n/** Eve authentication attribute that stores the bound Factory Task ID. */\nexport const factoryTaskAttribute = \"factoryTaskId\";\n/** HTTP header that carries the Task attempt fence into an Eve session. */\nexport const factoryTaskAttemptHeader = \"x-factory-task-attempt\";\n/** Eve authentication attribute that stores the bound Task attempt fence. */\nexport const factoryTaskAttemptAttribute = \"factoryTaskAttempt\";\n/** HTTP header that carries the authenticated repository authorization envelope. */\nexport const factoryRepositoryIdsHeader = \"x-factory-repository-ids\";\n/** HTTP header that carries the authenticated conversation reply channel. */\nexport const factoryReplyChannelHeader = \"x-factory-reply-channel\";\n/** HTTP header that carries the authenticated conversation reply address. */\nexport const factoryReplyAddressHeader = \"x-factory-reply-address\";\n/** Eve authentication attribute that stores the authorized repository IDs. */\nexport const factoryRepositoryIdsAttribute = \"factoryRepositoryIds\";\n/** Eve authentication attribute that stores the conversation reply channel. */\nexport const factoryReplyChannelAttribute = \"factoryReplyChannel\";\n/** Eve authentication attribute that stores the conversation reply address. */\nexport const factoryReplyAddressAttribute = \"factoryReplyAddress\";\n\ntype SessionInitiator = SessionContext[\"session\"][\"auth\"][\"initiator\"];\ntype AuthenticatedSessionInitiator = NonNullable<SessionInitiator>;\n\n/** The repository authorization envelope and reply destination bound to a conversation. */\nexport interface FactoryConversationSessionBinding {\n  repositoryIds: readonly RepositoryId[];\n  replyTo: ReplyTo;\n}\n\n/** Test whether authenticated Eve session state declares a Factory Task binding. */\nexport function hasFactoryTaskBinding(auth: SessionInitiator): boolean {\n  return auth?.attributes[factoryTaskAttribute] !== undefined;\n}\n\n/** Encode a Task ID and attempt fence as headers for an Eve session request. */\nexport function taskHeaders(task: TaskAttemptRef): Record<string, string> {\n  return {\n    [factoryTaskHeader]: task.taskId,\n    [factoryTaskAttemptHeader]: String(task.attempt),\n  };\n}\n\n/** Encode a conversation's repository scope and reply destination as Eve request headers. */\nexport function conversationHeaders(input: {\n  repositoryIds: readonly RepositoryId[];\n  replyTo: ReplyTo;\n}): Record<string, string> {\n  return {\n    [factoryRepositoryIdsHeader]: input.repositoryIds.join(\",\"),\n    [factoryReplyChannelHeader]: input.replyTo.channel,\n    [factoryReplyAddressHeader]: input.replyTo.address,\n  };\n}\n\n/** Add a validated Task ID and attempt fence to an authenticated Eve initiator. */\nexport function taskSessionAuth(\n  auth: AuthenticatedSessionInitiator,\n  task: TaskAttemptRef,\n): AuthenticatedSessionInitiator {\n  return {\n    ...auth,\n    attributes: {\n      ...auth.attributes,\n      [factoryTaskAttribute]: task.taskId,\n      [factoryTaskAttemptAttribute]: String(task.attempt),\n    },\n  };\n}\n\n/** Require valid Factory Task headers and bind them into the authenticated Eve initiator. */\nexport function withFactoryTask(authenticate: AuthFn<Request>): AuthFn<Request> {\n  return async (request) => {\n    const auth = await authenticate(request);\n    if (auth == null) return auth;\n    const parsedTask = taskIdSchema.safeParse(request.headers.get(factoryTaskHeader));\n    const parsedAttempt = parseTaskAttempt(request.headers.get(factoryTaskAttemptHeader));\n    if (!parsedTask.success || parsedAttempt === null) throw new ForbiddenError();\n    return taskSessionAuth(auth, taskAttemptRef(parsedTask.data, parsedAttempt));\n  };\n}\n\n/** Bind optional Task and conversation headers while rejecting partial or malformed context. */\nexport function withOptionalFactoryTask(authenticate: AuthFn<Request>): AuthFn<Request> {\n  return async (request) => {\n    const auth = await authenticate(request);\n    if (auth == null) return auth;\n    const taskId = request.headers.get(factoryTaskHeader);\n    const taskAttempt = request.headers.get(factoryTaskAttemptHeader);\n    const repositoryIds = request.headers.get(factoryRepositoryIdsHeader);\n    const replyChannel = request.headers.get(factoryReplyChannelHeader);\n    const replyAddress = request.headers.get(factoryReplyAddressHeader);\n    const hasConversationBinding =\n      repositoryIds !== null || replyChannel !== null || replyAddress !== null;\n    if (taskId === null && taskAttempt === null && !hasConversationBinding) return auth;\n    const parsedTask = taskId === null ? null : taskIdSchema.safeParse(taskId);\n    const parsedAttempt = parseTaskAttempt(taskAttempt);\n    const parsedRepositories =\n      repositoryIds === null\n        ? null\n        : repositoryIdSchema.array().min(1).safeParse(repositoryIds.split(\",\").filter(Boolean));\n    const parsedReplyTo =\n      replyChannel === null || replyAddress === null\n        ? null\n        : replyToSchema.safeParse({ channel: replyChannel, address: replyAddress });\n    if (\n      (parsedTask !== null && !parsedTask.success) ||\n      (parsedTask === null) !== (parsedAttempt === null) ||\n      (hasConversationBinding &&\n        (parsedRepositories === null ||\n          !parsedRepositories.success ||\n          parsedReplyTo === null ||\n          !parsedReplyTo.success))\n    ) {\n      throw new ForbiddenError();\n    }\n    const conversationAttributes: Record<string, string> =\n      parsedRepositories?.success === true && parsedReplyTo?.success === true\n        ? {\n            [factoryRepositoryIdsAttribute]: parsedRepositories.data.join(\",\"),\n            [factoryReplyChannelAttribute]: parsedReplyTo.data.channel,\n            [factoryReplyAddressAttribute]: parsedReplyTo.data.address,\n          }\n        : {};\n    return {\n      ...auth,\n      attributes: {\n        ...auth.attributes,\n        ...(parsedTask === null || parsedAttempt === null\n          ? {}\n          : {\n              [factoryTaskAttribute]: parsedTask.data,\n              [factoryTaskAttemptAttribute]: String(parsedAttempt),\n            }),\n        ...conversationAttributes,\n      },\n    };\n  };\n}\n\n/** Read the required Factory Task ID from authenticated Eve session state. */\nexport function requireTaskIdForSession(auth: SessionInitiator): TaskId {\n  return taskIdSchema.parse(auth?.attributes[factoryTaskAttribute]);\n}\n\n/** Read an optional Task ID from authenticated session state, rejecting malformed values. */\nexport function optionalTaskIdForSession(auth: SessionInitiator): TaskId | null {\n  const value = auth?.attributes[factoryTaskAttribute];\n  return value === undefined ? null : taskIdSchema.parse(value);\n}\n\n/** Read the complete, attempt-fenced Task binding established by Factory authentication. */\nexport function taskBindingForSession(auth: SessionInitiator): TaskAttemptRef {\n  const taskId = requireTaskIdForSession(auth);\n  const rawAttempt = auth?.attributes[factoryTaskAttemptAttribute];\n  const attempt = parseTaskAttempt(typeof rawAttempt === \"string\" ? rawAttempt : null);\n  if (attempt === null) throw new Error(\"Factory session Task attempt binding is invalid.\");\n  return { taskId, attempt };\n}\n\n/** Read the repository authorization envelope, or null when the session has none. */\nexport function repositoryIdsForSession(auth: SessionInitiator): readonly RepositoryId[] | null {\n  const value = auth?.attributes[factoryRepositoryIdsAttribute];\n  if (value === undefined) return null;\n  return repositoryIdSchema\n    .array()\n    .min(1)\n    .parse(typeof value === \"string\" ? value.split(\",\").filter(Boolean) : value);\n}\n\n/** Read the authenticated reply destination, or null when the session has none. */\nexport function replyToForSession(auth: SessionInitiator): ReplyTo | null {\n  const channel = auth?.attributes[factoryReplyChannelAttribute];\n  const address = auth?.attributes[factoryReplyAddressAttribute];\n  if (channel === undefined && address === undefined) return null;\n  return replyToSchema.parse({ channel, address });\n}\n\n/** Read the complete conversation binding, rejecting partial authentication state. */\nexport function conversationBindingForSession(\n  auth: SessionInitiator,\n): FactoryConversationSessionBinding | null {\n  const repositoryIds = repositoryIdsForSession(auth);\n  const replyTo = replyToForSession(auth);\n  if (repositoryIds === null && replyTo === null) return null;\n  if (repositoryIds === null || replyTo === null) {\n    throw new Error(\"Factory session conversation binding is incomplete.\");\n  }\n  return { repositoryIds, replyTo };\n}\n\n/** Authenticated conversation authority assembled from both initiator and current session state. */\nexport interface ConversationBinding {\n  replyTo: ReplyTo;\n  /**\n   * Repository envelopes the binding carries: the initiator's, plus the current\n   * auth's when it restates one. Admitted work must sit inside every envelope.\n   */\n  repositoryEnvelopes: readonly (readonly RepositoryId[])[];\n  parentTask?: TaskAttemptRef;\n}\n\nconst conversationBindingAttributes = [\n  factoryReplyChannelAttribute,\n  factoryReplyAddressAttribute,\n  factoryTaskAttribute,\n  factoryTaskAttemptAttribute,\n] as const;\n\n/**\n * Read and validate the conversation binding carried on a session's auth pair.\n * The initiator's attributes are authoritative; any binding attribute the\n * current auth restates must agree with them. This is the only reader of the\n * binding attribute encoding; callers never touch `attributes` themselves.\n *\n * Distinct from `conversationBindingForSession`, which reads the initiator\n * alone: admission needs every envelope the pair carries, so that work cannot\n * be admitted into a repository only one side of the pair authorizes.\n */\nexport function conversationBinding(auth: {\n  initiator: AuthenticatedSessionInitiator;\n  current: AuthenticatedSessionInitiator;\n}): ConversationBinding {\n  const attributes = auth.initiator.attributes;\n  const replyTo = replyToSchema.parse({\n    channel: attributes[factoryReplyChannelAttribute],\n    address: attributes[factoryReplyAddressAttribute],\n  });\n  for (const key of conversationBindingAttributes) {\n    if (\n      auth.current.attributes[key] !== undefined &&\n      auth.current.attributes[key] !== attributes[key]\n    )\n      throw new Error(\"Conversation binding does not match the authenticated conversation\");\n  }\n  const repositoryEnvelopes: (readonly RepositoryId[])[] = [];\n  for (const [index, entry] of [auth.initiator, auth.current].entries()) {\n    const raw = entry.attributes[factoryRepositoryIdsAttribute];\n    if (index === 1 && raw === undefined) continue;\n    repositoryEnvelopes.push(\n      repositoryIdSchema\n        .array()\n        .min(1)\n        .parse(typeof raw === \"string\" ? raw.split(\",\") : raw),\n    );\n  }\n  let parentTask: ConversationBinding[\"parentTask\"];\n  if (\n    attributes[factoryTaskAttribute] !== undefined ||\n    attributes[factoryTaskAttemptAttribute] !== undefined\n  ) {\n    const taskId = taskIdSchema.parse(attributes[factoryTaskAttribute]);\n    const rawAttempt = attributes[factoryTaskAttemptAttribute];\n    const attempt = typeof rawAttempt === \"string\" ? parseTaskAttempt(rawAttempt) : null;\n    if (attempt === null) throw new Error(\"Conversation binding carries an invalid parent attempt\");\n    parentTask = taskAttemptRef(taskId, attempt);\n  }\n  return { replyTo, repositoryEnvelopes, parentTask };\n}\n\nfunction parseTaskAttempt(value: string | null): number | null {\n  if (value === null || !/^[1-9]\\d*$/u.test(value)) return null;\n  const attempt = Number(value);\n  return Number.isSafeInteger(attempt) ? attempt : null;\n}\n"],"mappings":"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"}
+{"version":3,"file":"task-session.mjs","names":[],"sources":["../../src/eve/task-session.ts"],"sourcesContent":["import { repositoryIdSchema, taskIdSchema } from \"../schema/id\";\nimport { replyToSchema, type ReplyTo } from \"../schema/common\";\nimport { taskAttemptRef, type TaskAttemptRef } from \"../schema/execution\";\nimport type { RepositoryId, TaskId } from \"../schema/id\";\nimport { ForbiddenError, type AuthFn } from \"eve/channels/auth\";\nimport type { SessionContext } from \"eve/context\";\n\n/** HTTP header that carries the authenticated Factory Task ID into an Eve session. */\nexport const factoryTaskHeader = \"x-factory-task-id\";\n/** Eve authentication attribute that stores the bound Factory Task ID. */\nexport const factoryTaskAttribute = \"factoryTaskId\";\n/** HTTP header that carries the Task attempt fence into an Eve session. */\nexport const factoryTaskAttemptHeader = \"x-factory-task-attempt\";\n/** Eve authentication attribute that stores the bound Task attempt fence. */\nexport const factoryTaskAttemptAttribute = \"factoryTaskAttempt\";\n/** HTTP header that carries the authenticated repository authorization envelope. */\nexport const factoryRepositoryIdsHeader = \"x-factory-repository-ids\";\n/** HTTP header that carries the authenticated conversation reply channel. */\nexport const factoryReplyChannelHeader = \"x-factory-reply-channel\";\n/** HTTP header that carries the authenticated conversation reply address. */\nexport const factoryReplyAddressHeader = \"x-factory-reply-address\";\n/** Eve authentication attribute that stores the authorized repository IDs. */\nexport const factoryRepositoryIdsAttribute = \"factoryRepositoryIds\";\n/** Eve authentication attribute that stores the conversation reply channel. */\nexport const factoryReplyChannelAttribute = \"factoryReplyChannel\";\n/** Eve authentication attribute that stores the conversation reply address. */\nexport const factoryReplyAddressAttribute = \"factoryReplyAddress\";\n\ntype SessionInitiator = SessionContext[\"session\"][\"auth\"][\"initiator\"];\ntype AuthenticatedSessionInitiator = NonNullable<SessionInitiator>;\n\n/** The repository authorization envelope and reply destination bound to a conversation. */\nexport interface FactoryConversationSessionBinding {\n  repositoryIds: readonly RepositoryId[];\n  replyTo: ReplyTo;\n}\n\n/** Test whether authenticated Eve session state declares a Factory Task binding. */\nexport function hasFactoryTaskBinding(auth: SessionInitiator): boolean {\n  return auth?.attributes[factoryTaskAttribute] !== undefined;\n}\n\n/**\n * Encodes a Task ID and attempt fence as headers for a trusted Eve session request.\n *\n * @remarks\n * These headers are a transport envelope, not standalone authorization. The receiving Eve route\n * must authenticate the trusted caller and wrap that authentication with `withFactoryTask`.\n *\n * @param task - Exact Task and attempt claimed by dispatch.\n * @returns Headers consumed by `withFactoryTask` on the target Eve channel.\n *\n * @example\n * ```ts\n * import { taskHeaders } from \"@vercel/factory\";\n * import type { TaskAttemptRef } from \"@vercel/factory/execution\";\n *\n * declare const task: TaskAttemptRef;\n * const headers = taskHeaders(task);\n * ```\n */\nexport function taskHeaders(task: TaskAttemptRef): Record<string, string> {\n  return {\n    [factoryTaskHeader]: task.taskId,\n    [factoryTaskAttemptHeader]: String(task.attempt),\n  };\n}\n\n/** Encode a conversation's repository scope and reply destination as Eve request headers. */\nexport function conversationHeaders(input: {\n  repositoryIds: readonly RepositoryId[];\n  replyTo: ReplyTo;\n}): Record<string, string> {\n  return {\n    [factoryRepositoryIdsHeader]: input.repositoryIds.join(\",\"),\n    [factoryReplyChannelHeader]: input.replyTo.channel,\n    [factoryReplyAddressHeader]: input.replyTo.address,\n  };\n}\n\n/** Add a validated Task ID and attempt fence to an authenticated Eve initiator. */\nexport function taskSessionAuth(\n  auth: AuthenticatedSessionInitiator,\n  task: TaskAttemptRef,\n): AuthenticatedSessionInitiator {\n  return {\n    ...auth,\n    attributes: {\n      ...auth.attributes,\n      [factoryTaskAttribute]: task.taskId,\n      [factoryTaskAttemptAttribute]: String(task.attempt),\n    },\n  };\n}\n\n/**\n * Requires valid Factory Task headers and binds them into an authenticated Eve initiator.\n *\n * @remarks\n * The wrapped authenticator runs first. If it returns no identity, that result is preserved. For\n * an authenticated caller, both Factory headers are mandatory and validated before their Task ID\n * and attempt are copied into session attributes. This records claimed identity; mutating tools\n * call `requireTaskExecution` to recheck it against current durable Task state.\n *\n * Mount this wrapper only on routes reached through a trusted launcher that supplies\n * `taskHeaders`. It does not independently verify that the caller may claim an arbitrary Task.\n *\n * @param authenticate - Existing Eve request authenticator for the trusted launcher.\n * @returns An authenticator that adds the validated Factory Task binding.\n * @throws `ForbiddenError` when either Task header is absent or malformed.\n *\n * @example\n * ```ts\n * import { withFactoryTask } from \"@vercel/factory\";\n * import { localDev } from \"eve/channels/auth\";\n * import { eveChannel } from \"eve/channels/eve\";\n *\n * export default eveChannel({ auth: [withFactoryTask(localDev())] });\n * ```\n */\nexport function withFactoryTask(authenticate: AuthFn<Request>): AuthFn<Request> {\n  return async (request) => {\n    const auth = await authenticate(request);\n    if (auth == null) return auth;\n    const parsedTask = taskIdSchema.safeParse(request.headers.get(factoryTaskHeader));\n    const parsedAttempt = parseTaskAttempt(request.headers.get(factoryTaskAttemptHeader));\n    if (!parsedTask.success || parsedAttempt === null) throw new ForbiddenError();\n    return taskSessionAuth(auth, taskAttemptRef(parsedTask.data, parsedAttempt));\n  };\n}\n\n/** Bind optional Task and conversation headers while rejecting partial or malformed context. */\nexport function withOptionalFactoryTask(authenticate: AuthFn<Request>): AuthFn<Request> {\n  return async (request) => {\n    const auth = await authenticate(request);\n    if (auth == null) return auth;\n    const taskId = request.headers.get(factoryTaskHeader);\n    const taskAttempt = request.headers.get(factoryTaskAttemptHeader);\n    const repositoryIds = request.headers.get(factoryRepositoryIdsHeader);\n    const replyChannel = request.headers.get(factoryReplyChannelHeader);\n    const replyAddress = request.headers.get(factoryReplyAddressHeader);\n    const hasConversationBinding =\n      repositoryIds !== null || replyChannel !== null || replyAddress !== null;\n    if (taskId === null && taskAttempt === null && !hasConversationBinding) return auth;\n    const parsedTask = taskId === null ? null : taskIdSchema.safeParse(taskId);\n    const parsedAttempt = parseTaskAttempt(taskAttempt);\n    const parsedRepositories =\n      repositoryIds === null\n        ? null\n        : repositoryIdSchema.array().min(1).safeParse(repositoryIds.split(\",\").filter(Boolean));\n    const parsedReplyTo =\n      replyChannel === null || replyAddress === null\n        ? null\n        : replyToSchema.safeParse({ channel: replyChannel, address: replyAddress });\n    if (\n      (parsedTask !== null && !parsedTask.success) ||\n      (parsedTask === null) !== (parsedAttempt === null) ||\n      (hasConversationBinding &&\n        (parsedRepositories === null ||\n          !parsedRepositories.success ||\n          parsedReplyTo === null ||\n          !parsedReplyTo.success))\n    ) {\n      throw new ForbiddenError();\n    }\n    const conversationAttributes: Record<string, string> =\n      parsedRepositories?.success === true && parsedReplyTo?.success === true\n        ? {\n            [factoryRepositoryIdsAttribute]: parsedRepositories.data.join(\",\"),\n            [factoryReplyChannelAttribute]: parsedReplyTo.data.channel,\n            [factoryReplyAddressAttribute]: parsedReplyTo.data.address,\n          }\n        : {};\n    return {\n      ...auth,\n      attributes: {\n        ...auth.attributes,\n        ...(parsedTask === null || parsedAttempt === null\n          ? {}\n          : {\n              [factoryTaskAttribute]: parsedTask.data,\n              [factoryTaskAttemptAttribute]: String(parsedAttempt),\n            }),\n        ...conversationAttributes,\n      },\n    };\n  };\n}\n\n/** Read the required Factory Task ID from authenticated Eve session state. */\nexport function requireTaskIdForSession(auth: SessionInitiator): TaskId {\n  return taskIdSchema.parse(auth?.attributes[factoryTaskAttribute]);\n}\n\n/** Read an optional Task ID from authenticated session state, rejecting malformed values. */\nexport function optionalTaskIdForSession(auth: SessionInitiator): TaskId | null {\n  const value = auth?.attributes[factoryTaskAttribute];\n  return value === undefined ? null : taskIdSchema.parse(value);\n}\n\n/** Read the complete, attempt-fenced Task binding established by Factory authentication. */\nexport function taskBindingForSession(auth: SessionInitiator): TaskAttemptRef {\n  const taskId = requireTaskIdForSession(auth);\n  const rawAttempt = auth?.attributes[factoryTaskAttemptAttribute];\n  const attempt = parseTaskAttempt(typeof rawAttempt === \"string\" ? rawAttempt : null);\n  if (attempt === null) throw new Error(\"Factory session Task attempt binding is invalid.\");\n  return { taskId, attempt };\n}\n\n/** Read the repository authorization envelope, or null when the session has none. */\nexport function repositoryIdsForSession(auth: SessionInitiator): readonly RepositoryId[] | null {\n  const value = auth?.attributes[factoryRepositoryIdsAttribute];\n  if (value === undefined) return null;\n  return repositoryIdSchema\n    .array()\n    .min(1)\n    .parse(typeof value === \"string\" ? value.split(\",\").filter(Boolean) : value);\n}\n\n/** Read the authenticated reply destination, or null when the session has none. */\nexport function replyToForSession(auth: SessionInitiator): ReplyTo | null {\n  const channel = auth?.attributes[factoryReplyChannelAttribute];\n  const address = auth?.attributes[factoryReplyAddressAttribute];\n  if (channel === undefined && address === undefined) return null;\n  return replyToSchema.parse({ channel, address });\n}\n\n/** Read the complete conversation binding, rejecting partial authentication state. */\nexport function conversationBindingForSession(\n  auth: SessionInitiator,\n): FactoryConversationSessionBinding | null {\n  const repositoryIds = repositoryIdsForSession(auth);\n  const replyTo = replyToForSession(auth);\n  if (repositoryIds === null && replyTo === null) return null;\n  if (repositoryIds === null || replyTo === null) {\n    throw new Error(\"Factory session conversation binding is incomplete.\");\n  }\n  return { repositoryIds, replyTo };\n}\n\n/** Authenticated conversation authority assembled from both initiator and current session state. */\nexport interface ConversationBinding {\n  replyTo: ReplyTo;\n  /**\n   * Repository envelopes the binding carries: the initiator's, plus the current\n   * auth's when it restates one. Admitted work must sit inside every envelope.\n   */\n  repositoryEnvelopes: readonly (readonly RepositoryId[])[];\n  parentTask?: TaskAttemptRef;\n}\n\nconst conversationBindingAttributes = [\n  factoryReplyChannelAttribute,\n  factoryReplyAddressAttribute,\n  factoryTaskAttribute,\n  factoryTaskAttemptAttribute,\n] as const;\n\n/**\n * Read and validate the conversation binding carried on a session's auth pair.\n * The initiator's attributes are authoritative; any binding attribute the\n * current auth restates must agree with them. This is the only reader of the\n * binding attribute encoding; callers never touch `attributes` themselves.\n *\n * Distinct from `conversationBindingForSession`, which reads the initiator\n * alone: admission needs every envelope the pair carries, so that work cannot\n * be admitted into a repository only one side of the pair authorizes.\n */\nexport function conversationBinding(auth: {\n  initiator: AuthenticatedSessionInitiator;\n  current: AuthenticatedSessionInitiator;\n}): ConversationBinding {\n  const attributes = auth.initiator.attributes;\n  const replyTo = replyToSchema.parse({\n    channel: attributes[factoryReplyChannelAttribute],\n    address: attributes[factoryReplyAddressAttribute],\n  });\n  for (const key of conversationBindingAttributes) {\n    if (\n      auth.current.attributes[key] !== undefined &&\n      auth.current.attributes[key] !== attributes[key]\n    )\n      throw new Error(\"Conversation binding does not match the authenticated conversation\");\n  }\n  const repositoryEnvelopes: (readonly RepositoryId[])[] = [];\n  for (const [index, entry] of [auth.initiator, auth.current].entries()) {\n    const raw = entry.attributes[factoryRepositoryIdsAttribute];\n    if (index === 1 && raw === undefined) continue;\n    repositoryEnvelopes.push(\n      repositoryIdSchema\n        .array()\n        .min(1)\n        .parse(typeof raw === \"string\" ? raw.split(\",\") : raw),\n    );\n  }\n  let parentTask: ConversationBinding[\"parentTask\"];\n  if (\n    attributes[factoryTaskAttribute] !== undefined ||\n    attributes[factoryTaskAttemptAttribute] !== undefined\n  ) {\n    const taskId = taskIdSchema.parse(attributes[factoryTaskAttribute]);\n    const rawAttempt = attributes[factoryTaskAttemptAttribute];\n    const attempt = typeof rawAttempt === \"string\" ? parseTaskAttempt(rawAttempt) : null;\n    if (attempt === null) throw new Error(\"Conversation binding carries an invalid parent attempt\");\n    parentTask = taskAttemptRef(taskId, attempt);\n  }\n  return { replyTo, repositoryEnvelopes, parentTask };\n}\n\nfunction parseTaskAttempt(value: string | null): number | null {\n  if (value === null || !/^[1-9]\\d*$/u.test(value)) return null;\n  const attempt = Number(value);\n  return Number.isSafeInteger(attempt) ? attempt : null;\n}\n"],"mappings":";;;;;;AAQA,MAAa,oBAAoB;;AAEjC,MAAa,uBAAuB;;AAEpC,MAAa,2BAA2B;;AAExC,MAAa,8BAA8B;;AAE3C,MAAa,6BAA6B;;AAE1C,MAAa,4BAA4B;;AAEzC,MAAa,4BAA4B;;AAEzC,MAAa,gCAAgC;;AAE7C,MAAa,+BAA+B;;AAE5C,MAAa,+BAA+B;;AAY5C,SAAgB,sBAAsB,MAAiC;CACrE,OAAO,MAAM,WAAW,0BAA0B,KAAA;AACpD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,YAAY,MAA8C;CACxE,OAAO;GACJ,oBAAoB,KAAK;GACzB,2BAA2B,OAAO,KAAK,OAAO;CACjD;AACF;;AAGA,SAAgB,oBAAoB,OAGT;CACzB,OAAO;GACJ,6BAA6B,MAAM,cAAc,KAAK,GAAG;GACzD,4BAA4B,MAAM,QAAQ;GAC1C,4BAA4B,MAAM,QAAQ;CAC7C;AACF;;AAGA,SAAgB,gBACd,MACA,MAC+B;CAC/B,OAAO;EACL,GAAG;EACH,YAAY;GACV,GAAG,KAAK;IACP,uBAAuB,KAAK;IAC5B,8BAA8B,OAAO,KAAK,OAAO;EACpD;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,gBAAgB,cAAgD;CAC9E,OAAO,OAAO,YAAY;EACxB,MAAM,OAAO,MAAM,aAAa,OAAO;EACvC,IAAI,QAAQ,MAAM,OAAO;EACzB,MAAM,aAAa,aAAa,UAAU,QAAQ,QAAQ,IAAI,iBAAiB,CAAC;EAChF,MAAM,gBAAgB,iBAAiB,QAAQ,QAAQ,IAAI,wBAAwB,CAAC;EACpF,IAAI,CAAC,WAAW,WAAW,kBAAkB,MAAM,MAAM,IAAI,eAAe;EAC5E,OAAO,gBAAgB,MAAM,eAAe,WAAW,MAAM,aAAa,CAAC;CAC7E;AACF;;AAGA,SAAgB,wBAAwB,cAAgD;CACtF,OAAO,OAAO,YAAY;EACxB,MAAM,OAAO,MAAM,aAAa,OAAO;EACvC,IAAI,QAAQ,MAAM,OAAO;EACzB,MAAM,SAAS,QAAQ,QAAQ,IAAI,iBAAiB;EACpD,MAAM,cAAc,QAAQ,QAAQ,IAAI,wBAAwB;EAChE,MAAM,gBAAgB,QAAQ,QAAQ,IAAI,0BAA0B;EACpE,MAAM,eAAe,QAAQ,QAAQ,IAAI,yBAAyB;EAClE,MAAM,eAAe,QAAQ,QAAQ,IAAI,yBAAyB;EAClE,MAAM,yBACJ,kBAAkB,QAAQ,iBAAiB,QAAQ,iBAAiB;EACtE,IAAI,WAAW,QAAQ,gBAAgB,QAAQ,CAAC,wBAAwB,OAAO;EAC/E,MAAM,aAAa,WAAW,OAAO,OAAO,aAAa,UAAU,MAAM;EACzE,MAAM,gBAAgB,iBAAiB,WAAW;EAClD,MAAM,qBACJ,kBAAkB,OACd,OACA,mBAAmB,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,cAAc,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,CAAC;EAC1F,MAAM,gBACJ,iBAAiB,QAAQ,iBAAiB,OACtC,OACA,cAAc,UAAU;GAAE,SAAS;GAAc,SAAS;EAAa,CAAC;EAC9E,IACG,eAAe,QAAQ,CAAC,WAAW,WACnC,eAAe,UAAW,kBAAkB,SAC5C,2BACE,uBAAuB,QACtB,CAAC,mBAAmB,WACpB,kBAAkB,QAClB,CAAC,cAAc,UAEnB,MAAM,IAAI,eAAe;EAE3B,MAAM,yBACJ,oBAAoB,YAAY,QAAQ,eAAe,YAAY,OAC/D;IACG,gCAAgC,mBAAmB,KAAK,KAAK,GAAG;IAChE,+BAA+B,cAAc,KAAK;IAClD,+BAA+B,cAAc,KAAK;EACrD,IACA,CAAC;EACP,OAAO;GACL,GAAG;GACH,YAAY;IACV,GAAG,KAAK;IACR,GAAI,eAAe,QAAQ,kBAAkB,OACzC,CAAC,IACD;MACG,uBAAuB,WAAW;MAClC,8BAA8B,OAAO,aAAa;IACrD;IACJ,GAAG;GACL;EACF;CACF;AACF;;AAGA,SAAgB,wBAAwB,MAAgC;CACtE,OAAO,aAAa,MAAM,MAAM,WAAW,qBAAqB;AAClE;;AAGA,SAAgB,yBAAyB,MAAuC;CAC9E,MAAM,QAAQ,MAAM,WAAW;CAC/B,OAAO,UAAU,KAAA,IAAY,OAAO,aAAa,MAAM,KAAK;AAC9D;;AAGA,SAAgB,sBAAsB,MAAwC;CAC5E,MAAM,SAAS,wBAAwB,IAAI;CAC3C,MAAM,aAAa,MAAM,WAAW;CACpC,MAAM,UAAU,iBAAiB,OAAO,eAAe,WAAW,aAAa,IAAI;CACnF,IAAI,YAAY,MAAM,MAAM,IAAI,MAAM,kDAAkD;CACxF,OAAO;EAAE;EAAQ;CAAQ;AAC3B;;AAGA,SAAgB,wBAAwB,MAAwD;CAC9F,MAAM,QAAQ,MAAM,WAAW;CAC/B,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,OAAO,mBACJ,MAAM,CAAC,CACP,IAAI,CAAC,CAAC,CACN,MAAM,OAAO,UAAU,WAAW,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,IAAI,KAAK;AAC/E;;AAGA,SAAgB,kBAAkB,MAAwC;CACxE,MAAM,UAAU,MAAM,WAAW;CACjC,MAAM,UAAU,MAAM,WAAW;CACjC,IAAI,YAAY,KAAA,KAAa,YAAY,KAAA,GAAW,OAAO;CAC3D,OAAO,cAAc,MAAM;EAAE;EAAS;CAAQ,CAAC;AACjD;;AAGA,SAAgB,8BACd,MAC0C;CAC1C,MAAM,gBAAgB,wBAAwB,IAAI;CAClD,MAAM,UAAU,kBAAkB,IAAI;CACtC,IAAI,kBAAkB,QAAQ,YAAY,MAAM,OAAO;CACvD,IAAI,kBAAkB,QAAQ,YAAY,MACxC,MAAM,IAAI,MAAM,qDAAqD;CAEvE,OAAO;EAAE;EAAe;CAAQ;AAClC;AAaA,MAAM,gCAAgC;CACpC;CACA;CACA;CACA;AACF;;;;;;;;;;;AAYA,SAAgB,oBAAoB,MAGZ;CACtB,MAAM,aAAa,KAAK,UAAU;CAClC,MAAM,UAAU,cAAc,MAAM;EAClC,SAAS,WAAW;EACpB,SAAS,WAAW;CACtB,CAAC;CACD,KAAK,MAAM,OAAO,+BAChB,IACE,KAAK,QAAQ,WAAW,SAAS,KAAA,KACjC,KAAK,QAAQ,WAAW,SAAS,WAAW,MAE5C,MAAM,IAAI,MAAM,oEAAoE;CAExF,MAAM,sBAAmD,CAAC;CAC1D,KAAK,MAAM,CAAC,OAAO,UAAU,CAAC,KAAK,WAAW,KAAK,OAAO,CAAC,CAAC,QAAQ,GAAG;EACrE,MAAM,MAAM,MAAM,WAAW;EAC7B,IAAI,UAAU,KAAK,QAAQ,KAAA,GAAW;EACtC,oBAAoB,KAClB,mBACG,MAAM,CAAC,CACP,IAAI,CAAC,CAAC,CACN,MAAM,OAAO,QAAQ,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG,CACzD;CACF;CACA,IAAI;CACJ,IACE,WAAA,qBAAqC,KAAA,KACrC,WAAA,0BAA4C,KAAA,GAC5C;EACA,MAAM,SAAS,aAAa,MAAM,WAAW,qBAAqB;EAClE,MAAM,aAAa,WAAW;EAC9B,MAAM,UAAU,OAAO,eAAe,WAAW,iBAAiB,UAAU,IAAI;EAChF,IAAI,YAAY,MAAM,MAAM,IAAI,MAAM,wDAAwD;EAC9F,aAAa,eAAe,QAAQ,OAAO;CAC7C;CACA,OAAO;EAAE;EAAS;EAAqB;CAAW;AACpD;AAEA,SAAS,iBAAiB,OAAqC;CAC7D,IAAI,UAAU,QAAQ,CAAC,cAAc,KAAK,KAAK,GAAG,OAAO;CACzD,MAAM,UAAU,OAAO,KAAK;CAC5B,OAAO,OAAO,cAAc,OAAO,IAAI,UAAU;AACnD"}

package/dist/eve/transcript.mjs

@@ -39,6 +39,7 @@ function createEveTranscriptMaterializer(options) {
 		});
 		const origin = typeof options.origin === "string" ? options.origin : options.origin();
 		const response = await fetchImplementation(`${origin.replace(/\/+$/u, "")}/eve/agents/${encodeURIComponent(input.agent)}/eve/v1/session/${encodeURIComponent(input.execution.sessionId)}/stream?${query}`, {
+			cache: "no-store",
 			headers: await options.headers?.(scopeFor(input)),
 			signal: AbortSignal.timeout(timeoutMs),
 			redirect: "error"
@@ -53,7 +54,10 @@ function createEveTranscriptMaterializer(options) {
 			await response.body.cancel();
 			throw new Error("Eve transcript materialization did not include a valid durable cursor");
 		}
-		if (transcript.cursor <= tail) for await (const event of readEvents(response.body)) transcript.accept(event);
+		if (transcript.cursor <= tail) for await (const event of readEvents(response.body)) {
+			transcript.accept(event);
+			if (transcript.cursor === tail + 1) break;
+		}
 		else await response.body.cancel();
 		if (transcript.cursor !== tail + 1) throw new Error("Eve transcript materialization closed before its durable cursor");
 		await options.stores.transcripts.put(input.execution, transcript.snapshot());

package/dist/eve/transcript.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.mjs","names":[],"sources":["../../src/eve/transcript.ts"],"sourcesContent":["import { readEvents } from \"../client-events\";\nimport { Transcript } from \"../client-transcript\";\nimport { replyToSchema, type MaybePromise, type ReplyTo } from \"../schema/common\";\nimport { taskAttemptRef, type TaskAttemptRef } from \"../schema/execution\";\nimport { repositoryIdSchema, taskIdSchema, type RepositoryId } from \"../schema/id\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  factoryReplyAddressAttribute,\n  factoryReplyChannelAttribute,\n  factoryRepositoryIdsAttribute,\n  factoryTaskAttemptAttribute,\n  factoryTaskAttribute,\n} from \"./task-session\";\n\n/** Identifies the Eve execution and authenticated attributes to project into a transcript. */\nexport interface TranscriptMaterializationInput {\n  agent: string;\n  execution: { provider: \"eve\"; sessionId: string };\n  attributes: Readonly<Record<string, string | readonly string[]>>;\n}\n\n/** The Task and conversation authorization context forwarded when reading an Eve transcript. */\nexport interface EveTranscriptRequestScope {\n  task?: TaskAttemptRef;\n  conversation?: { repositoryIds: readonly RepositoryId[]; replyTo: ReplyTo };\n}\n\n/** Configures durable transcript storage and authenticated access to Eve session events. */\nexport interface EveTranscriptMaterializerOptions {\n  stores: Pick<FactoryStores, \"transcripts\">;\n  origin: string | (() => string);\n  headers?(scope: EveTranscriptRequestScope): MaybePromise<HeadersInit>;\n  fetch?: typeof globalThis.fetch;\n  timeoutMs?: number;\n}\n\n/** Materializes one Eve execution stream into Factory's browser-safe transcript store. */\nexport type EveTranscriptMaterializer = (input: TranscriptMaterializationInput) => Promise<void>;\n\nfunction attribute(\n  attributes: TranscriptMaterializationInput[\"attributes\"],\n  name: string,\n): string | undefined {\n  const value = attributes[name];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction scopeFor(input: TranscriptMaterializationInput): EveTranscriptRequestScope {\n  const taskId = taskIdSchema.safeParse(attribute(input.attributes, factoryTaskAttribute));\n  const attempt = Number(attribute(input.attributes, factoryTaskAttemptAttribute));\n  const repositories = repositoryIdSchema\n    .array()\n    .min(1)\n    .safeParse(\n      attribute(input.attributes, factoryRepositoryIdsAttribute)?.split(\",\").filter(Boolean),\n    );\n  const replyTo = replyToSchema.safeParse({\n    channel: attribute(input.attributes, factoryReplyChannelAttribute),\n    address: attribute(input.attributes, factoryReplyAddressAttribute),\n  });\n  return {\n    ...(taskId.success && Number.isSafeInteger(attempt) && attempt > 0\n      ? { task: taskAttemptRef(taskId.data, attempt) }\n      : {}),\n    ...(repositories.success && replyTo.success\n      ? { conversation: { repositoryIds: repositories.data, replyTo: replyTo.data } }\n      : {}),\n  };\n}\n\n/** Materialize a browser-safe transcript projection from one durable Eve session stream. */\nexport function createEveTranscriptMaterializer(\n  options: EveTranscriptMaterializerOptions,\n): EveTranscriptMaterializer {\n  const fetchImplementation = options.fetch ?? globalThis.fetch;\n  const timeoutMs = options.timeoutMs ?? 30_000;\n  return async (input: TranscriptMaterializationInput): Promise<void> => {\n    const previous = await options.stores.transcripts.get(input.execution);\n    const transcript = new Transcript();\n    if (previous !== null) transcript.hydrate(previous);\n    const query = new URLSearchParams({\n      startIndex: String(transcript.cursor),\n      includeTailIndex: \"1\",\n    });\n    const origin = typeof options.origin === \"string\" ? options.origin : options.origin();\n    const response = await fetchImplementation(\n      `${origin.replace(/\\/+$/u, \"\")}/eve/agents/${encodeURIComponent(input.agent)}/eve/v1/session/${encodeURIComponent(input.execution.sessionId)}/stream?${query}`,\n      {\n        headers: await options.headers?.(scopeFor(input)),\n        signal: AbortSignal.timeout(timeoutMs),\n        redirect: \"error\",\n      },\n    );\n    if (!response.ok || !response.body) {\n      await response.body?.cancel();\n      throw new Error(`Eve refused transcript materialization: ${response.status}`);\n    }\n    const tailValue = response.headers.get(\"x-eve-stream-tail-index\");\n    const tail = tailValue === null ? Number.NaN : Number(tailValue);\n    if (!Number.isSafeInteger(tail) || tail < -1) {\n      await response.body.cancel();\n      throw new Error(\"Eve transcript materialization did not include a valid durable cursor\");\n    }\n    if (transcript.cursor <= tail) {\n      for await (const event of readEvents(response.body)) transcript.accept(event);\n    } else {\n      await response.body.cancel();\n    }\n    if (transcript.cursor !== tail + 1) {\n      throw new Error(\"Eve transcript materialization closed before its durable cursor\");\n    }\n    await options.stores.transcripts.put(input.execution, transcript.snapshot());\n  };\n}\n"],"mappings":";;;;;;;AAuCA,SAAS,UACP,YACA,MACoB;CACpB,MAAM,QAAQ,WAAW;CACzB,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAA;AAC7C;AAEA,SAAS,SAAS,OAAkE;CAClF,MAAM,SAAS,aAAa,UAAU,UAAU,MAAM,YAAY,oBAAoB,CAAC;CACvF,MAAM,UAAU,OAAO,UAAU,MAAM,YAAY,2BAA2B,CAAC;CAC/E,MAAM,eAAe,mBAClB,MAAM,CAAC,CACP,IAAI,CAAC,CAAC,CACN,UACC,UAAU,MAAM,YAAY,6BAA6B,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,CACvF;CACF,MAAM,UAAU,cAAc,UAAU;EACtC,SAAS,UAAU,MAAM,YAAY,4BAA4B;EACjE,SAAS,UAAU,MAAM,YAAY,4BAA4B;CACnE,CAAC;CACD,OAAO;EACL,GAAI,OAAO,WAAW,OAAO,cAAc,OAAO,KAAK,UAAU,IAC7D,EAAE,MAAM,eAAe,OAAO,MAAM,OAAO,EAAE,IAC7C,CAAC;EACL,GAAI,aAAa,WAAW,QAAQ,UAChC,EAAE,cAAc;GAAE,eAAe,aAAa;GAAM,SAAS,QAAQ;EAAK,EAAE,IAC5E,CAAC;CACP;AACF;;AAGA,SAAgB,gCACd,SAC2B;CAC3B,MAAM,sBAAsB,QAAQ,SAAS,WAAW;CACxD,MAAM,YAAY,QAAQ,aAAa;CACvC,OAAO,OAAO,UAAyD;EACrE,MAAM,WAAW,MAAM,QAAQ,OAAO,YAAY,IAAI,MAAM,SAAS;EACrE,MAAM,aAAa,IAAI,WAAW;EAClC,IAAI,aAAa,MAAM,WAAW,QAAQ,QAAQ;EAClD,MAAM,QAAQ,IAAI,gBAAgB;GAChC,YAAY,OAAO,WAAW,MAAM;GACpC,kBAAkB;EACpB,CAAC;EACD,MAAM,SAAS,OAAO,QAAQ,WAAW,WAAW,QAAQ,SAAS,QAAQ,OAAO;EACpF,MAAM,WAAW,MAAM,oBACrB,GAAG,OAAO,QAAQ,SAAS,EAAE,EAAE,cAAc,mBAAmB,MAAM,KAAK,EAAE,kBAAkB,mBAAmB,MAAM,UAAU,SAAS,EAAE,UAAU,SACvJ;GACE,SAAS,MAAM,QAAQ,UAAU,SAAS,KAAK,CAAC;GAChD,QAAQ,YAAY,QAAQ,SAAS;GACrC,UAAU;EACZ,CACF;EACA,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,MAAM;GAClC,MAAM,SAAS,MAAM,OAAO;GAC5B,MAAM,IAAI,MAAM,2CAA2C,SAAS,QAAQ;EAC9E;EACA,MAAM,YAAY,SAAS,QAAQ,IAAI,yBAAyB;EAChE,MAAM,OAAO,cAAc,OAAO,MAAa,OAAO,SAAS;EAC/D,IAAI,CAAC,OAAO,cAAc,IAAI,KAAK,OAAO,IAAI;GAC5C,MAAM,SAAS,KAAK,OAAO;GAC3B,MAAM,IAAI,MAAM,uEAAuE;EACzF;EACA,IAAI,WAAW,UAAU,MACvB,WAAW,MAAM,SAAS,WAAW,SAAS,IAAI,GAAG,WAAW,OAAO,KAAK;OAE5E,MAAM,SAAS,KAAK,OAAO;EAE7B,IAAI,WAAW,WAAW,OAAO,GAC/B,MAAM,IAAI,MAAM,iEAAiE;EAEnF,MAAM,QAAQ,OAAO,YAAY,IAAI,MAAM,WAAW,WAAW,SAAS,CAAC;CAC7E;AACF"}
+{"version":3,"file":"transcript.mjs","names":[],"sources":["../../src/eve/transcript.ts"],"sourcesContent":["import { readEvents } from \"../client-events\";\nimport { Transcript } from \"../client-transcript\";\nimport { replyToSchema, type MaybePromise, type ReplyTo } from \"../schema/common\";\nimport { taskAttemptRef, type TaskAttemptRef } from \"../schema/execution\";\nimport { repositoryIdSchema, taskIdSchema, type RepositoryId } from \"../schema/id\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  factoryReplyAddressAttribute,\n  factoryReplyChannelAttribute,\n  factoryRepositoryIdsAttribute,\n  factoryTaskAttemptAttribute,\n  factoryTaskAttribute,\n} from \"./task-session\";\n\n/** Identifies the Eve execution and authenticated attributes to project into a transcript. */\nexport interface TranscriptMaterializationInput {\n  agent: string;\n  execution: { provider: \"eve\"; sessionId: string };\n  attributes: Readonly<Record<string, string | readonly string[]>>;\n}\n\n/** The Task and conversation authorization context forwarded when reading an Eve transcript. */\nexport interface EveTranscriptRequestScope {\n  task?: TaskAttemptRef;\n  conversation?: { repositoryIds: readonly RepositoryId[]; replyTo: ReplyTo };\n}\n\n/** Configures durable transcript storage and authenticated access to Eve session events. */\nexport interface EveTranscriptMaterializerOptions {\n  stores: Pick<FactoryStores, \"transcripts\">;\n  origin: string | (() => string);\n  headers?(scope: EveTranscriptRequestScope): MaybePromise<HeadersInit>;\n  fetch?: typeof globalThis.fetch;\n  timeoutMs?: number;\n}\n\n/** Materializes one Eve execution stream into Factory's browser-safe transcript store. */\nexport type EveTranscriptMaterializer = (input: TranscriptMaterializationInput) => Promise<void>;\n\nfunction attribute(\n  attributes: TranscriptMaterializationInput[\"attributes\"],\n  name: string,\n): string | undefined {\n  const value = attributes[name];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction scopeFor(input: TranscriptMaterializationInput): EveTranscriptRequestScope {\n  const taskId = taskIdSchema.safeParse(attribute(input.attributes, factoryTaskAttribute));\n  const attempt = Number(attribute(input.attributes, factoryTaskAttemptAttribute));\n  const repositories = repositoryIdSchema\n    .array()\n    .min(1)\n    .safeParse(\n      attribute(input.attributes, factoryRepositoryIdsAttribute)?.split(\",\").filter(Boolean),\n    );\n  const replyTo = replyToSchema.safeParse({\n    channel: attribute(input.attributes, factoryReplyChannelAttribute),\n    address: attribute(input.attributes, factoryReplyAddressAttribute),\n  });\n  return {\n    ...(taskId.success && Number.isSafeInteger(attempt) && attempt > 0\n      ? { task: taskAttemptRef(taskId.data, attempt) }\n      : {}),\n    ...(repositories.success && replyTo.success\n      ? { conversation: { repositoryIds: repositories.data, replyTo: replyTo.data } }\n      : {}),\n  };\n}\n\n/** Materialize a browser-safe transcript projection from one durable Eve session stream. */\nexport function createEveTranscriptMaterializer(\n  options: EveTranscriptMaterializerOptions,\n): EveTranscriptMaterializer {\n  const fetchImplementation = options.fetch ?? globalThis.fetch;\n  const timeoutMs = options.timeoutMs ?? 30_000;\n  return async (input: TranscriptMaterializationInput): Promise<void> => {\n    const previous = await options.stores.transcripts.get(input.execution);\n    const transcript = new Transcript();\n    if (previous !== null) transcript.hydrate(previous);\n    const query = new URLSearchParams({\n      startIndex: String(transcript.cursor),\n      includeTailIndex: \"1\",\n    });\n    const origin = typeof options.origin === \"string\" ? options.origin : options.origin();\n    const response = await fetchImplementation(\n      `${origin.replace(/\\/+$/u, \"\")}/eve/agents/${encodeURIComponent(input.agent)}/eve/v1/session/${encodeURIComponent(input.execution.sessionId)}/stream?${query}`,\n      {\n        cache: \"no-store\",\n        headers: await options.headers?.(scopeFor(input)),\n        signal: AbortSignal.timeout(timeoutMs),\n        redirect: \"error\",\n      },\n    );\n    if (!response.ok || !response.body) {\n      await response.body?.cancel();\n      throw new Error(`Eve refused transcript materialization: ${response.status}`);\n    }\n    const tailValue = response.headers.get(\"x-eve-stream-tail-index\");\n    const tail = tailValue === null ? Number.NaN : Number(tailValue);\n    if (!Number.isSafeInteger(tail) || tail < -1) {\n      await response.body.cancel();\n      throw new Error(\"Eve transcript materialization did not include a valid durable cursor\");\n    }\n    if (transcript.cursor <= tail) {\n      for await (const event of readEvents(response.body)) {\n        transcript.accept(event);\n        if (transcript.cursor === tail + 1) break;\n      }\n    } else {\n      await response.body.cancel();\n    }\n    if (transcript.cursor !== tail + 1) {\n      throw new Error(\"Eve transcript materialization closed before its durable cursor\");\n    }\n    await options.stores.transcripts.put(input.execution, transcript.snapshot());\n  };\n}\n"],"mappings":";;;;;;;AAuCA,SAAS,UACP,YACA,MACoB;CACpB,MAAM,QAAQ,WAAW;CACzB,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAA;AAC7C;AAEA,SAAS,SAAS,OAAkE;CAClF,MAAM,SAAS,aAAa,UAAU,UAAU,MAAM,YAAY,oBAAoB,CAAC;CACvF,MAAM,UAAU,OAAO,UAAU,MAAM,YAAY,2BAA2B,CAAC;CAC/E,MAAM,eAAe,mBAClB,MAAM,CAAC,CACP,IAAI,CAAC,CAAC,CACN,UACC,UAAU,MAAM,YAAY,6BAA6B,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,CACvF;CACF,MAAM,UAAU,cAAc,UAAU;EACtC,SAAS,UAAU,MAAM,YAAY,4BAA4B;EACjE,SAAS,UAAU,MAAM,YAAY,4BAA4B;CACnE,CAAC;CACD,OAAO;EACL,GAAI,OAAO,WAAW,OAAO,cAAc,OAAO,KAAK,UAAU,IAC7D,EAAE,MAAM,eAAe,OAAO,MAAM,OAAO,EAAE,IAC7C,CAAC;EACL,GAAI,aAAa,WAAW,QAAQ,UAChC,EAAE,cAAc;GAAE,eAAe,aAAa;GAAM,SAAS,QAAQ;EAAK,EAAE,IAC5E,CAAC;CACP;AACF;;AAGA,SAAgB,gCACd,SAC2B;CAC3B,MAAM,sBAAsB,QAAQ,SAAS,WAAW;CACxD,MAAM,YAAY,QAAQ,aAAa;CACvC,OAAO,OAAO,UAAyD;EACrE,MAAM,WAAW,MAAM,QAAQ,OAAO,YAAY,IAAI,MAAM,SAAS;EACrE,MAAM,aAAa,IAAI,WAAW;EAClC,IAAI,aAAa,MAAM,WAAW,QAAQ,QAAQ;EAClD,MAAM,QAAQ,IAAI,gBAAgB;GAChC,YAAY,OAAO,WAAW,MAAM;GACpC,kBAAkB;EACpB,CAAC;EACD,MAAM,SAAS,OAAO,QAAQ,WAAW,WAAW,QAAQ,SAAS,QAAQ,OAAO;EACpF,MAAM,WAAW,MAAM,oBACrB,GAAG,OAAO,QAAQ,SAAS,EAAE,EAAE,cAAc,mBAAmB,MAAM,KAAK,EAAE,kBAAkB,mBAAmB,MAAM,UAAU,SAAS,EAAE,UAAU,SACvJ;GACE,OAAO;GACP,SAAS,MAAM,QAAQ,UAAU,SAAS,KAAK,CAAC;GAChD,QAAQ,YAAY,QAAQ,SAAS;GACrC,UAAU;EACZ,CACF;EACA,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,MAAM;GAClC,MAAM,SAAS,MAAM,OAAO;GAC5B,MAAM,IAAI,MAAM,2CAA2C,SAAS,QAAQ;EAC9E;EACA,MAAM,YAAY,SAAS,QAAQ,IAAI,yBAAyB;EAChE,MAAM,OAAO,cAAc,OAAO,MAAa,OAAO,SAAS;EAC/D,IAAI,CAAC,OAAO,cAAc,IAAI,KAAK,OAAO,IAAI;GAC5C,MAAM,SAAS,KAAK,OAAO;GAC3B,MAAM,IAAI,MAAM,uEAAuE;EACzF;EACA,IAAI,WAAW,UAAU,MACvB,WAAW,MAAM,SAAS,WAAW,SAAS,IAAI,GAAG;GACnD,WAAW,OAAO,KAAK;GACvB,IAAI,WAAW,WAAW,OAAO,GAAG;EACtC;OAEA,MAAM,SAAS,KAAK,OAAO;EAE7B,IAAI,WAAW,WAAW,OAAO,GAC/B,MAAM,IAAI,MAAM,iEAAiE;EAEnF,MAAM,QAAQ,OAAO,YAAY,IAAI,MAAM,WAAW,WAAW,SAAS,CAAC;CAC7E;AACF"}

package/dist/execution.d.mts

@@ -4,28 +4,56 @@ import { FactoryStores } from "./store/engine.mjs";
 //#region src/execution.d.ts
 /** Validated request and stable idempotency key passed to an execution provider. */
 interface StartExecutionInput {
+  /** Exact Task-attempt request validated before the provider is called. */
   readonly request: CodingExecutionRequest;
+  /** Stable key that must identify the same provider launch across retries and process restarts. */
   readonly launchKey: ExecutionLaunchKey;
 }
 /** Current provider state when inspecting one recorded execution. */
 type ExecutionInspectionResult = {
+  /** The recorded execution still exists and is safe for the workflow to reattach. */
   status: "active";
 } | {
+  /** The provider can no longer inspect or reattach the recorded execution. */
   status: "expired";
 } | {
+  /** The provider has immutable final evidence for the recorded execution. */
   status: "finished";
   result: ExecutionResult;
 };
 /** Provider-neutral boundary for retry-safe execution start, inspection, and cancellation. */
 interface ExecutionAdapter {
-  /** Retry-safe by key. Throw ExecutionLaunchPendingError only for ambiguous acceptance; other errors mean no launch. */
+  /**
+   * Starts or recovers one launch by its stable key. Return only after provider acceptance is
+   * known. Throw `ExecutionLaunchPendingError` when acceptance is ambiguous; every other rejection
+   * promises that this call did not leave an untracked launch.
+   *
+   * @param input - Validated provider request and stable launch key.
+   * @returns The accepted execution reference for this logical launch.
+   */
   start(input: StartExecutionInput): Promise<ExecutionReference>;
-  /** Only active confirms that reattachment is safe. Missing/expired execution must never start implicitly. */
+  /**
+   * Observes one exact provider handle without starting replacement work. Only `active` confirms
+   * that reattachment is safe; `expired` and `finished` require workflow-owned reconciliation.
+   *
+   * @param execution - Exact provider handle previously recorded on the Task.
+   * @returns Current provider state and final result when finished.
+   */
   inspect(execution: ExecutionReference): Promise<ExecutionInspectionResult>;
-  /** Idempotent stop, returning final observed usage. May report cancellation even if interruption is unsupported. */
+  /**
+   * Idempotently requests a stop and returns the provider's final observed result and usage. An
+   * adapter may report cancellation even when immediate interruption is unsupported; callers that
+   * require proof of inactivity must use provider-specific confirmation.
+   *
+   * @param execution - Exact provider handle to stop or confirm inactive.
+   * @returns Immutable final result and usage for that execution.
+   */
   stop(execution: ExecutionReference): Promise<ExecutionResult>;
 }
-/** Error raised when an execution no longer matches the current running Task attempt. */
+/**
+ * Error raised when an execution no longer matches the current running Task attempt.
+ * Reread the Task and discard the stale observation; do not apply it to the replacement attempt.
+ */
 declare class ExecutionFenceError extends Error {}
 /** Store capabilities required to launch or reattach a coding execution. */
 type LaunchExecutionStores = Pick<FactoryStores, "repositories" | "tasks">;
@@ -35,40 +63,120 @@ type InspectExecutionStores = Pick<FactoryStores, "tasks">;
 type RecordExecutionUsageStores = Pick<FactoryStores, "receipts" | "tasks">;
 /** Store capabilities required to cancel and settle a coding execution. */
 type CancelExecutionStores = RecordExecutionUsageStores;
-/** Construct the stable provider idempotency key for one exact Task attempt. */
+/**
+ * Constructs the stable provider idempotency key for one exact Task attempt.
+ * Persist or deterministically recreate this key across launch recovery; a new attempt gets a new key.
+ */
 declare function executionLaunchKey(ref: TaskAttemptRef): ExecutionLaunchKey;
 /** Dependencies and request used to start or reattach one coding execution. */
 interface LaunchExecutionOptions {
+  /** Task and repository reads plus the durable execution-binding write. */
   readonly stores: LaunchExecutionStores;
+  /** Exact running Task attempt and single repository supplied to the provider. */
   readonly request: CodingExecutionRequest;
+  /** Provider boundary responsible for idempotent start and exact-handle inspection. */
   readonly adapter: ExecutionAdapter;
 }
-/** Called inside a durable workflow step after dispatch gates. No provider lifecycle is stored here. */
+/**
+ * Starts or reattaches one coding execution after dispatch has admitted its Task.
+ *
+ * @remarks
+ * The Task must still be `running` on the requested attempt and name exactly one enabled matching
+ * repository. If an execution is already recorded, this method inspects it and returns it only
+ * when the provider confirms it is active; it never starts an implicit replacement for a finished
+ * or expired handle.
+ *
+ * For a new launch, the adapter receives a stable key derived from the Task attempt. The method
+ * returns only after the provider reference is durably bound to that attempt. If acceptance or
+ * the binding write is ambiguous, it throws `ExecutionLaunchPendingError`; retry this operation
+ * with the same request so the same key can recover the launch. Reread the Task before applying
+ * any other error, because a concurrent writer may have replaced the attempt.
+ *
+ * @param options - Validated request, required stores, and provider adapter.
+ * @returns The recorded provider execution for the current running attempt.
+ * @throws `ExecutionFenceError` when Task attempt or execution ownership changes.
+ * @throws `ExecutionLaunchPendingError` when provider acceptance or durable binding is ambiguous.
+ */
 declare function launchExecution(options: LaunchExecutionOptions): Promise<ExecutionReference>;
 /** Dependencies and Task-attempt identity used to inspect one execution. */
 interface InspectExecutionOptions {
+  /** Task read used to establish and recheck the execution fence. */
   readonly stores: InspectExecutionStores;
+  /** Exact running Task attempt whose recorded execution may be inspected. */
   readonly task: TaskAttemptRef;
+  /** Provider boundary used only for observation. */
   readonly adapter: ExecutionAdapter;
 }
-/** Read a result without granting it lifecycle authority; workflows validate evidence and choose the next state. */
+/**
+ * Inspects a recorded execution without granting provider evidence lifecycle authority.
+ *
+ * @remarks
+ * The Task must be running on the exact attempt and have a recorded execution. Ownership is
+ * checked again after the provider call so a concurrent replacement cannot attach stale results.
+ * Finished results are schema-validated and must identify that same execution. This method writes
+ * no Task state or usage; the workflow decides how to validate evidence and transition afterward.
+ *
+ * @param options - Exact Task attempt, Task store, and provider adapter.
+ * @returns Current provider state and a validated result when finished.
+ * @throws `ExecutionFenceError` when the attempt or execution changes during inspection.
+ */
 declare function inspectExecution(options: InspectExecutionOptions): Promise<ExecutionInspectionResult>;
 /** Dependencies, Task-attempt identity, and provider result used to record usage. */
 interface RecordExecutionUsageOptions {
+  /** Receipt and Task stores used for idempotent usage persistence. */
   readonly stores: RecordExecutionUsageStores;
+  /** Exact Task attempt that owns the provider result. */
   readonly task: TaskAttemptRef;
+  /** Final provider result whose execution must match the Task's recorded handle. */
   readonly result: ExecutionResult;
 }
-/** For adapters reporting one immutable final usage packet instead of per-step usage hooks. */
+/**
+ * Records one adapter's immutable final usage packet without changing Task lifecycle state.
+ *
+ * @remarks
+ * Known cost is delegated to the Task usage store under a deterministic turn key, making identical
+ * replay non-charging. This API records an immutable final usage packet; an adapter must not also
+ * report the same charges through per-step usage hooks, because those observations use independent
+ * idempotency keys and would be added twice. When cost is unknown, an idempotent `usage_unresolved`
+ * receipt is appended and the Task remains unsettled so its reservation is retained. The workflow
+ * or reconciler must later supply measured usage before settlement.
+ *
+ * @param options - Exact Task attempt, final provider result, and persistence stores.
+ * @returns The Task after usage persistence, or unchanged after unresolved-cost evidence.
+ * @throws `ExecutionFenceError` when the result belongs to another attempt or execution.
+ */
 declare function recordExecutionUsage(options: RecordExecutionUsageOptions): Promise<Task>;
 /** Dependencies and reason used to cancel one exact Task execution attempt. */
 interface CancelExecutionOptions {
+  /** Task and receipt stores used for cancellation, usage, and settlement. */
   readonly stores: CancelExecutionStores;
+  /** Exact attempt to cancel; replacement attempts are refused. */
   readonly task: TaskAttemptRef;
+  /** Provider boundary used to request an idempotent stop and read its final observed result. */
   readonly adapter: ExecutionAdapter;
+  /** Human-readable cancellation reason retained in lifecycle evidence. */
   readonly reason: string;
 }
-/** Canonical cancellation precedes provider interruption. Retry this same call after an ambiguous stop. */
+/**
+ * Cancels canonical Task work, then interrupts and settles its exact provider execution.
+ *
+ * @remarks
+ * The Task first durably enters `cancelled`, preventing later workflow completion from winning.
+ * Provider interruption happens afterward and cannot roll that transition back. An absent recorded
+ * execution produces durable `cancellation_unresolved` evidence and throws. Since execution
+ * binding accepts only running Tasks, a handle discovered after this point cannot be attached by
+ * retrying this helper; application-owned reconciliation must stop that handle and persist its
+ * cleanup evidence and measured settlement separately. If `adapter.stop` fails ambiguously, retry
+ * this same call—the cancelled transition and adapter stop are both expected to be idempotent.
+ *
+ * Returned final usage is recorded once. Known cost then settles the Task; unknown cost retains the
+ * reservation and leaves reconciliation evidence for later measurement.
+ *
+ * @param options - Exact Task attempt, cancellation reason, stores, and provider adapter.
+ * @returns The cancelled Task after provider usage recording and any possible settlement.
+ * @throws `ExecutionFenceError` when the attempt has been replaced.
+ * @throws When execution discovery is unresolved or the provider stop request fails.
+ */
 declare function cancelExecution(options: CancelExecutionOptions): Promise<Task>;
 //#endregion
 export { CancelExecutionOptions, CancelExecutionStores, ExecutionAdapter, ExecutionFenceError, ExecutionInspectionResult, InspectExecutionOptions, InspectExecutionStores, LaunchExecutionOptions, LaunchExecutionStores, RecordExecutionUsageOptions, RecordExecutionUsageStores, StartExecutionInput, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage };