@segmentstream/agent 0.20.2 → 0.21.1

package/README.md

@@ -2,7 +2,7 @@
 
 The SegmentStream extension for a workspace's agent on [eve](https://www.npmjs.com/package/eve).
 It gives the agent the workspace's ontology as tools, acting as the member who is talking to it,
-and puts it behind the workspace's Telegram bot without a bot token in the deployment: Telegram
+lets the workspace's workflows hand it tasks, and puts it behind the workspace's Telegram bot without a bot token in the deployment: Telegram
 calls go through the workspace's connection, unknown senders pair with a member first, voice
 messages become text, and group chats are answered only when the agent is addressed or asked for
 something it does.
@@ -54,7 +54,7 @@ export default defineAgent({
   defaultTools: false,
   model: segmentstream.model(),
   reasoning: "medium",
-  limits: { maxTokenCostUsdPerSession: 2 },
+  limits: { sessionUsage: ({ window }) => (window.costUsd ?? 0) >= 2 },
 });
 ```
 
@@ -203,8 +203,9 @@ continue using GET lookup. Starter templates and pins remain unchanged in this s
 
 | Name                                                               | Slot           | What it does                                                                                                                                                                    |
 | ------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `segmentstream__ontology`                                          | `connections`  | Direct MCP tools through Eve search, calls and approvals, acting as the current member.                                                                                         |
+| `segmentstream__ontology`                                          | `connections`  | Direct MCP tools through Eve search, calls and approvals, acting as the current member or task.                                                                                 |
 | `segmentstream__telegram`                                          | `channels`     | `POST /eve/v1/telegram`: Telegram through the connection, with pairing, routing and voice.                                                                                      |
+| `segmentstream__tasks`                                             | `channels`     | `POST /eve/segmentstream/v1/tasks`: a workflow's `agentTask`, run as the workflow's user; see [Workflow tasks](#workflow-tasks).                                                |
 | `segmentstream__attachments_list`, `_read`, `_promote`, `_discard` | `tools`        | The member's temporary attachments in this chat: list, read, keep through an action, drop.                                                                                      |
 | `segmentstream__attachments_send`                                  | `tools`        | Sends readable stored ontology files into the current Telegram chat and topic.                                                                                                  |
 | `segmentstream__bash`, `_read_file`, `_write_file`                 | `tools`        | With `"sandbox": true`: eve's file tools, only in the sandbox `@segmentstream/agent/sandbox` opened.                                                                            |
@@ -269,6 +270,48 @@ member in history. A turn whose principal carries no `memberId`, such as an unpa
 gets no ontology connection at all. Each member gets their own connection instance, so members who
 share a group chat's session never share a client.
 
+A task session sends the task's secret in `X-SegmentStream-Agent-Task` instead of
+`X-SegmentStream-Act-As`, never both, on `/mcp` and on the metadata reads of its approval checks.
+The ontology resolves the workflow's user from the secret, so the session sees and runs exactly
+what that user may. Its instance key is `{origin}/mcp#task:<task id>`, so a task never shares a
+client with a member, and it negotiates neither chat posting nor the chat's runtime source.
+
+### Workflow tasks
+
+A workflow hands the workspace's agent a prompt with `agentTask` from
+`@segmentstream-cloud/ontology/workflows` and waits for its answer
+([the specification](../../docs/agent-tasks-spec.md)). The task runs in an ordinary session of the
+same agent: its instructions, model choice from the principal's roles, tools, guides and sandbox.
+The SDK adds no text to the prompt.
+
+- **Start.** The ontology calls `POST /eve/segmentstream/v1/tasks` with `{ "task_id", "secret" }`
+  and the deployment's runtime token. The route admits only functions of the same Vercel project in
+  production, as the health route does; elsewhere it answers 404. It reads
+  `GET /api/ontology/agent/tasks/current` with the secret and answers 409 when the task is not
+  live or is another task. Otherwise it ends any earlier session at `task:<task id>`, starts the
+  session with the prompt as its first message and answers 202 once the session accepted it.
+- **Principal.** `segmentstream-agent-task`, a `service` principal with the workflow user's id and
+  `taskId`, `workflow`, `roles` and `name`, all from the ontology's answer, never from the request.
+- **The secret.** The route hands the secret to the session in the channel's adapter state; the
+  session's first event moves it into the session's durable task state, and it is forgotten once
+  the outcome is reported. It is never in the principal, the model's context, tool arguments or
+  results, the session's events, logs or the conversation archive.
+- **No person is present.** Ontology actions the workflow's role permits run without confirmation
+  cards. Attachments, member files, chat history and `chat_post_message` are not offered. A
+  question from `questions_ask`, an approval a tool asks a person for, eve's own questions or a
+  sign-in end the task as `needs_input` with the question's text; the per-session cost cap ends it
+  as `failed`.
+- **Report.** When the turn ends, the channel posts the outcome to
+  `POST /api/ontology/agent/tasks/current/result`: `completed` with the turn's reply text,
+  `needs_input`, or `failed` with `agent_failed`. Text longer than 65,536 characters is cut and
+  marked `truncated`. A 409 means the task was already reported. Network failures, 429 and 5xx
+  retry with backoff for up to two minutes and never past the task's deadline. After the report,
+  or when the ontology refuses the secret, the session ends: eve has no command for a session to
+  retire itself, so it asks its own deployment's `POST /eve/segmentstream/v1/tasks/end`, which ends
+  only the session that still owns the task's address.
+- **Logs.** The conversation archive keeps a task's events under provider `task` and the task's id,
+  with no member taking part, so `segmentstream agent logs --chat <task id>` shows them.
+
 ### Telegram
 
 - **Credentials.** eve's Telegram channel puts the bot token in the URL path. The adapter gives it a
