@vercel/factory 0.0.13 → 0.0.15

package/dist/eve/task-session.mjs

@@ -0,0 +1,203 @@
+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;
+}
+/** Encode a Task ID and attempt fence as headers for an Eve session request. */
+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)
+		}
+	};
+}
+/** Require valid Factory Task headers and bind them into the authenticated Eve initiator. */
+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/** 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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"}

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,65 @@
+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}`, {
+			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);
+		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        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"}

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 };

package/dist/execution-public.mjs

@@ -0,0 +1,7 @@
+import { codingExecutionRequestSchema, executionArtifactSchema, executionLaunchKeySchema, executionResultSchema, taskAttemptRef, taskAttemptRefFromTask, taskAttemptRefSchema } from "./schema/execution.mjs";
+import { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, ExecutionLaunchPendingError, dispatchTask } from "./dispatch.mjs";
+import { workNotificationSchema } from "./store/work-notifications.mjs";
+import { ExecutionFenceError, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage } from "./execution.mjs";
+import { sweepQueued } from "./sweep.mjs";
+import { stallWindowMinutes, sweepTaskStalls } from "./stall.mjs";
+export { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, ExecutionFenceError, ExecutionLaunchPendingError, cancelExecution, codingExecutionRequestSchema, dispatchTask, executionArtifactSchema, executionLaunchKey, executionLaunchKeySchema, executionResultSchema, inspectExecution, launchExecution, recordExecutionUsage, stallWindowMinutes, sweepQueued, sweepTaskStalls, taskAttemptRef, taskAttemptRefFromTask, taskAttemptRefSchema, workNotificationSchema };

package/dist/execution.d.mts

@@ -0,0 +1,75 @@
+import { ExecutionReference, Task } from "./schema/task.mjs";
+import { CodingExecutionRequest, ExecutionLaunchKey, ExecutionResult, TaskAttemptRef } from "./schema/execution.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+//#region src/execution.d.ts
+/** Validated request and stable idempotency key passed to an execution provider. */
+interface StartExecutionInput {
+  readonly request: CodingExecutionRequest;
+  readonly launchKey: ExecutionLaunchKey;
+}
+/** Current provider state when inspecting one recorded execution. */
+type ExecutionInspectionResult = {
+  status: "active";
+} | {
+  status: "expired";
+} | {
+  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. */
+  start(input: StartExecutionInput): Promise<ExecutionReference>;
+  /** Only active confirms that reattachment is safe. Missing/expired execution must never start implicitly. */
+  inspect(execution: ExecutionReference): Promise<ExecutionInspectionResult>;
+  /** Idempotent stop, returning final observed usage. May report cancellation even if interruption is unsupported. */
+  stop(execution: ExecutionReference): Promise<ExecutionResult>;
+}
+/** Error raised when an execution no longer matches the current running Task attempt. */
+declare class ExecutionFenceError extends Error {}
+/** Store capabilities required to launch or reattach a coding execution. */
+type LaunchExecutionStores = Pick<FactoryStores, "repositories" | "tasks">;
+/** Store capabilities required to inspect a coding execution. */
+type InspectExecutionStores = Pick<FactoryStores, "tasks">;
+/** Store capabilities required to persist final execution usage. */
+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. */
+declare function executionLaunchKey(ref: TaskAttemptRef): ExecutionLaunchKey;
+/** Dependencies and request used to start or reattach one coding execution. */
+interface LaunchExecutionOptions {
+  readonly stores: LaunchExecutionStores;
+  readonly request: CodingExecutionRequest;
+  readonly adapter: ExecutionAdapter;
+}
+/** Called inside a durable workflow step after dispatch gates. No provider lifecycle is stored here. */
+declare function launchExecution(options: LaunchExecutionOptions): Promise<ExecutionReference>;
+/** Dependencies and Task-attempt identity used to inspect one execution. */
+interface InspectExecutionOptions {
+  readonly stores: InspectExecutionStores;
+  readonly task: TaskAttemptRef;
+  readonly adapter: ExecutionAdapter;
+}
+/** Read a result without granting it lifecycle authority; workflows validate evidence and choose the next state. */
+declare function inspectExecution(options: InspectExecutionOptions): Promise<ExecutionInspectionResult>;
+/** Dependencies, Task-attempt identity, and provider result used to record usage. */
+interface RecordExecutionUsageOptions {
+  readonly stores: RecordExecutionUsageStores;
+  readonly task: TaskAttemptRef;
+  readonly result: ExecutionResult;
+}
+/** For adapters reporting one immutable final usage packet instead of per-step usage hooks. */
+declare function recordExecutionUsage(options: RecordExecutionUsageOptions): Promise<Task>;
+/** Dependencies and reason used to cancel one exact Task execution attempt. */
+interface CancelExecutionOptions {
+  readonly stores: CancelExecutionStores;
+  readonly task: TaskAttemptRef;
+  readonly adapter: ExecutionAdapter;
+  readonly reason: string;
+}
+/** Canonical cancellation precedes provider interruption. Retry this same call after an ambiguous stop. */
+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 };
+//# sourceMappingURL=execution.d.mts.map

