One prompt, many child coding agents, each in its own process. A child runs

under a harness — `opencode` today — and the CLI reports what every one of them

did:

did.

```sh

openagents delegate "Add a regression test for the retry path, then say done" \

  --agents 3 --concurrency 2 \

  --child-model vertex-express/gemini-3.7-flash \

  --child-config ~/.config/openagents/delegate.json \

  --child-approve

Inside `openagents coder`, delegation is a tool the model calls, so you ask for

it in the conversation and nothing else is required:

```text

> split this three ways: each agent surveys one package for dead exports

```

`--agents` is how many children run the prompt and `--concurrency` is how many

run at once; the rest queue, so a fan-out of thirty does not become thirty

processes. `--child-approve` lets a child use its tools without asking, which a

child needs because there is nobody to ask. Add `--json` for the task records

and outcomes as data. The exit code is non-zero when any child did not finish.

The model calls `delegate`, the interface lists each child with the tool it is

running, its tool and token counts, and its result, and `ctrl+x` stops every

running child. `/delegate [<n>x] <prompt>` still works when you want to start

children yourself without spending a turn.

Children run on the session's own thread grant, so there is no child model to

choose and no provider credential to install. The CLI holds the grant in the

parent process, opens a loopback gateway on `127.0.0.1`, and points the child

harness at it; the child never receives the grant token, and its spending is

the thread's spending, under the same server-side budget.

The same fleet is available inside the terminal session. Start `openagents

coder` with `--child-model` and type `/delegate [<n>x] <prompt>`:

The children need the harness itself on `PATH`:

```sh

openagents coder --child-model vertex-express/gemini-3.7-flash \

  --child-config ~/.config/openagents/delegate.json --child-approve

npm i -g opencode-ai

```

```text

/delegate 4x survey the package for dead exports

Headless, the same fleet runs without a session:

```sh

openagents delegate "Add a regression test for the retry path, then say done" \

  --agents 3 --concurrency 2

```

Delegating does not spend a chat turn and does not block the next prompt. The

interface lists each child, what tool it is running, its tool and token counts,

and its result, and `ctrl+x` stops every running child. Each child's raw

harness transcript is kept as JSONL under

`$TMPDIR/openagents-coder-delegations`.

`--agents` is how many children run the prompt and `--concurrency` is how many

run at once; the rest queue, so a fan-out of thirty does not become thirty

processes. Add `--json` for the task records and outcomes as data. The exit code

is non-zero when any child did not finish. Each child's raw harness transcript

is kept as JSONL under `$TMPDIR/openagents-coder-delegations`.

When a child fails, the CLI reports what the child reported — the harness error

and its reference, the provider or proxy refusal with its status, a model the

harness does not have, or a missing executable — rather than an exit code.

The child model has no default, because a child spends money under a provider

account. `--child-model`, `--child-command`, and `--child-config` fall back to

To run children on a provider of your own instead of the thread grant, name it:

`--child-model`, `--child-command`, and `--child-config` fall back to

`OPENAGENTS_DELEGATE_MODEL`, `OPENAGENTS_DELEGATE_COMMAND`, and

`OPENAGENTS_DELEGATE_CONFIG`. The CLI never reads or stores a provider

credential: `--child-config` names a harness configuration file, which the CLI

passes to the child as `OPENCODE_CONFIG` and nothing else.

passes to the child as `OPENCODE_CONFIG` and nothing else. A child approves its

own tool use, because a delegated child has nobody to ask; `--child-ask` stops

it at its first edit for a dry run.

## Manage issues