@@ -546,7 +589,7 @@ a provider token.
 | `SEGMENTSTREAM_WORKSPACE_ID`          | The workspace in the proxy's path                                               |
 | `SEGMENTSTREAM_ORGANIZATION_ID`       | The tenant the proxy selects                                                    |
 | `SEGMENTSTREAM_AGENT_WEBHOOK_SECRET`  | The Telegram webhook secret; the only secret                                    |
-| `SEGMENTSTREAM_RUNTIME_OIDC_ISSUER`   | The team's OIDC issuer, which signs the tokens the messages route accepts       |
+| `SEGMENTSTREAM_RUNTIME_OIDC_ISSUER`   | The team's OIDC issuer, which signs the tokens the health and task routes take  |
 | `SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE` | The audience those tokens must name                                             |
 | `VERCEL_PROJECT_ID`                   | The project those tokens must name                                              |
 | `VERCEL_ENV`                          | Channels run only in `production`; `preview` selects the preview model          |
@@ -740,7 +783,9 @@ Upgrade the workspace ontology together with the agent: the connection requires
 runtime-envelope and exact chat-post contracts. Member authentication, provider provenance,
 trusted runtime arguments and exact chat-post confirmations remain in the adapter. The server
 authorizes each call against current permissions; connections are member-specific. Runtime
-catalogs omit optional output schemas unless `mcp.toolListing: "full"` is configured.
+catalogs omit optional output schemas. External MCP clients receive the same direct operations
+through standard cursor-paginated `tools/list`; the ontology search/describe/dispatch helpers
+are no longer exposed.
 
 Consequential actions pause the Eve turn until the requester approves or cancels. Other members
 in a shared chat may wait for its outcome. Eve caches discovery within a connection's lifetime;

package/dist/_chunks/{build-metadata-CftTwBkw.mjs → build-metadata-kBu1knj6.mjs}

