@vercel/factory 0.0.15 → 0.0.16

package/dist/eve/session-client.mjs

@@ -1,7 +1,43 @@
+import { readEvents } from "../client-events.mjs";
 import { ExecutionLaunchPendingError } from "../dispatch.mjs";
 import { Client } from "eve/client";
 //#region src/eve/session-client.ts
-/** Start or reconnect to an Eve session through its idempotent HTTP boundary. */
+/**
+* Starts or reconnects to one Eve session through its idempotent HTTP boundary.
+*
+* @remarks
+* This call sends one POST to the selected agent's `/eve/v1/session` endpoint. Reusing
+* `operationId` asks Eve to return the same logical session rather than create duplicate work.
+* The returned execution reference identifies provider acceptance only; Factory dispatch must
+* still persist it, and the agent must later complete or otherwise advance its Task.
+*
+* An HTTP refusal throws a regular error with the status. A successful response without a usable
+* session ID throws `ExecutionLaunchPendingError`, because the provider may have accepted work and
+* recovery must use the same operation ID. Request timeouts and transport failures propagate
+* unchanged because this transport helper does not own a durable retry loop. A launcher that can
+* recover the same running attempt must translate an ambiguous transport failure to
+* `ExecutionLaunchPendingError` at that boundary and retry with the same operation ID.
+*
+* @param options - Agent URL, initial message, stable operation ID, and optional request controls.
+* @returns An Eve execution reference containing the accepted session ID.
+* @throws `ExecutionLaunchPendingError` after an accepted response without a session ID, and a
+* regular error on timeout, transport failure, HTTP refusal, or invalid input.
+* @see The shipped `docs/recipes/eve-agent.md` recipe for the complete dispatch boundary.
+*
+* @example
+* ```ts
+* import { startEveSession, taskHeaders } from "@vercel/factory";
+* import type { TaskAttemptRef } from "@vercel/factory/execution";
+*
+* declare const task: TaskAttemptRef;
+* const execution = await startEveSession({
+*   agentUrl: "https://factory.example/eve/agents/worker",
+*   message: `Work Task ${task.taskId}`,
+*   operationId: `factory-task:${task.taskId}:${task.attempt}`,
+*   headers: taskHeaders(task),
+* });
+* ```
+*/
 async function startEveSession(options) {
 	const response = await (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session`, {
 		method: "POST",
@@ -24,10 +60,28 @@ async function startEveSession(options) {
 	};
 	throw new ExecutionLaunchPendingError(`${options.agentName ?? "Eve agent"} accepted the request but returned no session ID`);
 }
-/** Forward one authorized Factory API request to its exact Eve session. */
+/**
+* Forwards one authorized Factory API request to its exact Eve session.
+*
+* @remarks
+* The caller must authenticate and authorize the source request before invoking this helper. It
+* forwards the source method, abort signal, and POST body using the supplied binding headers, then
+* returns Eve's response unchanged. It does not interpret non-success status codes, retry the
+* request, or update Factory Task state, so callers retain operation-specific response and replay
+* handling.
+*
+* @param options - Exact Eve session, path, authorized source request, and transport controls.
+* @returns The unconsumed response from the Eve session endpoint.
+* @throws When a nonempty path is not absolute, resolves outside the session, contains a fragment,
+* or the request transport fails.
+*/
 async function forwardEveSessionRequest(options) {
-	if (!options.path.startsWith("/") || options.path.startsWith("//")) throw new Error("Eve session forwarding requires an absolute path suffix.");
-	return (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session/${encodeURIComponent(options.sessionId)}${options.path}`, {
+	if (options.path !== "" && (!options.path.startsWith("/") || options.path.startsWith("//"))) throw new Error("Eve session forwarding requires an absolute path suffix.");
+	const sessionUrl = `${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session/${encodeURIComponent(options.sessionId)}`;
+	const target = new URL(`${sessionUrl}${options.path}`);
+	const session = new URL(sessionUrl);
+	if (target.origin !== session.origin || target.hash !== "" || target.pathname !== session.pathname && !target.pathname.startsWith(`${session.pathname}/`)) throw new Error("Eve session forwarding path must stay within the selected session.");
+	return (options.fetch ?? globalThis.fetch)(target.href, {
 		method: options.source.method,
 		headers: jsonHeaders(await options.headers),
 		...options.source.method === "POST" ? { body: await options.source.text() } : {},
@@ -35,7 +89,23 @@ async function forwardEveSessionRequest(options) {
 		redirect: "error"
 	});
 }
-/** Request cancellation and confirm the exact Eve session has stopped running. */
+/**
+* Requests cancellation and confirms that the exact Eve session has stopped running.
+*
+* @remarks
+* A successful cancellation response is not sufficient by itself. Unless Eve reports
+* `no_active_turn`, this helper follows from the latest provider event and returns only after
+* observing `session.waiting`, `session.completed`, or `session.failed`. A refusal, timeout, stream
+* failure, or non-confirming event throws; the caller should keep canonical Task cancellation and
+* retry or inspect this same session rather than assume it stopped.
+*
+* This helper does not transition or settle a Factory Task. Use the higher-level execution
+* cancellation flow when Task lifecycle and usage must be persisted together.
+*
+* @param options - Exact Eve session plus request and confirmation bounds.
+* @returns After the provider confirms that the session has no active turn.
+* @throws On HTTP refusal, request or confirmation timeout, stream failure, or missing confirmation.
+*/
 async function cancelEveSession(options) {
 	const headers = await options.headers;
 	const response = await (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session/${encodeURIComponent(options.sessionId)}/cancel`, {
@@ -69,21 +139,63 @@ async function cancelEveSession(options) {
 	}
 	throw new Error("Eve execution cancellation is not yet confirmed by the provider stream");
 }
-/** Read the response from the latest fully completed Eve turn, if one exists. */
+/**
+* Reads the response from the latest fully completed Eve turn, if one exists.
+*
+* @remarks
+* This performs a bounded, non-following scan from the start of the session. It returns a nonempty
+* completed message only when the matching latest turn reaches `turn.completed`; failed,
+* cancelled, incomplete, over-limit, or message-less turns return `null`. The operation is
+* read-only and safe to repeat. The default reader verifies that it reached Eve's advertised
+* durable tail before accepting output. Transport and timeout failures are propagated so callers
+* can distinguish unavailable or truncated history from a confirmed lack of completed output.
+*
+* @param options - Exact Eve session plus stream deadline and event bound.
+* @returns The latest completed turn response, or `null` when no bounded complete response exists.
+* @throws When the event stream cannot be read or its deadline expires.
+*/
 async function readCompletedEveTurn(options) {
 	const headers = await options.headers ?? {};
-	let response = null;
-	let turnId;
-	let completed = false;
-	let count = 0;
-	for await (const event of (options.stream ?? streamEveSession)({
+	const signal = AbortSignal.timeout(options.timeoutMs ?? 1e4);
+	let expectedEventCount;
+	let events;
+	if (options.stream !== void 0) events = options.stream({
 		agentUrl: options.agentUrl,
 		sessionId: options.sessionId,
 		headers,
-		signal: AbortSignal.timeout(options.timeoutMs ?? 1e4),
+		signal,
 		startIndex: 0,
 		follow: false
-	})) {
+	});
+	else {
+		const query = new URLSearchParams({
+			startIndex: "0",
+			includeTailIndex: "1"
+		});
+		const response = await (options.fetch ?? globalThis.fetch)(`${options.agentUrl.replace(/\/+$/u, "")}/eve/v1/session/${encodeURIComponent(options.sessionId)}/stream?${query}`, {
+			cache: "no-store",
+			headers,
+			redirect: "error",
+			signal
+		});
+		if (!response.ok || response.body === null) {
+			await response.body?.cancel();
+			throw new Error(`Eve session history refused: ${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 session history did not include a valid durable cursor");
+		}
+		expectedEventCount = tail + 1;
+		events = readEvents(response.body);
+	}
+	let response = null;
+	let turnId;
+	let completed = false;
+	let count = 0;
+	for await (const event of events) {
 		if (++count > (options.maxEvents ?? 1e4)) return null;
 		const data = eventData(event);
 		if (event.type === "turn.started") {
@@ -99,6 +211,8 @@ async function readCompletedEveTurn(options) {
 			"session.failed"
 		].includes(event.type)) completed = false;
 	}
+	signal.throwIfAborted();
+	if (expectedEventCount !== void 0 && count !== expectedEventCount) throw new Error("Eve session history closed before its durable cursor");
 	return completed && response?.trim() ? response : null;
 }
 async function* streamEveSession(input) {

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

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

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

@@ -0,0 +1,380 @@
+import { TaskId } from "../schema/id.mjs";
+import { JsonValue } from "../schema/work.mjs";
+import { TaskKind } from "../schema/task.mjs";
+import "../workflows.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import "../tasks.mjs";
+import { SessionContext } from "eve/context";
+//#region src/eve/task-execution.d.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 },
+ * });
+ * ```
+ */
+declare function requireTaskExecution(stores: Pick<FactoryStores, "tasks">, ctx: {
+  session: Pick<SessionContext["session"], "id" | "auth">;
+}, requestedTaskId: TaskId): Promise<({
+  id: `task_${string}`;
+  schemaVersion: 1;
+  replyTo: {
+    channel: string;
+    address: string;
+  };
+  attempt: number;
+  updatedAt: string;
+  repositoryIds: readonly [`repo_${string}`, ...`repo_${string}`[]];
+  kind: TaskKind;
+  model?: string | undefined;
+  area?: string | undefined;
+  approval?: "required" | "granted" | "denied" | undefined;
+  origin: {
+    signalId?: `sig_${string}` | undefined;
+    operator?: string | undefined;
+  };
+  work: {
+    title: string;
+    input: JsonValue;
+    completionCriteria: readonly string[];
+    workflow: {
+      id: string;
+      version: number;
+    } & import("zod").$brand<"WorkflowBinding">;
+    route?: ({
+      id: string;
+      version: number;
+    } & import("zod").$brand<"AgentRouteBinding">) | undefined;
+  };
+  workflowPhase?: string | undefined;
+  rootTaskId: `task_${string}`;
+  pendingCommunicationReceiptIds?: readonly `rcpt_${string}`[] | undefined;
+  execution?: {
+    provider: string;
+    sessionId: string;
+    environmentId?: string | undefined;
+    harness?: string | undefined;
+    traceId?: string | undefined;
+  } | undefined;
+  lastProgressAt?: string | undefined;
+  reservedUsd?: number | undefined;
+  reservedAt?: string | undefined;
+  usage?: {
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    steps: Record<string, number>;
+  } | undefined;
+  settledUsd?: number | undefined;
+  answerEventIds?: readonly `ans_${string}`[] | undefined;
+  changeId?: `chg_${string}` | undefined;
+  reportRef?: string | undefined;
+  createdAt: string;
+} & {
+  stalledAt?: never;
+  stalledReason?: never;
+} & {
+  failureReceiptId?: never;
+} & {
+  state: "running";
+  waitingForMessages?: boolean;
+  needsHumanAction?: never;
+  needsHumanNotifiedAt?: never;
+  workResult?: {
+    output: JsonValue;
+    completedAt: string;
+  };
+} & {
+  question?: never;
+  questionTaskId?: never;
+  parentTaskAttempt?: never;
+  parentTaskId?: `task_${string}`;
+}) | ({
+  id: `task_${string}`;
+  schemaVersion: 1;
+  replyTo: {
+    channel: string;
+    address: string;
+  };
+  attempt: number;
+  updatedAt: string;
+  repositoryIds: readonly [`repo_${string}`, ...`repo_${string}`[]];
+  kind: TaskKind;
+  model?: string | undefined;
+  area?: string | undefined;
+  approval?: "required" | "granted" | "denied" | undefined;
+  origin: {
+    signalId?: `sig_${string}` | undefined;
+    operator?: string | undefined;
+  };
+  work: {
+    title: string;
+    input: JsonValue;
+    completionCriteria: readonly string[];
+    workflow: {
+      id: string;
+      version: number;
+    } & import("zod").$brand<"WorkflowBinding">;
+    route?: ({
+      id: string;
+      version: number;
+    } & import("zod").$brand<"AgentRouteBinding">) | undefined;
+  };
+  workflowPhase?: string | undefined;
+  rootTaskId: `task_${string}`;
+  pendingCommunicationReceiptIds?: readonly `rcpt_${string}`[] | undefined;
+  execution?: {
+    provider: string;
+    sessionId: string;
+    environmentId?: string | undefined;
+    harness?: string | undefined;
+    traceId?: string | undefined;
+  } | undefined;
+  lastProgressAt?: string | undefined;
+  reservedUsd?: number | undefined;
+  reservedAt?: string | undefined;
+  usage?: {
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    steps: Record<string, number>;
+  } | undefined;
+  settledUsd?: number | undefined;
+  answerEventIds?: readonly `ans_${string}`[] | undefined;
+  changeId?: `chg_${string}` | undefined;
+  reportRef?: string | undefined;
+  createdAt: string;
+} & {
+  stalledAt?: never;
+  stalledReason?: never;
+} & {
+  failureReceiptId?: never;
+} & {
+  state: "running";
+  waitingForMessages?: boolean;
+  needsHumanAction?: never;
+  needsHumanNotifiedAt?: never;
+  workResult?: {
+    output: JsonValue;
+    completedAt: string;
+  };
+} & {
+  question: {
+    text: string;
+    options: readonly string[];
+    closingOptions?: readonly string[] | undefined;
+    answer?: string | undefined;
+    answeredBy?: string | undefined;
+  };
+  questionTaskId?: never;
+  parentTaskAttempt?: never;
+  parentTaskId?: `task_${string}`;
+}) | ({
+  id: `task_${string}`;
+  schemaVersion: 1;
+  replyTo: {
+    channel: string;
+    address: string;
+  };
+  attempt: number;
+  updatedAt: string;
+  repositoryIds: readonly [`repo_${string}`, ...`repo_${string}`[]];
+  kind: TaskKind;
+  model?: string | undefined;
+  area?: string | undefined;
+  approval?: "required" | "granted" | "denied" | undefined;
+  origin: {
+    signalId?: `sig_${string}` | undefined;
+    operator?: string | undefined;
+  };
+  work: {
+    title: string;
+    input: JsonValue;
+    completionCriteria: readonly string[];
+    workflow: {
+      id: string;
+      version: number;
+    } & import("zod").$brand<"WorkflowBinding">;
+    route?: ({
+      id: string;
+      version: number;
+    } & import("zod").$brand<"AgentRouteBinding">) | undefined;
+  };
+  workflowPhase?: string | undefined;
+  rootTaskId: `task_${string}`;
+  pendingCommunicationReceiptIds?: readonly `rcpt_${string}`[] | undefined;
+  execution?: {
+    provider: string;
+    sessionId: string;
+    environmentId?: string | undefined;
+    harness?: string | undefined;
+    traceId?: string | undefined;
+  } | undefined;
+  lastProgressAt?: string | undefined;
+  reservedUsd?: number | undefined;
+  reservedAt?: string | undefined;
+  usage?: {
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    steps: Record<string, number>;
+  } | undefined;
+  settledUsd?: number | undefined;
+  answerEventIds?: readonly `ans_${string}`[] | undefined;
+  changeId?: `chg_${string}` | undefined;
+  reportRef?: string | undefined;
+  createdAt: string;
+} & {
+  stalledAt?: never;
+  stalledReason?: never;
+} & {
+  failureReceiptId?: never;
+} & {
+  state: "running";
+  waitingForMessages?: boolean;
+  needsHumanAction?: never;
+  needsHumanNotifiedAt?: never;
+  workResult?: {
+    output: JsonValue;
+    completedAt: string;
+  };
+} & {
+  question: {
+    text: string;
+    options: readonly string[];
+    closingOptions?: readonly string[] | undefined;
+    answer?: string | undefined;
+    answeredBy?: string | undefined;
+  };
+  questionTaskId?: never;
+  parentTaskAttempt: number;
+  parentTaskId: `task_${string}`;
+}) | ({
+  id: `task_${string}`;
+  schemaVersion: 1;
+  replyTo: {
+    channel: string;
+    address: string;
+  };
+  attempt: number;
+  updatedAt: string;
+  repositoryIds: readonly [`repo_${string}`, ...`repo_${string}`[]];
+  kind: TaskKind;
+  model?: string | undefined;
+  area?: string | undefined;
+  approval?: "required" | "granted" | "denied" | undefined;
+  origin: {
+    signalId?: `sig_${string}` | undefined;
+    operator?: string | undefined;
+  };
+  work: {
+    title: string;
+    input: JsonValue;
+    completionCriteria: readonly string[];
+    workflow: {
+      id: string;
+      version: number;
+    } & import("zod").$brand<"WorkflowBinding">;
+    route?: ({
+      id: string;
+      version: number;
+    } & import("zod").$brand<"AgentRouteBinding">) | undefined;
+  };
+  workflowPhase?: string | undefined;
+  rootTaskId: `task_${string}`;
+  pendingCommunicationReceiptIds?: readonly `rcpt_${string}`[] | undefined;
+  execution?: {
+    provider: string;
+    sessionId: string;
+    environmentId?: string | undefined;
+    harness?: string | undefined;
+    traceId?: string | undefined;
+  } | undefined;
+  lastProgressAt?: string | undefined;
+  reservedUsd?: number | undefined;
+  reservedAt?: string | undefined;
+  usage?: {
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    steps: Record<string, number>;
+  } | undefined;
+  settledUsd?: number | undefined;
+  answerEventIds?: readonly `ans_${string}`[] | undefined;
+  changeId?: `chg_${string}` | undefined;
+  reportRef?: string | undefined;
+  createdAt: string;
+} & {
+  stalledAt?: never;
+  stalledReason?: never;
+} & {
+  failureReceiptId?: never;
+} & {
+  state: "running";
+  waitingForMessages?: boolean;
+  needsHumanAction?: never;
+  needsHumanNotifiedAt?: never;
+  workResult?: {
+    output: JsonValue;
+    completedAt: string;
+  };
+} & {
+  question?: never;
+  questionTaskId: `task_${string}`;
+  parentTaskAttempt?: never;
+  parentTaskId?: `task_${string}`;
+})>;
+//#endregion
+export { requireTaskExecution };
+//# sourceMappingURL=task-execution.d.mts.map