{

  "name": "@openagentsinc/cli",

  "version": "0.3.2",

  "version": "0.3.3",

  "private": false,

  "description": "Effect TypeScript command-line client for OpenAgents repositories",

  "keywords": [

} from "./api-passthrough.js";

import { ApiTransport } from "./api-transport.js";

import { BrowserLauncher } from "./browser-launcher.js";

import type { ChildGrant } from "./coder-child-gateway.js";

import { startChildGateway } from "./coder-child-gateway.js";

import { writeChildHarnessConfig } from "./coder-child-config.js";

import type { DelegationOutcome } from "./coder-delegate.js";

import { DelegateFleet, describePrompt, OpencodeHarness } from "./coder-delegate.js";

import { fleetPlainLines } from "./coder-fleet.js";

import { runCoderUi } from "./coder-ui.js";

import { backendIds } from "./coder-backends.js";

import { openThread, ThreadUnavailable } from "./coder-thread.js";

import { delegateTool } from "./coder-tools.js";

import { describeWorkspace } from "./coder-workspace.js";

import { ComputerClient } from "./computer-client.js";

import { ComputerUp } from "./computer-up.js";

/**

 * Delegation flags, shared by `coder` and `delegate`.

 *

 * The child model is what turns delegation on. There is no default: a child

 * spends money under a provider account, and a console that silently picked a

 * model would spend it fifteen times over on a prompt the reader thought was

 * going nowhere. Each flag falls back to an environment variable so a fleet can

 * be configured once for a shell rather than typed on every launch.

 * None of them is required. Children run on the session's own thread grant

 * through a loopback gateway, which is what makes delegation work in a fresh

 * install with nothing configured: the earlier design demanded a child model

 * and a provider credential of the reader's own, so the fleet was off by

 * default and asking for one got a refusal. These flags are for the case where

 * somebody wants children on a different provider than the session.

 */

const childModelFlag = Flag.string("child-model").pipe(

  Flag.optional,

  Flag.withDescription(

    "The model delegated children run, as `provider/model`. Defaults to " +

      "OPENAGENTS_DELEGATE_MODEL. Delegation is unavailable without one",

    "Run children on this model instead of the session's own, as `provider/model`. " +

      "Defaults to OPENAGENTS_DELEGATE_MODEL, and to the session's thread grant when " +

      "neither is set",

  ),

);

const childCommandFlag = Flag.string("child-command").pipe(

      "provider credential reaches a child without being stored by the CLI",

  ),

);

const childApproveFlag = Flag.boolean("child-approve").pipe(

const childAskFlag = Flag.boolean("child-ask").pipe(

  Flag.withDescription(

    "Let children use their tools without asking. A delegated child has nobody to " +

      "ask, so a child that must edit files needs this",

    "Make children ask before using a tool. A delegated child has nobody to ask, so " +

      "this stops it at its first edit; it exists for a dry run over a directory you " +

      "do not want touched",

  ),

);

const concurrencyFlag = Flag.integer("concurrency").pipe(

  Flag.withDescription("How many children may run at once. The rest queue"),

);

/** Delegation and whatever has to be torn down with it. */

interface DelegationSetup {

  readonly delegation: CoderDelegation;

  /** Stops the child gateway and removes the generated harness config. */

  close(): Promise<void>;

}

/**

 * Assemble delegation, or nothing when no child model was named.

 * Assemble delegation.

 *

 * Returning undefined rather than throwing is what lets `coder` open without a

 * child model and say so when `/delegate` is typed, instead of refusing to

 * start over a feature the reader may not use.

 * Three ways a child gets a model, in order: a model named on the command line

 * or in the environment, with the reader's own harness config; the session's

 * thread grant, lent to children through a loopback gateway; or nothing, which

 * is only reached with no credential and no flag, and is what makes `/delegate`

 * say so instead of failing later.

 */

function buildDelegation(options: {

async function buildDelegation(options: {

  readonly model: string | undefined;

  readonly command: string | undefined;

  readonly configPath: string | undefined;

  readonly autoApprove: boolean;

  readonly concurrency: number;

  readonly cwd: string;

}): CoderDelegation | undefined {

  const model = options.model ?? process.env["OPENAGENTS_DELEGATE_MODEL"];

  if (model === undefined || model.trim().length === 0) return undefined;

  /** The session's grant, when it has one. Children spend it by default. */

  readonly grant: ChildGrant | undefined;

}): Promise<DelegationSetup | undefined> {

  const named = options.model ?? process.env["OPENAGENTS_DELEGATE_MODEL"];

  const command = options.command ?? process.env["OPENAGENTS_DELEGATE_COMMAND"];

  const namedConfig = options.configPath ?? process.env["OPENAGENTS_DELEGATE_CONFIG"];

  let model: string;

  let configPath: string | undefined;

  let close: () => Promise<void>;

  if (named !== undefined && named.trim().length > 0) {

    model = named;

    configPath = namedConfig;

    close = () => Promise.resolve();

  } else if (options.grant !== undefined) {

    const gateway = await startChildGateway(options.grant);

    const harnessConfig = writeChildHarnessConfig({

      baseUrl: gateway.baseUrl,

      model: options.grant.model,

    });

    model = gateway.modelId;

    configPath = harnessConfig.path;

    close = async () => {

      await gateway.close();

      harnessConfig.remove();

    };

  } else {

    return undefined;

  }

  const harness = new OpencodeHarness({

    model,

    command: options.command ?? process.env["OPENAGENTS_DELEGATE_COMMAND"],

    configPath: options.configPath ?? process.env["OPENAGENTS_DELEGATE_CONFIG"],

    command,

    configPath,

    autoApprove: options.autoApprove,

  });

  const registry = new CoderTaskRegistry();

    maxConcurrent: Math.max(1, options.concurrency),

    cwd: options.cwd,

  });

  return { registry, fleet, label: `${harness.agent} (${model})` };

  return {

    delegation: { registry, fleet, label: `${harness.agent} (${model})` },

    close,

  };

}