package/dist/execution.mjs

@@ -0,0 +1,153 @@
+import { executionReferenceSchema } from "./schema/task.mjs";
+import { codingExecutionRequestSchema, executionLaunchKeySchema, executionResultSchema, taskAttemptRefSchema } from "./schema/execution.mjs";
+import { ExecutionLaunchPendingError } from "./dispatch.mjs";
+import { isDeepStrictEqual } from "node:util";
+//#region src/execution.ts
+/** Error raised when an execution no longer matches the current running Task attempt. */
+var ExecutionFenceError = class extends Error {};
+function sameExecution(left, right) {
+	return isDeepStrictEqual(left === void 0 ? void 0 : JSON.parse(JSON.stringify(left)), right === void 0 ? void 0 : JSON.parse(JSON.stringify(right)));
+}
+async function currentAttempt(stores, ref) {
+	const { taskId, attempt } = taskAttemptRefSchema.parse(ref);
+	const task = await stores.tasks.get(taskId);
+	if (!task || task.attempt !== attempt || task.state !== "running") throw new ExecutionFenceError(`Execution requires running Task ${taskId} at attempt ${attempt}`);
+	return task;
+}
+/** Construct the stable provider idempotency key for one exact Task attempt. */
+function executionLaunchKey(ref) {
+	const { taskId, attempt } = taskAttemptRefSchema.parse(ref);
+	return executionLaunchKeySchema.parse(`factory-task:${taskId}:${attempt}`);
+}
+/** Called inside a durable workflow step after dispatch gates. No provider lifecycle is stored here. */
+async function launchExecution(options) {
+	const { stores, adapter } = options;
+	const request = codingExecutionRequestSchema.parse(options.request);
+	const ref = {
+		taskId: request.taskId,
+		attempt: request.attempt
+	};
+	const task = await currentAttempt(stores, ref);
+	if (task.repositoryIds.length !== 1) throw new Error("Execution requires exactly one repository");
+	const repository = await stores.repositories.get(task.repositoryIds[0]);
+	if (!repository?.enabled || repository.slug !== request.repository.slug) throw new Error("Execution repository must match the Task's enabled repository");
+	if (task.execution) {
+		const observed = await adapter.inspect(task.execution);
+		if (!sameExecution((await currentAttempt(stores, ref)).execution, task.execution)) throw new ExecutionFenceError("Execution changed during reattachment");
+		if (observed.status !== "active") throw new Error(`Execution is ${observed.status}; workflow must reconcile its outcome before continuing`);
+		return task.execution;
+	}
+	const execution = executionReferenceSchema.parse(await adapter.start({
+		request,
+		launchKey: executionLaunchKey(ref)
+	}));
+	try {
+		await stores.tasks.recordExecution(task.id, {
+			execution,
+			expectAttempt: task.attempt
+		});
+	} catch (error) {
+		let current;
+		try {
+			current = await stores.tasks.get(task.id);
+		} catch (cause) {
+			throw new ExecutionLaunchPendingError("Execution binding requires recovery with its original key", { cause });
+		}
+		if (!current || current.attempt !== task.attempt || current.state !== "running" || current.execution && !sameExecution(current.execution, execution)) {
+			await adapter.stop(execution);
+			throw error;
+		}
+		throw new ExecutionLaunchPendingError("Execution binding requires recovery with its original key", { cause: error });
+	}
+	return execution;
+}
+/** Read a result without granting it lifecycle authority; workflows validate evidence and choose the next state. */
+async function inspectExecution(options) {
+	const { stores, adapter } = options;
+	const task = await currentAttempt(stores, options.task);
+	if (!task.execution) throw new Error(`Task ${options.task.taskId} has no recorded execution`);
+	const observed = await adapter.inspect(task.execution);
+	if (!sameExecution((await currentAttempt(stores, options.task)).execution, task.execution)) throw new ExecutionFenceError("Execution changed during inspection");
+	if (observed.status !== "finished") return observed;
+	const result = executionResultSchema.parse(observed.result);
+	if (!sameExecution(result.execution, task.execution)) throw new ExecutionFenceError("Result belongs to another execution");
+	return {
+		status: "finished",
+		result
+	};
+}
+/** For adapters reporting one immutable final usage packet instead of per-step usage hooks. */
+async function recordExecutionUsage(options) {
+	const { stores } = options;
+	const { taskId, attempt } = taskAttemptRefSchema.parse(options.task);
+	const result = executionResultSchema.parse(options.result);
+	const task = await stores.tasks.get(taskId);
+	if (!task || task.attempt !== attempt || !sameExecution(task.execution, result.execution)) throw new ExecutionFenceError("Usage belongs to a different Task attempt or execution");
+	if (result.usage.costUsd === void 0) {
+		await stores.receipts.append({
+			taskId,
+			repositoryIds: task.repositoryIds,
+			kind: task.kind,
+			state: "usage_unresolved",
+			phase: "budget",
+			attempt,
+			execution: result.execution,
+			reason: "Execution cost is unknown; retain the reservation until measured usage is available",
+			dedupeKey: `execution:${taskId}:${attempt}:usage-unresolved`
+		});
+		return task;
+	}
+	return stores.tasks.recordUsage(taskId, {
+		step: {
+			turnId: `execution:${attempt}:${result.execution.provider}:${result.execution.sessionId}`,
+			stepIndex: 0,
+			costUsd: result.usage.costUsd,
+			inputTokens: result.usage.inputTokens,
+			outputTokens: result.usage.outputTokens
+		},
+		fence: {
+			attempt,
+			execution: result.execution
+		}
+	});
+}
+/** Canonical cancellation precedes provider interruption. Retry this same call after an ambiguous stop. */
+async function cancelExecution(options) {
+	const { stores, adapter, reason } = options;
+	const { taskId, attempt } = taskAttemptRefSchema.parse(options.task);
+	let task = await stores.tasks.get(taskId);
+	if (!task || task.attempt !== attempt) throw new ExecutionFenceError("Cancellation belongs to a replaced attempt");
+	if (task.state !== "cancelled") task = await stores.tasks.transition(taskId, "cancelled", {
+		expectFrom: task.state,
+		expectAttempt: attempt,
+		reason
+	});
+	if (!task.execution) {
+		const reason = "Cancellation is recorded; execution discovery is still required before stop and settlement";
+		await stores.receipts.append({
+			taskId,
+			repositoryIds: task.repositoryIds,
+			kind: task.kind,
+			state: "cancellation_unresolved",
+			phase: "cleanup",
+			attempt,
+			reason,
+			dedupeKey: `execution:${taskId}:${attempt}:cancellation-unresolved`
+		});
+		throw new Error(reason);
+	}
+	const result = executionResultSchema.parse(await adapter.stop(task.execution));
+	task = await recordExecutionUsage({
+		stores,
+		task: {
+			taskId,
+			attempt
+		},
+		result
+	});
+	return result.usage.costUsd === void 0 ? task : stores.tasks.settle(taskId, { cost: { totalUsd: task.usage.costUsd } });
+}
+//#endregion
+export { ExecutionFenceError, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage };
+
+//# sourceMappingURL=execution.mjs.map