@vercel/factory 0.0.14 → 0.0.16

package/dist/eve/task-execution.mjs

@@ -0,0 +1,73 @@
+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");
+	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 === 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, requireTaskExecutionIdentity };
+
+//# 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\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

@@ -0,0 +1,129 @@
+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;
+/**
+ * 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: {
+  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;
+/**
+ * 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>;
+/** 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

package/dist/eve/task-session.mjs

@@ -0,0 +1,245 @@
+import { repositoryIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { replyToSchema } from "../schema/common.mjs";
+import { taskAttemptRef } from "../schema/execution.mjs";
+import { ForbiddenError } from "eve/channels/auth";
+//#region src/eve/task-session.ts
+/** HTTP header that carries the authenticated Factory Task ID into an Eve session. */
+const factoryTaskHeader = "x-factory-task-id";
+/** Eve authentication attribute that stores the bound Factory Task ID. */
+const factoryTaskAttribute = "factoryTaskId";
+/** HTTP header that carries the Task attempt fence into an Eve session. */
+const factoryTaskAttemptHeader = "x-factory-task-attempt";
+/** Eve authentication attribute that stores the bound Task attempt fence. */
+const factoryTaskAttemptAttribute = "factoryTaskAttempt";
+/** HTTP header that carries the authenticated repository authorization envelope. */
+const factoryRepositoryIdsHeader = "x-factory-repository-ids";
+/** HTTP header that carries the authenticated conversation reply channel. */
+const factoryReplyChannelHeader = "x-factory-reply-channel";
+/** HTTP header that carries the authenticated conversation reply address. */
+const factoryReplyAddressHeader = "x-factory-reply-address";
+/** Eve authentication attribute that stores the authorized repository IDs. */
+const factoryRepositoryIdsAttribute = "factoryRepositoryIds";
+/** Eve authentication attribute that stores the conversation reply channel. */
+const factoryReplyChannelAttribute = "factoryReplyChannel";
+/** Eve authentication attribute that stores the conversation reply address. */
+const factoryReplyAddressAttribute = "factoryReplyAddress";
+/** Test whether authenticated Eve session state declares a Factory Task binding. */
+function hasFactoryTaskBinding(auth) {
+	return auth?.attributes[factoryTaskAttribute] !== void 0;
+}
+/**
+* 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,
+		[factoryTaskAttemptHeader]: String(task.attempt)
+	};
+}
+/** Encode a conversation's repository scope and reply destination as Eve request headers. */
+function conversationHeaders(input) {
+	return {
+		[factoryRepositoryIdsHeader]: input.repositoryIds.join(","),
+		[factoryReplyChannelHeader]: input.replyTo.channel,
+		[factoryReplyAddressHeader]: input.replyTo.address
+	};
+}
+/** Add a validated Task ID and attempt fence to an authenticated Eve initiator. */
+function taskSessionAuth(auth, task) {
+	return {
+		...auth,
+		attributes: {
+			...auth.attributes,
+			[factoryTaskAttribute]: task.taskId,
+			[factoryTaskAttemptAttribute]: String(task.attempt)
+		}
+	};
+}
+/**
+* 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);
+		if (auth == null) return auth;
+		const parsedTask = taskIdSchema.safeParse(request.headers.get(factoryTaskHeader));
+		const parsedAttempt = parseTaskAttempt(request.headers.get(factoryTaskAttemptHeader));
+		if (!parsedTask.success || parsedAttempt === null) throw new ForbiddenError();
+		return taskSessionAuth(auth, taskAttemptRef(parsedTask.data, parsedAttempt));
+	};
+}
+/** Bind optional Task and conversation headers while rejecting partial or malformed context. */
+function withOptionalFactoryTask(authenticate) {
+	return async (request) => {
+		const auth = await authenticate(request);
+		if (auth == null) return auth;
+		const taskId = request.headers.get(factoryTaskHeader);
+		const taskAttempt = request.headers.get(factoryTaskAttemptHeader);
+		const repositoryIds = request.headers.get(factoryRepositoryIdsHeader);
+		const replyChannel = request.headers.get(factoryReplyChannelHeader);
+		const replyAddress = request.headers.get(factoryReplyAddressHeader);
+		const hasConversationBinding = repositoryIds !== null || replyChannel !== null || replyAddress !== null;
+		if (taskId === null && taskAttempt === null && !hasConversationBinding) return auth;
+		const parsedTask = taskId === null ? null : taskIdSchema.safeParse(taskId);
+		const parsedAttempt = parseTaskAttempt(taskAttempt);
+		const parsedRepositories = repositoryIds === null ? null : repositoryIdSchema.array().min(1).safeParse(repositoryIds.split(",").filter(Boolean));
+		const parsedReplyTo = replyChannel === null || replyAddress === null ? null : replyToSchema.safeParse({
+			channel: replyChannel,
+			address: replyAddress
+		});
+		if (parsedTask !== null && !parsedTask.success || parsedTask === null !== (parsedAttempt === null) || hasConversationBinding && (parsedRepositories === null || !parsedRepositories.success || parsedReplyTo === null || !parsedReplyTo.success)) throw new ForbiddenError();
+		const conversationAttributes = parsedRepositories?.success === true && parsedReplyTo?.success === true ? {
+			[factoryRepositoryIdsAttribute]: parsedRepositories.data.join(","),
+			[factoryReplyChannelAttribute]: parsedReplyTo.data.channel,
+			[factoryReplyAddressAttribute]: parsedReplyTo.data.address
+		} : {};
+		return {
+			...auth,
+			attributes: {
+				...auth.attributes,
+				...parsedTask === null || parsedAttempt === null ? {} : {
+					[factoryTaskAttribute]: parsedTask.data,
+					[factoryTaskAttemptAttribute]: String(parsedAttempt)
+				},
+				...conversationAttributes
+			}
+		};
+	};
+}
+/** Read the required Factory Task ID from authenticated Eve session state. */
+function requireTaskIdForSession(auth) {
+	return taskIdSchema.parse(auth?.attributes[factoryTaskAttribute]);
+}
+/** Read an optional Task ID from authenticated session state, rejecting malformed values. */
+function optionalTaskIdForSession(auth) {
+	const value = auth?.attributes[factoryTaskAttribute];
+	return value === void 0 ? null : taskIdSchema.parse(value);
+}
+/** Read the complete, attempt-fenced Task binding established by Factory authentication. */
+function taskBindingForSession(auth) {
+	const taskId = requireTaskIdForSession(auth);
+	const rawAttempt = auth?.attributes[factoryTaskAttemptAttribute];
+	const attempt = parseTaskAttempt(typeof rawAttempt === "string" ? rawAttempt : null);
+	if (attempt === null) throw new Error("Factory session Task attempt binding is invalid.");
+	return {
+		taskId,
+		attempt
+	};
+}
+/** Read the repository authorization envelope, or null when the session has none. */
+function repositoryIdsForSession(auth) {
+	const value = auth?.attributes[factoryRepositoryIdsAttribute];
+	if (value === void 0) return null;
+	return repositoryIdSchema.array().min(1).parse(typeof value === "string" ? value.split(",").filter(Boolean) : value);
+}
+/** Read the authenticated reply destination, or null when the session has none. */
+function replyToForSession(auth) {
+	const channel = auth?.attributes[factoryReplyChannelAttribute];
+	const address = auth?.attributes[factoryReplyAddressAttribute];
+	if (channel === void 0 && address === void 0) return null;
+	return replyToSchema.parse({
+		channel,
+		address
+	});
+}
+/** Read the complete conversation binding, rejecting partial authentication state. */
+function conversationBindingForSession(auth) {
+	const repositoryIds = repositoryIdsForSession(auth);
+	const replyTo = replyToForSession(auth);
+	if (repositoryIds === null && replyTo === null) return null;
+	if (repositoryIds === null || replyTo === null) throw new Error("Factory session conversation binding is incomplete.");
+	return {
+		repositoryIds,
+		replyTo
+	};
+}
+const conversationBindingAttributes = [
+	factoryReplyChannelAttribute,
+	factoryReplyAddressAttribute,
+	factoryTaskAttribute,
+	factoryTaskAttemptAttribute
+];
+/**
+* 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.
+*/
+function conversationBinding(auth) {
+	const attributes = auth.initiator.attributes;
+	const replyTo = replyToSchema.parse({
+		channel: attributes[factoryReplyChannelAttribute],
+		address: attributes[factoryReplyAddressAttribute]
+	});
+	for (const key of conversationBindingAttributes) if (auth.current.attributes[key] !== void 0 && auth.current.attributes[key] !== attributes[key]) throw new Error("Conversation binding does not match the authenticated conversation");
+	const repositoryEnvelopes = [];
+	for (const [index, entry] of [auth.initiator, auth.current].entries()) {
+		const raw = entry.attributes[factoryRepositoryIdsAttribute];
+		if (index === 1 && raw === void 0) continue;
+		repositoryEnvelopes.push(repositoryIdSchema.array().min(1).parse(typeof raw === "string" ? raw.split(",") : raw));
+	}
+	let parentTask;
+	if (attributes["factoryTaskId"] !== void 0 || attributes["factoryTaskAttempt"] !== void 0) {
+		const taskId = taskIdSchema.parse(attributes[factoryTaskAttribute]);
+		const rawAttempt = attributes[factoryTaskAttemptAttribute];
+		const attempt = typeof rawAttempt === "string" ? parseTaskAttempt(rawAttempt) : null;
+		if (attempt === null) throw new Error("Conversation binding carries an invalid parent attempt");
+		parentTask = taskAttemptRef(taskId, attempt);
+	}
+	return {
+		replyTo,
+		repositoryEnvelopes,
+		parentTask
+	};
+}
+function parseTaskAttempt(value) {
+	if (value === null || !/^[1-9]\d*$/u.test(value)) return null;
+	const attempt = Number(value);
+	return Number.isSafeInteger(attempt) ? attempt : null;
+}
+//#endregion
+export { 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.mjs.map

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

@@ -0,0 +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/**\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":"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"}

package/dist/eve/transcript.d.mts

@@ -0,0 +1,37 @@
+import { RepositoryId } from "../schema/id.mjs";
+import { MaybePromise, ReplyTo } from "../schema/common.mjs";
+import { TaskAttemptRef } from "../schema/execution.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+//#region src/eve/transcript.d.ts
+/** Identifies the Eve execution and authenticated attributes to project into a transcript. */
+interface TranscriptMaterializationInput {
+  agent: string;
+  execution: {
+    provider: "eve";
+    sessionId: string;
+  };
+  attributes: Readonly<Record<string, string | readonly string[]>>;
+}
+/** The Task and conversation authorization context forwarded when reading an Eve transcript. */
+interface EveTranscriptRequestScope {
+  task?: TaskAttemptRef;
+  conversation?: {
+    repositoryIds: readonly RepositoryId[];
+    replyTo: ReplyTo;
+  };
+}
+/** Configures durable transcript storage and authenticated access to Eve session events. */
+interface EveTranscriptMaterializerOptions {
+  stores: Pick<FactoryStores, "transcripts">;
+  origin: string | (() => string);
+  headers?(scope: EveTranscriptRequestScope): MaybePromise<HeadersInit>;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+}
+/** Materializes one Eve execution stream into Factory's browser-safe transcript store. */
+type EveTranscriptMaterializer = (input: TranscriptMaterializationInput) => Promise<void>;
+/** Materialize a browser-safe transcript projection from one durable Eve session stream. */
+declare function createEveTranscriptMaterializer(options: EveTranscriptMaterializerOptions): EveTranscriptMaterializer;
+//#endregion
+export { EveTranscriptMaterializer, EveTranscriptMaterializerOptions, EveTranscriptRequestScope, TranscriptMaterializationInput, createEveTranscriptMaterializer };
+//# sourceMappingURL=transcript.d.mts.map

package/dist/eve/transcript.mjs

@@ -0,0 +1,69 @@
+import { repositoryIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { replyToSchema } from "../schema/common.mjs";
+import { taskAttemptRef } from "../schema/execution.mjs";
+import { factoryReplyAddressAttribute, factoryReplyChannelAttribute, factoryRepositoryIdsAttribute, factoryTaskAttemptAttribute, factoryTaskAttribute } from "./task-session.mjs";
+import { readEvents } from "../client-events.mjs";
+import { Transcript } from "../client-transcript.mjs";
+//#region src/eve/transcript.ts
+function attribute(attributes, name) {
+	const value = attributes[name];
+	return typeof value === "string" ? value : void 0;
+}
+function scopeFor(input) {
+	const taskId = taskIdSchema.safeParse(attribute(input.attributes, factoryTaskAttribute));
+	const attempt = Number(attribute(input.attributes, factoryTaskAttemptAttribute));
+	const repositories = repositoryIdSchema.array().min(1).safeParse(attribute(input.attributes, factoryRepositoryIdsAttribute)?.split(",").filter(Boolean));
+	const replyTo = replyToSchema.safeParse({
+		channel: attribute(input.attributes, factoryReplyChannelAttribute),
+		address: attribute(input.attributes, factoryReplyAddressAttribute)
+	});
+	return {
+		...taskId.success && Number.isSafeInteger(attempt) && attempt > 0 ? { task: taskAttemptRef(taskId.data, attempt) } : {},
+		...repositories.success && replyTo.success ? { conversation: {
+			repositoryIds: repositories.data,
+			replyTo: replyTo.data
+		} } : {}
+	};
+}
+/** Materialize a browser-safe transcript projection from one durable Eve session stream. */
+function createEveTranscriptMaterializer(options) {
+	const fetchImplementation = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	return async (input) => {
+		const previous = await options.stores.transcripts.get(input.execution);
+		const transcript = new Transcript();
+		if (previous !== null) transcript.hydrate(previous);
+		const query = new URLSearchParams({
+			startIndex: String(transcript.cursor),
+			includeTailIndex: "1"
+		});
+		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"
+		});
+		if (!response.ok || !response.body) {
+			await response.body?.cancel();
+			throw new Error(`Eve refused transcript materialization: ${response.status}`);
+		}
+		const tailValue = response.headers.get("x-eve-stream-tail-index");
+		const tail = tailValue === null ? NaN : Number(tailValue);
+		if (!Number.isSafeInteger(tail) || tail < -1) {
+			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 + 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());
+	};
+}
+//#endregion
+export { createEveTranscriptMaterializer };
+
+//# sourceMappingURL=transcript.mjs.map