const coderCommand = Command.make(

    childModel: childModelFlag,

    childCommand: childCommandFlag,

    childConfig: childConfigFlag,

    childApprove: childApproveFlag,

    childAsk: childAskFlag,

    concurrency: concurrencyFlag,

  },

  ({

    childModel,

    childCommand,

    childConfig,

    childApprove,

    childAsk,

    concurrency,

  }) =>

    Effect.gen(function* () {

        : undefined;

      const source = thread ?? new DummyReplySource();

      const delegation = buildDelegation({

        model: Option.getOrUndefined(childModel),

        command: Option.getOrUndefined(childCommand),

        configPath: Option.getOrUndefined(childConfig),

        autoApprove: childApprove,

        concurrency,

        cwd: process.cwd(),

      });

      const setup = yield* Effect.promise(() =>

        buildDelegation({

          model: Option.getOrUndefined(childModel),

          command: Option.getOrUndefined(childCommand),

          configPath: Option.getOrUndefined(childConfig),

          autoApprove: !childAsk,

          concurrency,

          cwd: process.cwd(),

          grant: thread?.childGrant,

        }),

      );

      const session = new CoderSession(

        source,

        workspace.repository,

        workspace.branch,

        setup?.delegation,

      );

      const session = new CoderSession(source, workspace.repository, workspace.branch, delegation);

      // The model is told what it can do rather than the reader being asked to

      // remember a slash command. A turn that needs three agents asks for them

      // mid-sentence, and `/delegate` stays as the way to launch a fan-out

      // without spending a turn to ask for one.

      if (thread !== undefined && setup !== undefined) {

        thread.useTools([delegateTool(setup.delegation)]);

      }

      if (Option.isNone(stored) && !offline) {

        session.notice(

          // session nobody is in. A process killed outright still leaves it to

          // the server's expiry reap.

          if (thread !== undefined) await thread.revoke();

          if (setup !== undefined) await setup.close();

        }

      });

    }),

).pipe(

  Command.withDescription(

    "Open a terminal coding session on a thread of its own. Replies come from the thread's grant through the inference proxy, so nothing typed here reaches /chat; --offline answers from a built-in stand-in instead. With --child-model, `/delegate [<n>x] <prompt>` runs child coding agents and the interface shows the fleet",

    "Open a terminal coding session on a thread of its own. Replies come from the thread's grant through the inference proxy, so nothing typed here reaches /chat; --offline answers from a built-in stand-in instead. The session can delegate: ask it to split work and it runs child coding agents on the same grant, or launch a fan-out yourself with `/delegate [<n>x] <prompt>`, and the interface shows the fleet",

  ),

);

    childModel: childModelFlag,

    childCommand: childCommandFlag,

    childConfig: childConfigFlag,

    childApprove: childApproveFlag,

    childAsk: childAskFlag,

    concurrency: concurrencyFlag,

  },

  ({

    childModel,

    childCommand,

    childConfig,

    childApprove,

    childAsk,

    concurrency,

  }) =>

    Effect.gen(function* () {

      const flags = yield* rootCommand;

      const cwd = Option.getOrUndefined(dir) ?? process.cwd();

      const delegation = buildDelegation({

        model: Option.getOrUndefined(childModel),

        command: Option.getOrUndefined(childCommand),

        configPath: Option.getOrUndefined(childConfig),

        autoApprove: childApprove,

        concurrency,

        cwd,

      });

      const endpoint = yield* resolveApiEndpoint(endpointOverrides(flags));

      const named = Option.getOrUndefined(childModel) ?? process.env["OPENAGENTS_DELEGATE_MODEL"];

      // Children spend a thread the same way the interactive session does, so

      // this command opens one rather than demanding a provider of its own. It

      // is skipped when a child model was named, because then the reader is

      // paying somebody else and a thread would be opened and never spent.

      const stored =

        named === undefined

          ? yield* findToken(endpoint.origin).pipe(

              Effect.catchTag("OpenAgentsCli.CredentialPersistenceUnavailable", () =>

                Effect.succeed(Option.none()),

              ),

            )

          : Option.none();

      const thread = Option.isSome(stored)

        ? yield* Effect.tryPromise({

            try: () =>

              openThread({

                origin: endpoint.origin,

                token: Redacted.value(stored.value.token),

                objective: `openagents delegate: ${describePrompt(prompt)}`,

              }),

            catch: (cause) => coderRefusal(endpoint.origin, cause),

          })

        : undefined;

      if (delegation === undefined) {

      const setup = yield* Effect.promise(() =>

        buildDelegation({

          model: Option.getOrUndefined(childModel),

          command: Option.getOrUndefined(childCommand),

          configPath: Option.getOrUndefined(childConfig),

          autoApprove: !childAsk,

          concurrency,

          cwd,

          grant: thread?.childGrant,

        }),

      );

      if (setup === undefined) {

        return yield* new InputError({

          message:

            "No child model. Pass --child-model provider/model or set " +

            "OPENAGENTS_DELEGATE_MODEL.",

            "Nothing to run children on. Sign in with `openagents auth login --scope " +

            "chat:account` so children can spend a thread, or pass --child-model " +

            "provider/model to run them on a provider of your own.",

        });

      }

      const delegation = setup.delegation;

      const count = Math.max(1, agents);

      const label = Option.getOrUndefined(description) ?? describePrompt(prompt);

          process.off("SIGTERM", onSignal);

          process.off("exit", onSignal);

          unsubscribe();

          await setup.close();

          // The thread's slot goes back even on the failure path: an account

          // holds eight, and a script that delegates in a loop would otherwise

          // be refused on its ninth run.

          if (thread !== undefined) await thread.revoke();

        }

      });

    }),

).pipe(

  Command.withDescription(

    "Run one prompt on many child coding agents at once and report each result",

    "Run one prompt on many child coding agents at once and report each result. Children run on a thread of their own by default, so this needs no provider credential",

  ),

);