@@ -4,7 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-var version = "0.20.2";
+var version = "0.21.1";
 function agentBuild(environment = process.env) {
 	return {
 		agent: version,

package/dist/_chunks/{principal-DFcIfKSa.mjs → principal-69qoDdqy.mjs}

@@ -4,6 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import "../extension/lib/agent-task.mjs";
 import { n as currentInboundRequest } from "./inbound-request-gJ5wpsBF.mjs";
 import { randomUUID } from "node:crypto";
 function telegramRuntimeSource(message, files, callbackQueryId) {
@@ -111,6 +112,7 @@ function conversationLanguage(texts) {
 	}
 }
 function memberIdOf(principal) {
+	if (principal?.authenticator === "segmentstream-agent-task") return;
 	const memberId = principal?.attributes.memberId;
 	return typeof memberId === "string" && memberId !== "" ? memberId : void 0;
 }

package/dist/extension/channels/tasks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `segmentstream__tasks` at `POST /eve/segmentstream/v1/tasks`: the ontology starts a workflow's
+ * `agentTask` here, and the agent works on its prompt as the workflow's user, then reports the
+ * outcome (`docs/agent-tasks-spec.md`). Only this deployment's functions may call it, in production.
+ */
+declare const _default: import("eve/channels").Channel<import("../lib/agent-task-channel.js").AgentTaskChannelState, Record<string, unknown>, Record<string, unknown>>;
+export default _default;

package/dist/extension/channels/tasks.mjs

@@ -0,0 +1,9 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { agentTaskChannel } from "../lib/agent-task-channel.mjs";
+var tasks_default = agentTaskChannel();
+export { tasks_default as default };

package/dist/extension/connections/ontology.d.ts

@@ -1,3 +1,3 @@
-/** Let Eve own tool discovery, schemas and calls, while retaining our member/approval boundary. */
+/** Let Eve own tool discovery, schemas and calls, while retaining our member, task and approval boundary. */
 declare const _default: import("eve").DynamicSentinel<import("eve/connections").DynamicConnectionResult, import("eve").DynamicContext>;
 export default _default;

package/dist/extension/hooks/authorization.mjs

@@ -5,7 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { localizedText } from "../lib/admission.mjs";
-import "../../_chunks/principal-DFcIfKSa.mjs";
+import "../../_chunks/principal-69qoDdqy.mjs";
 import { confirmationLocale } from "../lib/telegram/confirmation-text.mjs";
 import segmentstream from "../extension.mjs";
 import { defineHook } from "eve/hooks";

package/dist/extension/instructions/conversations.d.ts

@@ -1,3 +1,6 @@
-/** Refreshes durable chat context on every turn, including bot posts and cold starts. */
+/**
+ * Refreshes durable chat context on every turn, including bot posts and cold starts. A task has no
+ * chat: its prompt is all the workspace's, so a task session gets none.
+ */
 declare const _default: import("eve").DynamicSentinel<import("eve/instructions").DynamicInstructionsResult, import("eve").DynamicContext>;
 export default _default;

package/dist/extension/instructions/conversations.mjs

@@ -4,13 +4,14 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { agentTaskIdOf } from "../lib/agent-task.mjs";
 import { conversations, storedConversationContext } from "../lib/conversations.mjs";
 import { conversationCoordinates } from "../lib/conversation-runtime.mjs";
 import { defineDynamic, defineInstructions } from "eve/instructions";
 const archive = conversations();
 var conversations_default = defineDynamic(async (context) => {
 	const coordinates = conversationCoordinates(context);
-	if (coordinates === void 0) return null;
+	if (coordinates === void 0 || agentTaskIdOf(context.session.auth.current) !== void 0) return null;
 	const content = await context.memo([context.turn?.id ?? null, coordinates.participantIds], () => storedConversationContext(archive, coordinates));
 	return content === null ? null : defineInstructions({
 		role: "user",

package/dist/extension/lib/actor.d.ts

@@ -0,0 +1,39 @@
+import type { SessionAuthContext } from "eve/context";
+import { type DynamicToolEntry } from "eve/tools";
+/** The header that names the member a runtime caller acts for. */
+export declare const ACT_AS_HEADER = "X-SegmentStream-Act-As";
+/**
+ * Whom a session acts for at the ontology: the paired member who writes, or the workflow user of a
+ * task, whom the ontology resolves from the task's secret. It comes from the principal a
+ * SegmentStream channel stamped, never from the model.
+ */
+export type OntologyActor = {
+    readonly kind: "member";
+    readonly memberId: string;
+} | {
+    readonly kind: "task";
+    readonly taskId: string;
+};
+export declare function member(memberId: string): OntologyActor;
+export declare function actorOf(principal: SessionAuthContext | null | undefined): OntologyActor | undefined;
+/** A stable key per actor, such as `member:<id>` or `task:<id>`. */
+export declare function actorKey(actor: OntologyActor): string;
+/** The session has no member or task to act for, or not the one a client was opened for. */
+export declare class ActorRequiredError extends Error {
+    readonly name = "ActorRequiredError";
+}
+/**
+ * The headers that name whom an ontology request acts for: the member in `X-SegmentStream-Act-As`
+ * with the verified identity provider, or the task's secret in `X-SegmentStream-Agent-Task`.
+ * A request never carries both. The secret is read from the session's task state.
+ */
+export declare function actorHeaders(input: {
+    readonly actor: OntologyActor;
+    readonly principal?: SessionAuthContext | null;
+    readonly secret?: (taskId: string) => string | undefined;
+}): Record<string, string>;
+/**
+ * A tool only a member's session offers. A task has no chat, attachments or member files, so a
+ * task session is not offered the tool at all; other sessions get it as before.
+ */
+export declare function memberTool<Tool extends DynamicToolEntry>(tool: Tool): import("eve").DynamicSentinel<import("eve/tools").DynamicToolResult, import("eve").DynamicContext>;

package/dist/extension/lib/actor.mjs

@@ -0,0 +1,48 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { AGENT_TASK_HEADER, agentTaskIdOf, taskSecret } from "./agent-task.mjs";
+import { i as memberIdOf, r as identityProviderOf } from "../../_chunks/principal-69qoDdqy.mjs";
+import { defineDynamic } from "eve/tools";
+const ACT_AS_HEADER = "X-SegmentStream-Act-As";
+function member(memberId) {
+	return {
+		kind: "member",
+		memberId
+	};
+}
+function actorOf(principal) {
+	const taskId = agentTaskIdOf(principal);
+	if (taskId !== void 0) return {
+		kind: "task",
+		taskId
+	};
+	const memberId = memberIdOf(principal);
+	return memberId === void 0 ? void 0 : member(memberId);
+}
+function actorKey(actor) {
+	return actor.kind === "member" ? `member:${actor.memberId}` : `task:${actor.taskId}`;
+}
+var ActorRequiredError = class extends Error {
+	name = "ActorRequiredError";
+};
+function actorHeaders(input) {
+	const { actor } = input;
+	if (actor.kind === "task") {
+		const secret = (input.secret ?? taskSecret)(actor.taskId);
+		if (secret === void 0) throw new ActorRequiredError("The task is no longer live in this session.");
+		return { [AGENT_TASK_HEADER]: secret };
+	}
+	const provider = memberIdOf(input.principal) === actor.memberId ? identityProviderOf(input.principal) : void 0;
+	return {
+		[ACT_AS_HEADER]: actor.memberId,
+		...provider === void 0 ? {} : { "X-SegmentStream-Identity-Provider": provider }
+	};
+}
+function memberTool(tool) {
+	return defineDynamic((context) => actorOf(context.session.auth.current)?.kind === "task" ? null : tool);
+}
+export { ACT_AS_HEADER, ActorRequiredError, actorHeaders, actorKey, actorOf, member, memberTool };

package/dist/extension/lib/agent-task-channel.d.ts

@@ -0,0 +1,45 @@
+import { type Channel, type ChannelEvents } from "eve/channels";
+import type { StateHandle } from "eve/context";
+import { type AgentTasks, type AgentTaskSession } from "./agent-task.js";
+import { type Environment } from "./environment.js";
+import { type RuntimeTokenVerifier } from "./runtime-identity.js";
+import type { RuntimeToken } from "./runtime-token.js";
+/**
+ * The task channel (`docs/agent-tasks-spec.md`). The ontology starts a task at
+ * `POST /eve/segmentstream/v1/tasks` with the task's id and secret. The route reads the task with
+ * the secret, ends an earlier session at the task's address, and starts the session with the
+ * workspace's prompt as its first message, acting as the workflow's user. When the turn ends, the
+ * channel reports the outcome to the ontology and ends the session.
+ */
+/** The channel's adapter state: the task, until the session's first event takes it. */
+export interface AgentTaskChannelState {
+    pending: AgentTaskSession | null;
+}
+interface AgentTaskChannelContext {
+    readonly state: AgentTaskChannelState;
+}
+export interface AgentTaskChannelOptions {
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+    /** Verifies the route's callers; tests pass one on a local key set. */
+    readonly verify?: RuntimeTokenVerifier;
+    /** The ontology's task routes; tests pass a fake. */
+    readonly tasks?: AgentTasks;
+    readonly state?: StateHandle<AgentTaskSession | null>;
+    /** How long the route waits for an earlier session at the address to retire. */
+    readonly retireTimeoutMs?: number;
+    readonly log?: (message: string, detail: unknown) => void;
+}
+/**
+ * The events that end a task session's turn. The first event of the session moves the task out of
+ * the adapter state into the session's task state, where the ontology connection reads it.
+ */
+export declare function agentTaskEvents(input: {
+    readonly tasks: () => AgentTasks;
+    readonly state?: StateHandle<AgentTaskSession | null>;
+    readonly log?: (message: string, detail: unknown) => void;
+}): ChannelEvents<AgentTaskChannelContext>;
+/** The task channel of the extension. */
+export declare function agentTaskChannel(options?: AgentTaskChannelOptions): Channel<AgentTaskChannelState>;
+export {};

package/dist/extension/lib/agent-task-channel.mjs

@@ -0,0 +1,201 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { redactDiagnostic } from "./diagnostics.mjs";
+import { channelsEnabled, runtimeIdentityEnvironment } from "./environment.mjs";
+import { AGENT_TASK_END_ROUTE, AGENT_TASK_ROUTE, agentTaskSessions, agentTasks, taskAddress, taskPrincipal } from "./agent-task.mjs";
+import { runtimeTokenVerifier } from "./runtime-identity.mjs";
+import { runtimeRequestFailure } from "./telegram/runtime-request.mjs";
+import { POST, defineChannel } from "eve/channels";
+import { interaction, reply } from "eve/events";
+import { SessionNotActiveError } from "eve/sessions";
+const RETIRE_TIMEOUT_MS = 2e4;
+const FAILED = {
+	status: "failed",
+	reason: "agent_failed"
+};
+const TASK_ID = /^[0-9A-Za-z][0-9A-Za-z_-]{0,127}$/;
+const SECRET = /^[0-9A-Za-z_-]{16,512}$/;
+function error(code, status) {
+	return Response.json({ error: code }, { status });
+}
+async function fields(request, names) {
+	let body;
+	try {
+		body = await request.json();
+	} catch {
+		return;
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return;
+	const record = body;
+	const [first, second] = [record[names[0]], record[names[1]]];
+	return typeof first === "string" && typeof second === "string" ? [first, second] : void 0;
+}
+function replyText(view, turnId) {
+	return reply(view, turnId).filter((part) => part.kind === "text" && part.interrupted !== true).flatMap((part) => typeof part.value === "string" ? [part.value] : []).join("\n");
+}
+function agentTaskEvents(input) {
+	const state = input.state ?? agentTaskSessions;
+	const log = input.log ?? ((message, detail) => console.error(message, detail));
+	function adopt(channel) {
+		const pending = channel?.state.pending ?? null;
+		if (pending !== null) {
+			state.update(() => pending);
+			channel.state.pending = null;
+		}
+		return state.get();
+	}
+	async function finish(sessionId, task, outcome, end) {
+		if (task === null || task.secret === null) return;
+		try {
+			await input.tasks().report(task.secret, outcome, {
+				taskId: task.taskId,
+				deadlineAt: task.deadlineAt
+			});
+		} finally {
+			state.update((current) => current?.taskId === task.taskId ? {
+				...current,
+				secret: null
+			} : current);
+		}
+		if (!end) return;
+		try {
+			await input.tasks().end({
+				taskId: task.taskId,
+				sessionId
+			});
+		} catch (cause) {
+			log("[segmentstream] agent_task_end_failed", {
+				taskId: task.taskId,
+				sessionId,
+				error: cause
+			});
+		}
+	}
+	return {
+		"turn.started"(_event, ctx) {
+			adopt(ctx.channel);
+		},
+		async "turn.paused"(event, ctx) {
+			const task = adopt(ctx.channel);
+			const asked = event.data.awaiting.flatMap(({ interactionId }) => {
+				const found = interaction(ctx.view, interactionId);
+				return found === void 0 ? [] : [found];
+			});
+			await finish(ctx.session.id, task, asked.some((item) => item.request.kind === "budget") ? FAILED : {
+				status: "needs_input",
+				text: asked.map((item) => item.request.prompt || (item.request.title ?? "")).filter((text) => text !== "").join("\n\n")
+			}, true);
+		},
+		async "turn.settled"(event, ctx) {
+			const task = adopt(ctx.channel);
+			const question = task?.question;
+			const { outcome, turnId } = event.data;
+			await finish(ctx.session.id, task, outcome !== "completed" ? FAILED : question?.turnId === turnId ? {
+				status: "needs_input",
+				text: question.text
+			} : {
+				status: "completed",
+				text: replyText(ctx.view, turnId)
+			}, true);
+		},
+		async "session.ended"(_event, ctx) {
+			await finish(ctx.session.id, adopt(ctx.channel), FAILED, false);
+		}
+	};
+}
+async function retire(source, timeoutMs) {
+	let delivery;
+	try {
+		delivery = await source.reset();
+	} catch (cause) {
+		if (SessionNotActiveError.is(cause)) return;
+		throw cause;
+	}
+	await delivery.result({ signal: AbortSignal.timeout(timeoutMs) });
+}
+function agentTaskChannel(options = {}) {
+	const environment = options.environment ?? process.env;
+	const log = options.log ?? ((message, detail) => console.error(message, detail));
+	let verify = options.verify;
+	let client = options.tasks;
+	const tasks = () => client ??= agentTasks({
+		environment,
+		...options.token === void 0 ? {} : { token: options.token },
+		...options.fetch === void 0 ? {} : { fetch: options.fetch }
+	});
+	const authenticate = (request) => runtimeRequestFailure(request, {
+		enabled: () => true,
+		configured: () => channelsEnabled(environment),
+		verify: () => verify ??= runtimeTokenVerifier(runtimeIdentityEnvironment(environment))
+	});
+	async function start(request, args) {
+		const failure = await authenticate(request);
+		if (failure !== void 0) return failure;
+		const body = await fields(request, ["task_id", "secret"]);
+		if (body === void 0 || !TASK_ID.test(body[0]) || !SECRET.test(body[1])) return error("invalid_request", 400);
+		const [taskId, secret] = body;
+		let lookup;
+		try {
+			lookup = await tasks().current(secret);
+		} catch (cause) {
+			log("[segmentstream] agent_task_lookup_failed", {
+				taskId,
+				error: redactDiagnostic(cause, new Set([secret]))
+			});
+			return error("unavailable", 503);
+		}
+		if (lookup.status === "refused" || lookup.task.id !== taskId) return error("task_not_live", 409);
+		const task = lookup.task;
+		const source = args.from(taskAddress(task.id));
+		try {
+			await retire(source, options.retireTimeoutMs ?? RETIRE_TIMEOUT_MS);
+			const still = await tasks().current(secret);
+			if (still.status === "refused" || still.task.id !== taskId) return error("task_not_live", 409);
+			await source.send(task.prompt, {
+				auth: taskPrincipal(task),
+				state: { pending: {
+					taskId: task.id,
+					secret,
+					deadlineAt: task.deadlineAt
+				} }
+			});
+		} catch (cause) {
+			log("[segmentstream] agent_task_start_failed", {
+				taskId,
+				error: redactDiagnostic(cause, new Set([secret]))
+			});
+			return error("unavailable", 503);
+		}
+		return Response.json({ accepted: true }, { status: 202 });
+	}
+	async function end(request, args) {
+		const failure = await authenticate(request);
+		if (failure !== void 0) return failure;
+		const body = await fields(request, ["task_id", "session_id"]);
+		if (body === void 0 || !TASK_ID.test(body[0]) || body[1] === "") return error("invalid_request", 400);
+		const [taskId, sessionId] = body;
+		const owner = await args.resolveSession(taskAddress(taskId));
+		if (owner?.id !== sessionId) return Response.json({ ended: false });
+		try {
+			await owner.reset();
+		} catch (cause) {
+			if (!SessionNotActiveError.is(cause)) throw cause;
+		}
+		return Response.json({ ended: true }, { status: 202 });
+	}
+	return defineChannel({
+		state: { pending: null },
+		context: (state) => ({ state }),
+		routes: [POST(AGENT_TASK_ROUTE, start), POST(AGENT_TASK_END_ROUTE, end)],
+		events: agentTaskEvents({
+			tasks,
+			...options.state === void 0 ? {} : { state: options.state },
+			log
+		})
+	});
+}
+export { agentTaskChannel, agentTaskEvents };

package/dist/extension/lib/agent-task.d.ts

@@ -0,0 +1,127 @@
+import { type SessionAuthContext, type StateHandle } from "eve/context";
+import { type Environment } from "./environment.js";
+import { type RuntimeToken } from "./runtime-token.js";
+/**
+ * Agent tasks (`docs/agent-tasks-spec.md`): a workflow hands the workspace's agent one prompt, and
+ * the agent works on it in a session of its own, acting as the workflow's user, then reports the
+ * outcome. The ontology owns the task; it authenticates the agent's calls for the task with a
+ * secret it mints per start attempt and sends only to the task route.
+ */
+/** The route authenticator of a task session's principal. */
+export declare const AGENT_TASK_AUTHENTICATOR = "segmentstream-agent-task";
+/** The header that carries a live task's secret; it replaces `X-SegmentStream-Act-As`. */
+export declare const AGENT_TASK_HEADER = "X-SegmentStream-Agent-Task";
+/** Where the ontology starts a task. eve reserves `/eve/v1/*`. */
+export declare const AGENT_TASK_ROUTE = "/eve/segmentstream/v1/tasks";
+/**
+ * Where a task session asks its own deployment to end it. eve offers no command for a session to
+ * retire itself, so the session calls the route that holds the channel's operations.
+ */
+export declare const AGENT_TASK_END_ROUTE = "/eve/segmentstream/v1/tasks/end";
+/** The most characters of an outcome's text the ontology keeps; longer text is cut. */
+export declare const MAXIMUM_TASK_TEXT = 65536;
+/** The task channel's address of a task's session. */
+export declare function taskAddress(taskId: string): string;
+/** A live task, as `GET /api/ontology/agent/tasks/current` answers it. */
+export interface CurrentTask {
+    readonly id: string;
+    readonly workflow: string;
+    readonly prompt: string;
+    readonly deadlineAt: string;
+    /** The workflow's user, whom the task acts as. */
+    readonly principal: {
+        readonly id: string;
+        readonly name: string;
+        readonly roles: ReadonlyArray<string>;
+    };
+}
+/**
+ * The principal of a task session. It comes from the ontology's answer for the secret, never from
+ * the route's body, so a caller cannot choose whom the agent acts as. The secret is not part of it.
+ */
+export declare function taskPrincipal(task: CurrentTask): SessionAuthContext;
+/** The task a session principal works on, when the task channel stamped it. */
+export declare function agentTaskIdOf(principal: SessionAuthContext | null | undefined): string | undefined;
+/**
+ * What a task session keeps between steps. The secret lives only here, in eve's durable session
+ * state: never in the principal, the model's context, tool arguments or results, or the session's
+ * events. The ontology connection's headers and the result report read it.
+ */
+export interface AgentTaskSession {
+    readonly taskId: string;
+    /** `null` once the outcome is reported, so nothing acts for the task afterwards. */
+    readonly secret: string | null;
+    readonly deadlineAt: string;
+    /** The question `questions_ask` asked; the turn that asked it ends as `needs_input`. */
+    readonly question?: {
+        readonly turnId: string;
+        readonly text: string;
+    };
+}
+export declare const agentTaskSessions: StateHandle<AgentTaskSession | null>;
+/** The live secret of `taskId` in this session, or `undefined` once reported or for another task. */
+export declare function taskSecret(taskId: string, state?: StateHandle<AgentTaskSession | null>): string | undefined;
+/** How a task ended, as the result route takes it. */
+export type TaskOutcome = {
+    readonly status: "completed";
+    readonly text: string;
+}
+/** The agent asked a person something; `text` is its question. */
+ | {
+    readonly status: "needs_input";
+    readonly text: string;
+} | {
+    readonly status: "failed";
+    readonly reason: "agent_failed";
+};
+/** The result route's body: text cut to {@link MAXIMUM_TASK_TEXT}, never inside a surrogate pair. */
+export declare function resultBody(outcome: TaskOutcome): Record<string, unknown>;
+export type CurrentTaskLookup = {
+    readonly status: "live";
+    readonly task: CurrentTask;
+}
+/** The secret matches no live task, or the workflow's user is inactive. */
+ | {
+    readonly status: "refused";
+};
+export type TaskReport = 
+/** The ontology made the task terminal with this outcome. */
+"accepted"
+/** The task was already terminal: the first report won. */
+ | "already_reported"
+/** The secret matches no live task. */
+ | "refused"
+/** The report could not be delivered before giving up; the task's deadline ends it. */
+ | "failed";
+/** The ontology answered a task call unexpectedly. Carries its status, never the secret. */
+export declare class AgentTaskError extends Error {
+    readonly status?: number | undefined;
+    readonly name = "AgentTaskError";
+    constructor(message: string, status?: number | undefined, options?: ErrorOptions);
+}
+/** The ontology's task routes, called as the deployment with the task's secret. */
+export declare function agentTasks(options?: {
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly log?: (message: string, detail: unknown) => void;
+}): {
+    /** The task the secret belongs to, while it is live. Other failures throw. */
+    current(secret: string): Promise<CurrentTaskLookup>;
+    /**
+     * Reports the outcome. Network failures, timeouts, 429 and 5xx retry with backoff for at most
+     * two minutes and never past the task's deadline, when the ontology times the task out itself.
+     */
+    report(secret: string, outcome: TaskOutcome, context: {
+        readonly taskId: string;
+        readonly deadlineAt: string;
+    }): Promise<TaskReport>;
+    /** Asks this deployment's task route to end the task's session. */
+    end(input: {
+        readonly taskId: string;
+        readonly sessionId: string;
+    }): Promise<void>;
+};
+export type AgentTasks = ReturnType<typeof agentTasks>;