@homeflare/seat-runtime 0.1.0

package/src/mcp-render.ts

@@ -0,0 +1,67 @@
+/**
+ * An MCP tool result as the text a model reads.
+ *
+ * ★ ALWAYS A STRING. A result is a list of content blocks (text, image, audio, a resource, a
+ *   link), and what goes into the model's context is one message. Text is passed through
+ *   verbatim, joined by newlines; everything else becomes a one-line marker naming what it was.
+ * ⛔ A BINARY BLOCK NEVER REACHES THE MODEL AS ITS BYTES. An image's base64 is tens of
+ *   kilobytes of context that says nothing to a text model and costs every later round; the
+ *   marker keeps its type and MIME type so the model knows something was there.
+ * ⚠️ AN EMPTY RESULT IS NOT AN EMPTY STRING. Some providers refuse a tool message with empty
+ *   content (not measured against cf-code), and a refused request ends the whole run over a
+ *   tool that merely had nothing to say.
+ */
+
+/** What the model reads for a tool that returned no content blocks. */
+export const EMPTY_RESULT = '(no content)';
+
+type Block = Readonly<Record<string, unknown>>;
+
+const isBlock = (value: unknown): value is Block => typeof value === 'object' && value !== null;
+const str = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
+
+/** One block. The shapes are MCP's `TextContent`, `ImageContent`, `AudioContent`, `ResourceLink`, `EmbeddedResource`. */
+function renderBlock(block: Block): string {
+  const type = str(block['type']) ?? 'unknown';
+  switch (type) {
+    case 'text':
+      return str(block['text']) ?? '';
+    case 'image':
+    case 'audio':
+      return `[${type}: ${str(block['mimeType']) ?? 'unknown type'}, not shown]`;
+    case 'resource_link':
+      return `[resource link: ${str(block['uri']) ?? 'no uri'}]`;
+    case 'resource': {
+      const resource = isBlock(block['resource']) ? block['resource'] : {};
+      // An embedded resource is either text (shown) or a base64 blob (not).
+      return str(resource['text']) ?? `[resource: ${str(resource['uri']) ?? 'no uri'}, not shown]`;
+    }
+    default:
+      return `[unsupported content block: ${type}]`;
+  }
+}
+
+/** The text of a `CallToolResult.content`. Anything that is not a block list is JSON, not dropped. */
+export function renderContent(content: unknown): string {
+  if (!Array.isArray(content)) {
+    return content === undefined ? EMPTY_RESULT : JSON.stringify(content);
+  }
+  const lines = content.map((block: unknown) =>
+    isBlock(block) ? renderBlock(block) : JSON.stringify(block),
+  );
+  return lines.length === 0 ? EMPTY_RESULT : lines.join('\n');
+}
+
+/**
+ * The text of a whole `callTool` result. ★ The `content` blocks are what MCP asks a server to
+ * always send; a server that sends only `structuredContent` (an `outputSchema` tool that skipped
+ * the text copy) would otherwise read as empty, so its JSON is shown instead. The legacy
+ * `toolResult` shape (the SDK's compatibility result) is read as content.
+ */
+export function renderResult(result: Readonly<Record<string, unknown>>): string {
+  const content = 'content' in result ? result['content'] : result['toolResult'];
+  if (Array.isArray(content) && content.length === 0 && result['structuredContent'] !== undefined) {
+    return JSON.stringify(result['structuredContent']);
+  }
+  return renderContent(content);
+}

package/src/mcp-tool.ts