/**

 * The harness config that points children at this session's gateway.

 *

 * opencode reads its provider list from a config file named by

 * `OPENCODE_CONFIG`, so lending a session's grant to children means writing one

 * provider entry whose base URL is the loopback gateway. Written per session

 * into a private directory rather than into the reader's own

 * `~/.config/opencode`: the port changes every launch, two sessions must not

 * fight over one file, and nothing here should survive the process that needs

 * it.

 *

 * The file carries no credential. The gateway holds the grant, and the key

 * below exists only because an OpenAI-compatible client refuses to send a

 * request without one.

 */

import { mkdtempSync, rmSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { join } from "node:path";

import { CHILD_PROVIDER } from "./coder-child-gateway.js";

/** The config body, as a value, so a test can read it without a file. */

export function childHarnessConfig(options: {

  readonly baseUrl: string;

  readonly model: string;

}): Record<string, unknown> {

  return {

    $schema: "https://opencode.ai/config.json",

    provider: {

      [CHILD_PROVIDER]: {

        npm: "@ai-sdk/openai-compatible",

        name: "OpenAgents",

        options: {

          baseURL: options.baseUrl,

          // The gateway authenticates with the thread's grant and ignores

          // this, but a client that has no key at all will not send a request.

          apiKey: "openagents-thread-grant",

        },

        models: {

          [options.model]: { name: options.model, tool_call: true },

        },

      },

    },

  };

}

export interface ChildHarnessFile {

  readonly path: string;

  remove(): void;

}

/** Write the config to a private directory and hand back its path. */

export function writeChildHarnessConfig(options: {

  readonly baseUrl: string;

  readonly model: string;

}): ChildHarnessFile {

  const directory = mkdtempSync(join(tmpdir(), "openagents-child-"));

  const path = join(directory, "opencode.json");

  writeFileSync(path, `${JSON.stringify(childHarnessConfig(options), undefined, 2)}\n`, {

    mode: 0o600,

  });

  return {

    path,

    remove: () => {

      rmSync(directory, { recursive: true, force: true });

    },

  };

}

/**

 * A local OpenAI-compatible endpoint that lends the session's thread grant to

 * child coding agents.

 *

 * Delegation used to require the reader to name a child model and to hold a

 * provider credential of their own, which meant the fleet was off by default

 * and `/delegate` in a fresh session did nothing. That was backwards: the

 * session already holds a grant the server minted for it, the grant is already

 * metered against the thread's own budget, and a child is the same kind of

 * spend as a reply. So children run on the session's grant, and delegation

 * needs no flags, no key, and no second account.

 *

 * A harness cannot talk to `POST /api/inference/proxy` directly, for two

 * reasons:

 *

 * - **Path.** An OpenAI-compatible client appends `/chat/completions` to its

 *   base URL, and the proxy is one fixed path that answers nothing else.

 * - **Tool history.** The proxy maps a `tool` message to a

 *   `function_call_output` item and sends it *alone*, which the provider

 *   refuses without the `function_call` that preceded it — and the response id

 *   that would link them is never given to a client. A coding agent calls a

 *   tool on nearly every step, so the second step of every child would fail.

 *   This gateway therefore flattens a tool exchange into plain turns: the

 *   assistant's call becomes assistant text naming the call, and the result

 *   becomes a user turn carrying the output. The harness keeps its own state

 *   machine and only needs the next call from the model, so a flattened history

 *   costs prompt-shape fidelity and nothing else.

 *

 * The grant never reaches the harness: it is held here, the child is told only

 * a loopback URL, and the placeholder key it sends back is ignored. That is why

 * the gateway binds to `127.0.0.1` and to a port the operating system picks —

 * anything on the box could otherwise spend the thread's budget, and a fixed

 * port would collide between two sessions.

 */

import { createServer } from "node:http";

import type { AddressInfo } from "node:net";

import { Redacted } from "effect";

/** What the child gateway needs in order to spend a thread's grant. */

export interface ChildGrant {

  /** The proxy URL the grant was minted for. */

  readonly proxyUrl: string;

  readonly token: Redacted.Redacted<string>;

  /** The model the grant pins. A request body cannot select another. */

  readonly model: string;

}

/** One chat-completions message as a harness sends it. */

interface ClientMessage {

  readonly role?: unknown;

  readonly content?: unknown;

  readonly tool_calls?: unknown;

  readonly tool_call_id?: unknown;

}

/** A turn the proxy accepts: a role and text, and nothing else. */

interface FlatMessage {

  readonly role: "system" | "user" | "assistant";

  readonly content: string;

}

/**

 * Flatten a harness's message list into turns the proxy accepts.

 *

 * Exported for the tests, which is the only way to check the mapping without

 * standing up a server and a child.

 */

export function flattenForProxy(messages: ReadonlyArray<unknown>): ReadonlyArray<FlatMessage> {

  const flat: FlatMessage[] = [];

  for (const raw of messages) {

    if (typeof raw !== "object" || raw === null) continue;

    const message = raw as ClientMessage;

    const text = textOf(message.content);

    const role = typeof message.role === "string" ? message.role : "user";

    if (role === "tool") {

      const id = typeof message.tool_call_id === "string" ? message.tool_call_id : "";

      // A result is put on a user turn because that is the only role the proxy

      // will carry text on that the model has not already spoken.

      flat.push({ role: "user", content: `[tool result${id === "" ? "" : ` ${id}`}]\n${text}` });

      continue;

    }

    const calls = describeCalls(message.tool_calls);

    if (role === "assistant" && calls !== undefined) {

      flat.push({ role: "assistant", content: `${text}\n[tool call]\n${calls}`.trim() });

      continue;

    }

    // An empty turn is dropped rather than sent: the proxy refuses a request

    // whose input is empty, and a blank assistant turn is what a harness emits

    // around a call it has already described.

    if (text.trim().length === 0) continue;

    flat.push({

      role: role === "system" ? "system" : role === "assistant" ? "assistant" : "user",

      content: text,

    });

  }

  return flat;

}

/** The text of a message whose content may be a string or a part array. */

function textOf(content: unknown): string {

  if (typeof content === "string") return content;

  if (!Array.isArray(content)) return "";

  return content

    .map((part) => {

      if (typeof part === "string") return part;

      if (typeof part === "object" && part !== null) {

        const text = (part as { text?: unknown }).text;

        return typeof text === "string" ? text : "";

      }

      return "";

    })

    .join("");

}

/** The calls on an assistant message, as one line each, or nothing. */

function describeCalls(toolCalls: unknown): string | undefined {

  if (!Array.isArray(toolCalls) || toolCalls.length === 0) return undefined;

  const lines: string[] = [];

  for (const raw of toolCalls) {

    if (typeof raw !== "object" || raw === null) continue;

    const fn = (raw as { function?: { name?: unknown; arguments?: unknown } }).function ?? {};

    const id = (raw as { id?: unknown }).id;

    const name = typeof fn.name === "string" ? fn.name : "tool";

    const args = typeof fn.arguments === "string" ? fn.arguments : "";

    const suffix = typeof id === "string" && id.length > 0 ? ` id=${id}` : "";

    lines.push(`${name}(${args})${suffix}`);

  }

  return lines.length === 0 ? undefined : lines.join("\n");

}

/** A running gateway: where children should send their calls, and how to stop. */

export interface ChildGateway {

  /** The base URL a harness config points at, without a trailing slash. */

  readonly baseUrl: string;

  /** The model id, as the harness must name it: `provider/model`. */

  readonly modelId: string;

  close(): Promise<void>;

}

/** The provider name children see. Part of the model id they are given. */

export const CHILD_PROVIDER = "openagents";

/**

 * Start the gateway on a loopback port of the operating system's choosing.

 *

 * Resolves once it is listening, because a child launched against a port that

 * is not up yet fails on its first call and reports it as a provider error.

 */

export async function startChildGateway(grant: ChildGrant): Promise<ChildGateway> {

  const server = createServer((request, response) => {

    const chunks: Buffer[] = [];

    request.on("data", (chunk: Buffer) => chunks.push(chunk));

    request.on("end", () => {

      void forward(Buffer.concat(chunks).toString("utf8"), grant, response);

    });

  });

  // A child that hangs must not hold the console open on the way out.

  server.unref();

  await new Promise<void>((resolve, reject) => {

    server.once("error", reject);

    server.listen(0, "127.0.0.1", resolve);

  });

  const address = server.address() as AddressInfo;

  return {

    baseUrl: `http://127.0.0.1:${String(address.port)}/v1`,

    modelId: `${CHILD_PROVIDER}/${grant.model}`,

    close: () =>

      new Promise<void>((resolve) => {

        server.close(() => resolve());

      }),

  };

}

/** Spend the grant on one child call and stream the answer back verbatim. */

async function forward(

  body: string,

  grant: ChildGrant,

  response: import("node:http").ServerResponse,

): Promise<void> {

  let payload: Record<string, unknown> = {};

  try {

    const parsed: unknown = JSON.parse(body === "" ? "{}" : body);

    if (typeof parsed === "object" && parsed !== null) payload = parsed as Record<string, unknown>;

  } catch {

    // An unparseable body is treated as an empty one, and the proxy's own

    // refusal is what the child then reports.

  }

  const messages = Array.isArray(payload["messages"]) ? payload["messages"] : [];

  const tools = payload["tools"];

  const upstream = await fetch(grant.proxyUrl, {

    method: "POST",

    headers: {

      authorization: `Bearer ${Redacted.value(grant.token)}`,

      "content-type": "application/json",

      accept: "text/event-stream, application/json",

    },

    body: JSON.stringify({

      // The grant pins the model, so whatever the child named is ignored here

      // rather than passed through and refused.

      model: grant.model,

      stream: true,

      messages: flattenForProxy(messages),

      ...(Array.isArray(tools) && tools.length > 0 ? { tools } : {}),

    }),

  }).catch((cause: unknown) => {

    response.writeHead(502, { "content-type": "application/json" });

    response.end(

      JSON.stringify({

        error: { message: `The inference proxy could not be reached: ${String(cause)}` },

      }),

    );

    return undefined;

  });

  if (upstream === undefined) return;

  if (!upstream.ok) {

    // The proxy answers a refusal as `{"error":{"code":"…"}}`, which an

    // OpenAI-compatible client reports as an unexplained server error because

    // it looks for `error.message`. Putting the status and the body in a

    // message is the difference between a child that says

    // `budget_exhausted` and three children that say `exited with code 1`.

    const detail = (await upstream.text().catch(() => "")).slice(0, 400);

    response.writeHead(upstream.status, { "content-type": "application/json" });

    response.end(

      JSON.stringify({

        error: {

          type: "openagents_proxy",

          message:

            `The OpenAgents inference proxy refused this call with HTTP ${String(upstream.status)}` +

            `${detail === "" ? "." : `: ${detail}`}`,

        },

      }),

    );

    return;

  }

  response.writeHead(upstream.status, {

    "content-type": upstream.headers.get("content-type") ?? "text/event-stream",

  });

  if (upstream.body === null) {

    response.end();

    return;

  }

  const reader = upstream.body.getReader();

  for (;;) {

    // The body is a stream and each read depends on the one before it.

    // eslint-disable-next-line no-await-in-loop

    const { done, value } = await reader.read();

    if (done) break;

    response.write(Buffer.from(value));

  }

  response.end();

}

  }

  if (type === "error") {

    const message =

      stringField(event, "message") ??

      (isRecord(event["error"]) ? stringField(event["error"], "message") : undefined) ??

      "The child agent reported an error.";

    return { type: "error", message };

    return { type: "error", message: describeHarnessError(event) };

  }

  const sessionId = stringField(event, "sessionID");

  return undefined;

}