package/dist/eve/transcript.mjs.map

@@ -0,0 +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        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-public.d.mts

@@ -0,0 +1,8 @@
+import { WorkNotification, WorkNotifications, workNotificationSchema } from "./store/work-notifications.mjs";
+import { CodingExecutionRequest, ExecutionArtifact, ExecutionLaunchKey, ExecutionResult, TaskAttemptRef, codingExecutionRequestSchema, executionArtifactSchema, executionLaunchKeySchema, executionResultSchema, taskAttemptRef, taskAttemptRefFromTask, taskAttemptRefSchema } from "./schema/execution.mjs";
+import { RecordTaskExecutionInput, RecordTaskUsageInput, StepUsage, TaskExecutionFence } from "./store/engine.mjs";
+import { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchBudget, DispatchOptions, DispatchRefusalCode, DispatchRefusedError, DispatchStores, DispatchTaskInput, ExecutionLaunchPendingError, dispatchTask } from "./dispatch.mjs";
+import { StallSweepOptions, TaskStallSweepResult, TaskStallSweepStores, stallWindowMinutes, sweepTaskStalls } from "./stall.mjs";
+import { CancelExecutionOptions, CancelExecutionStores, ExecutionAdapter, ExecutionFenceError, ExecutionInspectionResult, InspectExecutionOptions, InspectExecutionStores, LaunchExecutionOptions, LaunchExecutionStores, RecordExecutionUsageOptions, RecordExecutionUsageStores, StartExecutionInput, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage } from "./execution.mjs";
+import { SweepFailureReasonCode, SweepQueuedOptions, SweepQueuedResult, SweepQueuedStores, SweepSkipReasonCode, TaskLauncher, sweepQueued } from "./sweep.mjs";
+export { BudgetExhaustedError, type CancelExecutionOptions, type CancelExecutionStores, type CodingExecutionRequest, DEFAULT_MAX_LAUNCH_ATTEMPTS, type DispatchBudget, type DispatchOptions, type DispatchRefusalCode, DispatchRefusedError, type DispatchStores, type DispatchTaskInput, type ExecutionAdapter, type ExecutionArtifact, ExecutionFenceError, type ExecutionInspectionResult, type ExecutionLaunchKey, ExecutionLaunchPendingError, type ExecutionResult, type InspectExecutionOptions, type InspectExecutionStores, type LaunchExecutionOptions, type LaunchExecutionStores, type RecordExecutionUsageOptions, type RecordExecutionUsageStores, type RecordTaskExecutionInput, type RecordTaskUsageInput, type StallSweepOptions, type StartExecutionInput, type StepUsage, type SweepFailureReasonCode, type SweepQueuedOptions, type SweepQueuedResult, type SweepQueuedStores, type SweepSkipReasonCode, type TaskAttemptRef, type TaskExecutionFence, type TaskLauncher, type TaskStallSweepResult, type TaskStallSweepStores, type WorkNotification, type WorkNotifications, cancelExecution, codingExecutionRequestSchema, dispatchTask, executionArtifactSchema, executionLaunchKey, executionLaunchKeySchema, executionResultSchema, inspectExecution, launchExecution, recordExecutionUsage, stallWindowMinutes, sweepQueued, sweepTaskStalls, taskAttemptRef, taskAttemptRefFromTask, taskAttemptRefSchema, workNotificationSchema };