@@ -0,0 +1,101 @@
+/**
+ * One MCP tool as an Effect AI dynamic tool: the server's own JSON Schema goes to the model,
+ * and the tool call the model sends back decodes without losing its arguments.
+ *
+ * ★ `Tool.dynamic` WITH THE SERVER'S JSON SCHEMA IS THE RIGHT SHAPE (its docs name MCP tools
+ *   discovered at runtime), and the model sees that schema verbatim.
+ * 🔴 BUT @effect/ai-openai-compat rc.115 CANNOT DECODE A TOOL CALL FOR IT. Measured 2026-09-29
+ *   (tests/seat-loop.test.ts, first run): the request goes out, and when the model's reply asks
+ *   for the tool, `transformToolCallParams` runs the OpenAI structured-output codec over the
+ *   tool's `parametersSchema` — `Schema.Unknown` in JSON-Schema mode — and fails the whole turn
+ *   with `UnsupportedSchemaError: Root JSON Schema must have type "object" and must not use
+ *   "anyOf"`. rc.118 fixed it upstream: it returns the raw params for a dynamic tool that has a
+ *   `jsonSchema`. The estate is pinned at rc.115 and rc.118 drops the `unstable/` import prefix,
+ *   so this file carries the workaround until the pin moves.
+ * ★ THE WORKAROUND: keep `jsonSchema` (what the model is sent, and what `Tool.getJsonSchema`
+ *   returns), and replace `parametersSchema` — what compat's codec and the Toolkit decode with —
+ *   by an object schema of the DECLARED property names, each `Unknown`, decoded to `Unknown`
+ *   with an ENCODE THAT IS FORBIDDEN. Every declared value passes through untouched and
+ *   `required` is honoured, so a missing argument fails as a tool result the model can read
+ *   instead of reaching the server.
+ * 🔴 WHY THE ENCODE IS FORBIDDEN. compat's `transformToolCallParams` (OpenAiLanguageModel.js)
+ *   decodes the model's params through the OpenAI structured-output codec and re-encodes them
+ *   with `parametersSchema`, falling back to the params AS SENT when either step fails. That
+ *   codec rewrites every optional property as nullable and reads `null` as ABSENT, so with a
+ *   plain object schema an explicit `null` on an optional argument was deleted before the call.
+ *   Measured 2026-09-29 (review of PR 328), end to end through `SeatModel` and `mcpToolkit` into
+ *   an Effect `McpServer`: `update_issue {id, assignee: null}` (null unassigns, omitted leaves
+ *   alone) reached the server as `{id}`, and the run ended 'done'. That normalisation exists for
+ *   the codec's own JSON Schema, and the model here was sent the server's, where `null` is a
+ *   value. Forbidding the encode makes the re-encode fail, so compat forwards the params as the
+ *   model sent them: `null` arrives as `null` (pinned in tests/mcp-arguments.test.ts).
+ * ⚠️ WHAT IT COSTS: a property the schema does not declare is DROPPED before the call
+ *   (Effect's decoder ignores excess keys; v4 has no "preserve"), so a server that declares
+ *   `additionalProperties: true` and relies on undeclared keys gets fewer than the model sent.
+ *   And a tool that declares no properties takes no arguments: `Tool.EmptyParams` is the only
+ *   root the codec accepts for it, and it rejects any key.
+ * ⛔ REMOVE THIS WHEN THE PIN REACHES rc.118 or later: build the tool from `Tool.dynamic` alone.
+ *   The clone below copies what `Tool`'s own `setParameters` copies (its prototype and own
+ *   fields), so it depends on Effect's tool object layout; the end-to-end test is what fails
+ *   first if a bump changes that.
+ */
+import type * as JsonSchema from 'effect/JsonSchema';
+import * as Schema from 'effect/Schema';
+import * as SchemaGetter from 'effect/SchemaGetter';
+import * as Tool from 'effect/unstable/ai/Tool';
+
+/** One dynamic tool per MCP tool: the server's JSON Schema in, text out, failures returned. */
+export type McpTool = Tool.Dynamic<
+  string,
+  {
+    readonly parameters: JsonSchema.JsonSchema;
+    readonly success: typeof Schema.String;
+    readonly failure: typeof Schema.String;
+    readonly failureMode: 'return';
+  }
+>;
+
+/** What `client.listTools()` gives for one tool, narrowed to what is used here. */
+export type McpToolSpec = {
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly inputSchema: JsonSchema.JsonSchema;
+};
+
+/** The workaround's `parametersSchema`: the declared property names, each passed through as-is, decode-only. */
+export function declaredParameters(inputSchema: JsonSchema.JsonSchema): Schema.Constraint {
+  const properties = inputSchema['properties'];
+  const names =
+    typeof properties === 'object' && properties !== null ? Object.keys(properties) : [];
+  if (names.length === 0) return Tool.EmptyParams;
+  const required = new Set(
+    Array.isArray(inputSchema['required']) ? (inputSchema['required'] as unknown[]) : [],
+  );
+  const declared = Schema.Struct(
+    Object.fromEntries(
+      names.map((name) => [
+        name,
+        required.has(name) ? Schema.Unknown : Schema.optional(Schema.Unknown),
+      ]),
+    ),
+  );
+  return declared.pipe(
+    Schema.decodeTo(Schema.Unknown, {
+      decode: SchemaGetter.passthrough(),
+      encode: SchemaGetter.forbiddenEncoding,
+    }),
+  );
+}
+
+export function mcpTool(spec: McpToolSpec): McpTool {
+  const dynamic = Tool.dynamic(spec.name, {
+    description: spec.description,
+    parameters: spec.inputSchema,
+    success: Schema.String,
+    failure: Schema.String,
+    failureMode: 'return',
+  });
+  return Object.assign(Object.create(Object.getPrototypeOf(dynamic)), dynamic, {
+    parametersSchema: declaredParameters(spec.inputSchema),
+  }) as McpTool;
+}