/**

 * The sentence behind a harness error event.

 *

 * opencode nests the sentence: the event carries an `error` with a `name` and a

 * `data` holding the `message` and a support `ref`. Reading only `message` off

 * the outer object — which is what this did — found nothing, so the fleet fell

 * back to the exit code and every failure on screen read `exited with code 1`,

 * which says nothing about the provider refusal, the missing credential, or the

 * unreachable endpoint that actually happened.

 */

function describeHarnessError(event: Record<string, unknown>): string {

  const error = isRecord(event["error"]) ? event["error"] : {};

  const data = isRecord(error["data"]) ? error["data"] : {};

  const sentence =

    stringField(event, "message") ??

    stringField(error, "message") ??

    stringField(data, "message") ??

    stringField(data, "error");

  const name = stringField(error, "name");

  const ref = stringField(data, "ref");

  const parts: string[] = [];

  if (name !== undefined && name !== "Error") parts.push(name);

  parts.push(sentence ?? "the child agent reported an error");

  const text = parts.join(": ");

  return ref === undefined ? text : `${text} (${ref})`;

}

/**

 * What the child was working on.

 *

    this.model = options.model;

  }

  /** The preflight, run once and shared by every child of this fleet. */

  private preflight: Promise<string | undefined> | undefined;

  /**

   * Check that the harness exists and knows the model, once per fleet.

   *

   * Without this, a model the harness cannot resolve fails inside its provider

   * and is reported as `Unexpected server error`, once per child — fifteen

   * identical sentences naming nothing. `opencode models` costs one process at

   * the start of a fan-out and turns that into the model id and the fact that

   * it is not on the list.

   *

   * A preflight that cannot answer says nothing rather than guessing: a

   * harness that lists no models, or a build whose subcommand differs, must

   * not be able to block a fleet that would have worked.

   */

  private check(command: string): Promise<string | undefined> {

    this.preflight ??= new Promise<string | undefined>((resolve) => {

      const probe = spawn(command, ["models"], {

        env: {

          ...process.env,

          ...this.options.env,

          ...(this.options.configPath === undefined

            ? {}

            : { OPENCODE_CONFIG: this.options.configPath }),

        },

        stdio: ["ignore", "pipe", "ignore"],

      });

      let listing = "";

      probe.stdout.setEncoding("utf8");

      probe.stdout.on("data", (chunk: string) => {

        listing += chunk;

      });

      probe.on("error", (cause: Error) => {

        resolve(

          (cause as NodeJS.ErrnoException).code === "ENOENT"

            ? `The \`${command}\` harness is not installed. Install it with ` +

                "`npm i -g opencode-ai`, or name another with --child-command."

            : `The \`${command}\` harness could not be started: ${cause.message}`,

        );

      });

      probe.on("close", (code) => {

        const models = listing

          .split("\n")

          .map((line) => stripAnsi(line).trim())

          .filter((line) => line.includes("/"));

        if (code !== 0 || models.length === 0 || models.includes(this.model)) {

          resolve(undefined);

          return;

        }

        resolve(

          `The \`${command}\` harness has no model \`${this.model}\`. ` +

            `It offers ${String(models.length)}, including ${models.slice(0, 3).join(", ")}.`,

        );

      });

    });

    return this.preflight;

  }

  async *run(

    input: { readonly prompt: string; readonly cwd: string; readonly transcriptPath: string },

    signal: AbortSignal,

  ): AsyncIterable<DelegateEvent> {

    const command = this.options.command ?? "opencode";

    const problem = await this.check(command);

    if (problem !== undefined) {

      yield { type: "error", message: problem };

      throw new Error(problem);

    }

    const args = ["run", "--format", "json", "--model", this.model, "--dir", input.cwd];

    if (this.options.autoApprove === true) args.push("--auto");

    args.push(input.prompt);

    };

    let stderr = "";

    /** The tail of stdout, kept for a child that failed without an event. */

    let stdout = "";

    let reported: string | undefined;

    let exited = false;

    let failure: string | undefined;

    child.stdout.setEncoding("utf8");

    child.stdout.on("data", (chunk: string) => {

      transcript.write(chunk);

      stdout = `${stdout}${chunk}`.slice(-4000);

      pending += chunk;

      let newline = pending.indexOf("\n");

      while (newline >= 0) {

        const line = pending.slice(0, newline);

        pending = pending.slice(newline + 1);

        const event = parseOpencodeEvent(line);

        if (event !== undefined) queue.push(event);

        if (event !== undefined) {

          if (event.type === "error") reported = event.message;

          queue.push(event);

        }

        newline = pending.indexOf("\n");

      }

      wake();

    child.on("close", (code) => {

      const trailing = parseOpencodeEvent(pending);

      if (trailing !== undefined) queue.push(trailing);

      if (trailing !== undefined) {

        if (trailing.type === "error") reported = trailing.message;

        queue.push(trailing);

      }

      if (failure === undefined && code !== 0 && !signal.aborted) {

        failure = describeExit(code, stderr);

        // What the harness said beats what the shell said. A child that

        // reported `provider refused the key` and then exited 1 has already

        // explained itself, and replacing that with the exit code is how a

        // fleet ends up reporting three identical `code 1` lines that name

        // nothing a reader could fix.

        failure = reported ?? describeExit(code, stderr, stdout);

      }

      exited = true;

      wake();

  }

}

function describeExit(code: number | null, stderr: string): string {

  const tail = stderr

/**

 * Why a child ended, in one sentence.

 *

 * Both streams are read, stderr first: a harness that dies before it starts

 * writes there, and one that dies mid-run may have written only structured

 * output that this side could not name. An exit code on its own is the last

 * resort, not the first answer.

 */

function describeExit(code: number | null, stderr: string, stdout = ""): string {

  const exit = code === null ? "was killed" : `exited with code ${code}`;

  const tail = lastLines(stderr) ?? lastLines(stdout);

  return tail === undefined ? `The child ${exit}.` : `The child ${exit}: ${tail}`;

}

function lastLines(text: string): string | undefined {

  const tail = text

    .split("\n")

    .map((line) => stripAnsi(line).trim())

    .filter((line) => line.length > 0)

    .slice(-2)

    .join(" ");

  const exit = code === null ? "was killed" : `exited with code ${code}`;

  return tail.length > 0 ? `The child ${exit}: ${tail}` : `The child ${exit}.`;

  return tail.length === 0 ? undefined : tail.slice(-400);

}

function stripAnsi(text: string): string {

    const delegation = this.delegation;

    if (delegation === undefined) {

      this.notice(

        "This session cannot delegate. Start it with a child model, for example " +

          "`openagents coder --child-model vertex-express/gemini-3.7-flash`.",

        "This session cannot delegate: children spend the session's thread, and this " +

          "session has none. Sign in with `openagents auth login --scope chat:account`, " +

          "or start the session with `--child-model provider/model` to run children on a " +

          "provider of your own.",

      );

      return;

    }

 *   ever produced here, and the interface's dim-italic reasoning entry, which

 *   the stand-in behind `--offline` still exercises, never appears against a

 *   live model.

 * - **No tool runs.** The chat lane ran tools on the server and reported each

 * - **Tools run here.** The chat lane ran tools on the server and reported each

 *   one. The proxy is a bare completions surface: it forwards the `tools` a

 *   caller declares and returns the calls the model asks for, and the caller

 *   executes them. This CLI declares none and has no tool runtime, so the