package/src/mcp-toolkit.ts

@@ -0,0 +1,183 @@
+/**
+ * An MCP server's tools as an Effect AI `Toolkit`, and its resources as two Effects, through
+ * the official MCP TypeScript SDK (`Client` over `StreamableHTTPClientTransport`).
+ *
+ * ★ THE SDK'S CLIENT IS THE CLIENT. Effect AI ships the SERVER half of MCP (`McpServer`,
+ *   `McpSchema`); no client (walked down 2026-09-29, docs/plans/2026-09-29-cf-seat-sdk-spike.md
+ *   open item 2). Wrapping the official client as dynamic tools is that plan's smallest option,
+ *   and the scout measured the pairing: list, call and resource read against an Effect
+ *   `McpServer` (pair115/mcp.ts).
+ * ★ EACH MCP TOOL IS A `Tool.dynamic` WITH THE SERVER'S OWN JSON SCHEMA (mcp-tool.ts). The schema
+ *   goes to the model as the server wrote it, and no Effect Schema is built from its types: the
+ *   only client-side check is that the declared `required` arguments are present, and the server
+ *   validates the rest and its complaint comes back to the model.
+ * ⚠️ A TOOL FAILURE IS THE MODEL'S TO SEE, NOT THE RUN'S TO DIE OF. Every tool is
+ *   `failureMode: 'return'`: an `isError` result, a JSON-RPC error (bad arguments, unknown
+ *   tool) and a call that never completed all come back to the model as the tool's result, so
+ *   it can correct itself or answer without the tool. MCP specifies errors-in-results for
+ *   exactly this. Connecting and listing are different: nothing works without them, so they
+ *   fail with `McpToolkitError`.
+ * ⚠️ THE TOOL LIST IS A SNAPSHOT taken at connect time; a server's `listChanged` notification is
+ *   not followed. Reconnect for a fresh list.
+ * ⛔ HEADERS ARE CREDENTIALS. They ride `requestInit` to the server and nowhere else: not in an
+ *   error, a span or a log (mcp-error.ts). Pass a bearer value as `Redacted` to keep it out of
+ *   an accidental print of the argument, as `SeatModel` does with the API key.
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+import type * as Toolkit from 'effect/unstable/ai/Toolkit';
+import {
+  DEFAULT_CONNECT_TIMEOUT_MS,
+  type McpHeaders,
+  connectAndBuild,
+  headerValues,
+  validateTimeout,
+} from './mcp-connect.ts';
+import { McpToolkitError, type Redact, redactor, serverLabel } from './mcp-error.ts';
+import { collect } from './mcp-pages.ts';
+import { type McpTools, toolset } from './mcp-toolset.ts';
+
+export type { McpTools } from './mcp-toolset.ts';
+
+export type McpResource = {
+  readonly uri: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly mimeType?: string | undefined;
+};
+
+/** One entry of a resource read: `text` for text, `blob` (base64) for binary. */
+export type McpResourceContent = {
+  readonly uri: string;
+  readonly mimeType?: string | undefined;
+  readonly text?: string | undefined;
+  readonly blob?: string | undefined;
+};
+
+export type McpToolkit = {
+  /** Every tool the server listed, with handlers that call it: hand this to `runRounds`. */
+  readonly toolkit: Toolkit.WithHandler<McpTools>;
+  /** The server's resources; empty when it does not advertise the resources capability. */
+  readonly listResources: Effect.Effect<ReadonlyArray<McpResource>, McpToolkitError>;
+  /** The contents of one resource; fails with `McpToolkitError` for an unknown URI. */
+  readonly readResource: (
+    uri: string,
+  ) => Effect.Effect<ReadonlyArray<McpResourceContent>, McpToolkitError>;
+};
+
+export type McpToolkitOptions = {
+  /**
+   * The budget for STARTING UP, in milliseconds; default 15 000. A finite number above 0 and at
+   * most 2 ** 31 - 1, or a `RangeError` defect before any request (mcp-connect.ts).
+   * It covers, each with the full budget:
+   *   - the WHOLE handshake: `initialize` and the `notifications/initialized` that follows it;
+   *   - every `tools/list` page read after it (a server holding one fails the call as
+   *     `McpToolkitError` with `operation: 'listTools'`).
+   * ⚠️ It is a budget PER REQUEST, not a total: a server that answers each of its (up to 100)
+   *   tool pages in just under the budget can still take that many budgets. Wrap the whole call
+   *   in `Effect.timeout` for a total.
+   * ⚠️ The SDK bounds only the `initialize` request (its default is 60 s) and leaves the
+   *   notification unbounded, so a server that answers `initialize` and then stalls would hold a
+   *   seat at startup indefinitely. Here the budget covers both, and the handshake and the
+   *   listing are interruptible, so a caller's `Effect.timeout` or a shutdown also ends them, and
+   *   either way the client is closed and nothing is left in your scope (mcp-connect.ts).
+   * ⚠️ NOT COVERED: `listResources`, `readResource` and tool calls, which are requests you make
+   *   after startup and keep the SDK's 60 s default per request. They are interruptible too.
+   */
+  readonly connectTimeoutMs?: number | undefined;
+};
+
+/** The two resource operations against a connected client; neither runs at connect time. */
+function resourcesOf(client: Client, server: string, redact: Redact) {
+  const listResources = Effect.suspend(() =>
+    // ★ A server that does not advertise resources is not asked: a strict one answers
+    //   "method not found", and "no resources" is the truthful reading of that.
+    client.getServerCapabilities()?.resources === undefined
+      ? Effect.succeed<ReadonlyArray<McpResource>>([])
+      : collect(
+          'listResources',
+          server,
+          async (cursor, signal) => {
+            const page = await client.listResources(cursor === undefined ? undefined : { cursor }, {
+              signal,
+            });
+            return {
+              items: page.resources.map((resource): McpResource => ({
+                uri: resource.uri,
+                name: resource.name,
+                description: resource.description,
+                mimeType: resource.mimeType,
+              })),
+              next: page.nextCursor,
+            };
+          },
+          redact,
+        ),
+  ).pipe(Effect.withSpan('seat.mcp.list_resources', { attributes: { 'server.address': server } }));
+
+  const readResource = (uri: string) =>
+    Effect.tryPromise({
+      try: async (signal): Promise<ReadonlyArray<McpResourceContent>> => {
+        const read = await client.readResource({ uri }, { signal });
+        return read.contents.map((entry) => ({
+          uri: entry.uri,
+          mimeType: entry.mimeType,
+          text: 'text' in entry ? entry.text : undefined,
+          blob: 'blob' in entry ? entry.blob : undefined,
+        }));
+      },
+      catch: (cause) => new McpToolkitError({ operation: 'readResource', server, cause, redact }),
+    }).pipe(
+      Effect.withSpan('seat.mcp.read_resource', {
+        attributes: { 'mcp.resource': uri, 'server.address': server },
+      }),
+    );
+
+  return { listResources, readResource };
+}
+
+/**
+ * Connect to a Streamable HTTP MCP server, list its tools, and return them as a toolkit.
+ * The connection lives as long as the surrounding `Scope`.
+ *
+ * ★ A FAILURE AT ANY POINT LEAVES THE CALLER'S SCOPE EMPTY: the handshake, the `tools/list`
+ *   (a JSON-RPC error, a page held past `connectTimeoutMs`) and building the toolkit all run
+ *   before the client's finalizer is registered, and each closes the client if it fails or is
+ *   interrupted (`connectAndBuild`, mcp-connect.ts). So `Effect.retry` around `mcpToolkit`
+ *   accumulates no clients, sessions or sockets.
+ */
+export function mcpToolkit(
+  url: string | URL,
+  headers?: McpHeaders,
+  options?: McpToolkitOptions,
+): Effect.Effect<McpToolkit, McpToolkitError, Scope.Scope> {
+  return Effect.gen(function* () {
+    const timeout = yield* validateTimeout(options?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
+    // ⚠️ Parsed INSIDE the Effect: `new URL` throws, and a throw at call time would skip the typed
+    //   error. The message never repeats the string: a URL is where a token may sit.
+    const target = yield* Effect.try({
+      try: () => new URL(url),
+      catch: () =>
+        new McpToolkitError({
+          operation: 'connect',
+          server: '(unparseable URL)',
+          cause: 'the URL did not parse',
+        }),
+    });
+    const server = serverLabel(target);
+    // ⛔ Every error and every failure text below goes through this: a server echoes its address,
+    //   a query value or a header value, and a fetch failure prints the address, query string and
+    //   all (mcp-error.ts).
+    const redact = redactor(target, headerValues(headers));
+
+    // The connection lives in the surrounding scope; it is registered there only once the whole
+    // toolkit below has been built (see the header of `mcpToolkit`).
+    return yield* connectAndBuild(target, headers, server, timeout, redact, (client) =>
+      Effect.gen(function* () {
+        const toolkit = yield* toolset(client, server, timeout, redact);
+        return { toolkit, ...resourcesOf(client, server, redact) };
+      }),
+    );
+  });
+}

package/src/mcp-toolset.ts

@@ -0,0 +1,91 @@
+/**
+ * An MCP server's tools as a ready-to-run Effect AI toolkit: list them (bounded by the startup
+ * budget), wrap each as a `Tool.dynamic` (mcp-tool.ts), and give each a handler that calls the
+ * server. Split from mcp-toolkit.ts so that `connectAndBuild` can run all of this BEFORE the
+ * client's finalizer is registered (mcp-connect.ts): listing can fail, and a failed listing must
+ * leave nothing in the caller's scope.
+ *
+ * ⚠️ A TOOL FAILURE IS THE MODEL'S TO SEE, NOT THE RUN'S TO DIE OF (see mcp-toolkit.ts). Every
+ *   failure below comes back as a string.
+ * ⛔ A FAILURE'S TEXT IS REDACTED, A SUCCESS'S IS NOT. What the model reads for an `isError`
+ *   result, a JSON-RPC error or a dropped call goes through `redact`: a server that rejects a
+ *   credential typically prints it ("bad credential Bearer ..."), and that text goes on to a
+ *   cloud model. Measured 2026-09-29 (review of PR 328, later round): an `isError` result that
+ *   echoed a query value and a bearer token delivered both to the model, while the same echo in
+ *   an `McpToolkitError` was already redacted. A SUCCESSFUL result is the tool's payload and is
+ *   delivered verbatim: rewriting it would corrupt legitimate data that happens to contain a
+ *   value, and a server that returns a credential as data is not a failure this can tell apart.
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import * as Effect from 'effect/Effect';
+import * as Toolkit from 'effect/unstable/ai/Toolkit';
+import { type McpToolkitError, type Redact, describeCause } from './mcp-error.ts';
+import { collect } from './mcp-pages.ts';
+import { renderResult } from './mcp-render.ts';
+import { type McpTool, mcpTool } from './mcp-tool.ts';
+
+export type McpTools = Readonly<Record<string, McpTool>>;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Everything the model can do wrong or the server can refuse comes back as a string. */
+const call = (client: Client, server: string, redact: Redact, name: string) => (params: unknown) =>
+  Effect.gen(function* () {
+    // The Toolkit's decode has already rejected a non-object (mcp-tool.ts), so this is the
+    // type guard the `unknown` argument needs and not a second line of defence.
+    if (!isRecord(params)) {
+      return yield* Effect.fail(`${name}: the arguments must be a JSON object`);
+    }
+    const result = yield* Effect.tryPromise({
+      try: (signal) => client.callTool({ name, arguments: params }, undefined, { signal }),
+      catch: (cause) => `MCP call to ${name} failed: ${redact(describeCause(cause))}`,
+    });
+    const text = renderResult(result);
+    // ⛔ Only a FAILURE's text is redacted: see the header.
+    return result.isError === true ? yield* Effect.fail(redact(text)) : text;
+  }).pipe(
+    Effect.withSpan('seat.mcp.call_tool', {
+      attributes: { 'mcp.tool': name, 'server.address': server },
+    }),
+  );
+
+/**
+ * List the server's tools and return them as a toolkit with handlers.
+ * ★ A server that does not advertise tools is not asked for them: a resources-only server
+ *   answers `tools/list` with "method not found", and one such server would otherwise make the
+ *   whole connection unusable for its resources.
+ * ★ `timeout` is the startup budget: without it the SDK waits its 60 s per page.
+ */
+export const toolset = (
+  client: Client,
+  server: string,
+  timeout: number,
+  redact: Redact,
+): Effect.Effect<Toolkit.WithHandler<McpTools>, McpToolkitError> =>
+  Effect.gen(function* () {
+    const listed =
+      client.getServerCapabilities()?.tools === undefined
+        ? []
+        : yield* collect(
+            'listTools',
+            server,
+            async (cursor, signal) => {
+              const page = await client.listTools(cursor === undefined ? undefined : { cursor }, {
+                signal,
+                timeout,
+              });
+              return { items: page.tools, next: page.nextCursor };
+            },
+            redact,
+          );
+    const tools = listed.map((tool) =>
+      mcpTool({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }),
+    );
+    const definition = Toolkit.make(...tools);
+    const handlers = Object.fromEntries(
+      tools.map((tool) => [tool.name, call(client, server, redact, tool.name)]),
+    );
+    const context = yield* definition.toHandlers(handlers);
+    return yield* definition.pipe(Effect.provideContext(context));
+  });

package/src/rounds.ts

@@ -0,0 +1,211 @@
+/**
+ * The one round loop every seat shares: model turn, tool results, model turn, until the model
+ * stops asking for tools or the cap fires — and a cap that fires is followed by ONE more turn
+ * with the toolkit taken away, so a run ends with an answer instead of a truncated transcript.
+ *
+ * ★ WHAT THE SDK DOES AND DOES NOT DO. `Chat.generateText` with a toolkit resolves the tool
+ *   calls of ONE model turn and returns; it never re-prompts, and Effect AI ships no
+ *   `maxRounds` or `stopWhen` (grep of LanguageModel.d.ts and Chat.d.ts, 2026-09-29). The
+ *   documented multi-round agent is a `while` over `session.generateText({ prompt: [], toolkit })`
+ *   (compat's ai-docs, 30_chat.ts). This file is that `while`, once, with the cap.
+ * ⛔ THE CAP IS HARD AND FINITE. `maxRounds` must be a positive integer: `Infinity`, `0`, a
+ *   fraction or `NaN` is a programming error and dies with a `RangeError` before any model
+ *   call, because a loop a bad config can un-cap is a loop that spends until something else
+ *   stops it (LiteLLM's budget hit the claude2 fleet that way, 2026-09-28).
+ * ⚠️ THE FORCED TURN SENDS NO TOOLS. No toolkit, and `toolChoice: 'none'` stated anyway: the SDK
+ *   already defaults `toolChoice` to `'none'` for a call with no toolkit (LanguageModel.js,
+ *   `providerOptions`, measured by mutation 2026-09-29: dropping the option changed no test), so
+ *   it is kept for what it says and for the `toolChoice` attribute on the turn's span. compat
+ *   then sends neither `tools` nor `tool_choice` (prepareTools returns both undefined for an
+ *   empty tool list, rc.115), because an OpenAI-shaped API refuses a `tool_choice` with no
+ *   `tools`. The history still carries the earlier tool calls and results, and cf-code accepted
+ *   exactly that: one live call through CT100's LiteLLM (:4100), 2026-09-29, a history of
+ *   system, user, assistant tool call and tool result, no `tools`, `toolChoice: 'none'`, came
+ *   back `finishReason: 'stop'` with text and no tool call. One sample, one alias.
+ * ⚠️ `capped` MEANS THE MODEL STILL WANTED TOOLS after `maxRounds` tool rounds. A model that
+ *   answers on round `maxRounds` exactly is `capped: false`: the cap did not fire.
+ * 🔴 THE FORCED TURN CAN BE REFUSED, AND THEN THE RUN DOES NOT DIE OF IT. A provider that asks for
+ *   a tool although none was offered (a gateway that adds a dummy tool for a history full of
+ *   tool calls does exactly that) answers a turn the SDK cannot use, and the SDK says so with one
+ *   of TWO `AiError` reasons, depending on WHO rejects the tool call:
+ *   - `ToolNotFoundError`: @effect/ai-openai-compat (`SeatModel`'s provider) rejects it first,
+ *     while it maps the reply (`transformToolCallParams`: "Tool ... not found. Available tools:
+ *     none"). Measured 2026-09-29 (review of PR 328, of the round 2 fix), `SeatModel` against a loopback
+ *     LiteLLM stand-in that answered every call with a tool call: 3 model calls, tools offered
+ *     [true, true, false], then the whole run failed with every round already spent. Round 2's
+ *     fix caught only the reason below and so did nothing for this provider.
+ *   - `InvalidOutputError` raised by `LanguageModel` (module `LanguageModel`): the SDK's own decode
+ *     of the provider's parts ("Expected ... text | reasoning ..."), reached by a provider that hands
+ *     the SDK a tool-call part itself (the scripted model in tests/fake-model.ts). The same reason
+ *     raised by `OpenAiClient` (an empty, truncated or non-completion body, a dropped stream) is NOT
+ *     a refusal and fails the run (tests/seat-broken-forced.test.ts).
+ *   Either is caught: the result is `capped` and `unanswered`, its `response` is the LAST TOOL
+ *   ROUND's (whose calls did run), `rounds` stays `maxRounds`, and a warning, a span error and
+ *   `seat_rounds_unanswered_total` say what happened. Any OTHER failure of the forced turn
+ *   (network, rate limit, a handler) still fails the run.
+ */
+import * as Effect from 'effect/Effect';
+import * as Metric from 'effect/Metric';
+import type * as Chat from 'effect/unstable/ai/Chat';
+import type * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as Prompt from 'effect/unstable/ai/Prompt';
+import type * as Tool from 'effect/unstable/ai/Tool';
+import type { AiError } from 'effect/unstable/ai/AiError';
+import type * as Toolkit from 'effect/unstable/ai/Toolkit';
+
+/**
+ * A tool call the forced turn cannot use. `ToolNotFoundError` is compat's own rejection (its reply
+ * mapping); `InvalidOutputError` counts ONLY when `LanguageModel` raised it (the SDK's decode of a
+ * provider that handed it a tool-call part). compat raises the same reason, from `OpenAiClient`, for
+ * a 200 with an empty, non-JSON, truncated or non-completion body and for a body stream that dies
+ * mid-read: those are gateway or network failures and must fail the run, not read as a refusal
+ * (review of PR 328, round 4; tests/seat-broken-forced.test.ts).
+ */
+const isToolRefusal = (error: AiError): boolean =>
+  error.reason._tag === 'ToolNotFoundError' ||
+  (error.reason._tag === 'InvalidOutputError' && error.module === 'LanguageModel');
+
+/** Every model turn, forced or not. */
+const roundsTotal = Metric.counter('seat_rounds_total', {
+  description:
+    'Model turns taken by runRounds that returned; a refused forced final turn is not counted.',
+});
+/** Runs whose cap fired: the interesting number, because each one is an agent that did not finish. */
+const roundsCapped = Metric.counter('seat_rounds_capped_total', {
+  description: 'runRounds runs that hit maxRounds and were given a forced final turn.',
+});
+
+/** Runs whose forced final turn was refused: the model still asked for a tool. */
+const roundsUnanswered = Metric.counter('seat_rounds_unanswered_total', {
+  description: 'runRounds runs whose forced final turn came back as a tool call, not an answer.',
+});
+
+/**
+ * A turn's response: with the toolkit, or the forced one without.
+ * ⚠️ The two modes differ because the SDK's own types do: a call with a toolkit answers
+ *   `'opaque'` tool parameters, a call without one answers the default `'decoded'`.
+ */
+type Response<Tools extends Record<string, Tool.Any>> =
+  | LanguageModel.GenerateTextResponse<Tools, 'opaque'>
+  | LanguageModel.GenerateTextResponse<{}, 'decoded'>;
+
+/** One model turn, as `onRound` and the result see it. A refused forced final turn is not reported. */
+export type Round<Tools extends Record<string, Tool.Any>> = {
+  /** 1-based. The forced final turn, when there is one, is `maxRounds + 1`. */
+  readonly round: number;
+  /** True only for the forced final turn: no toolkit, `toolChoice: 'none'`. */
+  readonly forced: boolean;
+  readonly response: Response<Tools>;
+};
+
+export type RoundsOptions<Tools extends Record<string, Tool.Any>> = {
+  /**
+   * The conversation, already holding the opening prompt (`Chat.fromPrompt`) or a resumed
+   * history that ends in a user message or tool results. Every round sends an EMPTY prompt:
+   * `Chat` appends the model's turn and its tool results to `history` itself.
+   */
+  readonly chat: Chat.Chat;
+  /**
+   * Tools WITH their handlers. A `Toolkit.make(...)` is an Effect that needs its handlers from
+   * context: `yield*` it where they are provided, and pass the result. (Typing it as the
+   * Effect would hide its requirements, which `generateText` itself cannot track either.)
+   */
+  readonly toolkit: Toolkit.WithHandler<Tools>;
+  /** The most tool rounds allowed. A positive integer; see the header. */
+  readonly maxRounds: number;
+  /** After every model turn, the forced one included. Runs inside that turn's span. */
+  readonly onRound?: ((round: Round<Tools>) => Effect.Effect<void>) | undefined;
+};
+
+export type RoundsResult<Tools extends Record<string, Tool.Any>> = {
+  /** The last model turn: the answer, or the forced final turn when the cap fired. */
+  readonly response: Response<Tools>;
+  /** Model turns that returned, the forced one included when it did. */
+  readonly rounds: number;
+  /** The cap fired and `response` is the forced final turn (or see `unanswered`). */
+  readonly capped: boolean;
+  /**
+   * The forced turn was refused (a provider that still asks for a tool) and `response` is the
+   * last TOOL round's: it holds no answer, and its tool calls ran. Only ever true with `capped`;
+   * `rounds` then counts the turns that returned, so it is `maxRounds`. See the header.
+   */
+  readonly unanswered: boolean;
+};
+
+/**
+ * Run the loop. Fails with whatever a model turn fails with (`AiError`, a tool handler's own
+ * failure); nothing is retried here — the caller wraps `Effect.retry` where it wants one.
+ */
+export function runRounds<Tools extends Record<string, Tool.Any>>(
+  options: RoundsOptions<Tools>,
+): Effect.Effect<
+  RoundsResult<Tools>,
+  LanguageModel.ExtractError<{ readonly toolkit: Toolkit.WithHandler<Tools> }>,
+  | LanguageModel.LanguageModel
+  | LanguageModel.ExtractServices<{ readonly toolkit: Toolkit.WithHandler<Tools> }>
+> {
+  const { chat, toolkit, maxRounds, onRound } = options;
+  return Effect.gen(function* () {
+    if (!Number.isInteger(maxRounds) || maxRounds < 1) {
+      return yield* Effect.die(
+        new RangeError(`runRounds: maxRounds must be a positive integer, got ${String(maxRounds)}`),
+      );
+    }
+    const finish = (round: number, forced: boolean) =>
+      Effect.fnUntraced(function* (response: Response<Tools>) {
+        yield* Metric.update(roundsTotal, 1);
+        yield* Effect.annotateCurrentSpan({ 'seat.tool_calls': response.toolCalls.length });
+        if (onRound !== undefined) yield* onRound({ round, forced, response });
+        return response;
+      });
+    const span = (round: number, forced: boolean) =>
+      Effect.withSpan('seat.round', {
+        attributes: { 'seat.round': round, 'seat.round.forced': forced },
+      });
+
+    const turn = (round: number) =>
+      chat
+        .generateText({ prompt: Prompt.empty, toolkit })
+        .pipe(Effect.flatMap(finish(round, false)), span(round, false));
+
+    let round = 1;
+    let response: Response<Tools> = yield* turn(round);
+    // ★ The exit test is the model's: no tool calls means it has answered.
+    while (response.toolCalls.length > 0 && round < maxRounds) {
+      round += 1;
+      response = yield* turn(round);
+    }
+    if (response.toolCalls.length === 0) {
+      return { response, rounds: round, capped: false, unanswered: false };
+    }
+
+    yield* Metric.update(roundsCapped, 1);
+    yield* Effect.logWarning('seat round cap reached; forcing a final turn without tools', {
+      maxRounds,
+    });
+    const forcedRound = maxRounds + 1;
+    /** The forced turn came back as a tool call: counted and logged, and the run goes on. */
+    const refused = () =>
+      Effect.as(
+        Effect.all([
+          Metric.update(roundsUnanswered, 1),
+          Effect.logWarning('seat forced final turn refused: the model still asked for a tool', {
+            maxRounds,
+          }),
+        ]),
+        undefined,
+      );
+    const forced = yield* chat.generateText({ prompt: Prompt.empty, toolChoice: 'none' }).pipe(
+      Effect.flatMap(finish(forcedRound, true)),
+      span(forcedRound, true),
+      // ⚠️ Only a tool call nobody offered: see the header for who raises which. Every other AiError
+      //   (a dropped connection, an empty or truncated body, a rate limit) still fails the run.
+      Effect.catchTag('AiError', (error) =>
+        isToolRefusal(error) ? refused() : Effect.fail(error),
+      ),
+    );
+    return forced === undefined
+      ? { response, rounds: maxRounds, capped: true, unanswered: true }
+      : { response: forced, rounds: forcedRound, capped: true, unanswered: false };
+  });
+}