* permissions, provider credentials — is the harness's business.

   */

  run(

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

    input: {

      readonly prompt: string;

      readonly cwd: string;

      readonly transcriptPath: string;

      /**

       * A session to continue rather than start.

       *

       * Set only on a retry, and only when the first attempt got far enough to

       * report one. Resuming is what makes a retry safe: a child that ran

       * twenty-five tools before its provider dropped has already edited files,

       * and starting it again from the prompt would redo all of it.

       */

      readonly resumeSessionId?: string | undefined;

    },

    signal: AbortSignal,

  ): AsyncIterable<DelegateEvent>;

}

  }

  async *run(

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

    input: {

      readonly prompt: string;

      readonly cwd: string;

      readonly transcriptPath: string;

      readonly resumeSessionId?: string | undefined;

    },

    signal: AbortSignal,

  ): AsyncIterable<DelegateEvent> {

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

  }

  async *run(

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

    input: {

      readonly prompt: string;

      readonly cwd: string;

      readonly transcriptPath: string;

      readonly resumeSessionId?: string | undefined;

    },

    signal: AbortSignal,

  ): AsyncIterable<DelegateEvent> {

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

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

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

    args.push(input.prompt);

    if (input.resumeSessionId === undefined) {

      args.push(input.prompt);

    } else {

      // The work already done stays done. `--continue` picks the session back

      // up with its whole transcript, so the child carries on from where its

      // provider dropped rather than re-reading and re-editing everything.

      args.push("--session", input.resumeSessionId, "--continue");

      args.push(

        "The previous attempt stopped when the model provider became unavailable. " +

          "Continue from where you left off and finish the task.",

      );

    }

    const child = spawn(command, args, {

      cwd: input.cwd,

    /** Tool calls already counted. A harness reports one call several times. */

    const counted = new Set<string>();

    /** The child's session, once it reports one, so a retry can resume it. */

    let sessionId: string | undefined;

    let text = "";

    let reported: string | undefined;

    try {

      for await (const event of this.harness.run(

        { prompt: request.prompt, cwd, transcriptPath },

        controller.signal,

      )) {

        if (controller.signal.aborted) break;

        if (event.type === "tool") {

          if (counted.has(event.callId)) continue;

          counted.add(event.callId);

          const activity: CoderToolActivity = { toolName: event.name, target: event.target };

          this.registry.recordToolUse(id, activity);

        } else if (event.type === "tokens") {

          this.registry.recordTokens(id, { input: event.input, output: event.output });

        } else if (event.type === "text") {

          // Only the final assistant text is the child's answer, and a harness

          // emits one text part per step, so the last one wins.

          text = event.value;

        } else if (event.type === "error") {

          reported = event.message;

    for (let attempt = 1; ; attempt += 1) {

      let reported: string | undefined;

      let thrown: string | undefined;

      try {

        for await (const event of this.harness.run(

          {

            prompt: request.prompt,

            cwd,

            transcriptPath,

            ...(sessionId === undefined ? {} : { resumeSessionId: sessionId }),

          },

          controller.signal,

        )) {

          if (controller.signal.aborted) break;

          if (event.type === "session") {

            sessionId = event.sessionId;

          } else if (event.type === "tool") {

            if (counted.has(event.callId)) continue;

            counted.add(event.callId);

            const activity: CoderToolActivity = { toolName: event.name, target: event.target };

            this.registry.recordToolUse(id, activity);

          } else if (event.type === "tokens") {

            this.registry.recordTokens(id, { input: event.input, output: event.output });

          } else if (event.type === "text") {

            // Only the final assistant text is the child's answer, and a

            // harness emits one text part per step, so the last one wins.

            text = event.value;

          } else if (event.type === "error") {

            reported = event.message;

          }

        }

      } catch (cause) {

        thrown = cause instanceof Error ? cause.message : String(cause);

      }

      if (controller.signal.aborted) {

        return { status: "stopped", taskId: id };

      }

      if (reported !== undefined) {

        this.registry.fail(id, reported);

        return { status: "failed", taskId: id, error: reported };

      if (controller.signal.aborted) return { status: "stopped", taskId: id };

      const failure = reported ?? thrown;

      if (failure === undefined) {

        this.registry.complete(id, text);

        return { status: "completed", taskId: id, result: text };

      }

      this.registry.complete(id, text);

      return { status: "completed", taskId: id, result: text };

    } catch (cause) {

      if (controller.signal.aborted) {

        return { status: "stopped", taskId: id };

      const retry = this.retryDelay(failure, attempt, sessionId, counted.size);

      if (retry === undefined) {

        this.registry.fail(id, failure);

        return { status: "failed", taskId: id, error: failure };

      }

      const message = cause instanceof Error ? cause.message : String(cause);

      this.registry.fail(id, message);

      return { status: "failed", taskId: id, error: message };

      this.registry.recordToolUse(id, {

        toolName: "retry",

        target: `provider unavailable, attempt ${String(attempt + 1)}`,

      });

      await new Promise((wake) => setTimeout(wake, retry));

      if (controller.signal.aborted) return { status: "stopped", taskId: id };

    }

  }

  /**

   * How long to wait before running this child again, or `undefined` to stop.

   *

   * A provider that went away is the one failure worth retrying: nothing about

   * the request was wrong, and the six minutes of work the child had already

   * done are thrown away with it. Everything else — a refused permission, a

   * missing model, a prompt the child could not carry out — recurs on the

   * second attempt exactly as it did on the first.

   *

   * A retry that cannot resume the child's session is refused once the child

   * has run a tool. That child has edited files, and starting it again from

   * the prompt would apply its work twice; losing the run is the better of two

   * bad outcomes. With a session to continue, the work already done stays

   * done and the retry is safe.

   */

  private retryDelay(

    failure: string,

    attempt: number,

    sessionId: string | undefined,

    toolsRun: number,

  ): number | undefined {

    const attempts = 3;

    if (attempt >= attempts) return undefined;

    if (!transientProviderFailure(failure)) return undefined;

    if (sessionId === undefined && toolsRun > 0) return undefined;

    // Exponential, from two seconds. A provider that has just dropped is

    // usually back within a few, and a child is not a keystroke — waiting eight

    // seconds to save six minutes of work is not a wait anyone notices.

    return 2_000 * 2 ** (attempt - 1);

  }

  private mintId(): CoderTaskId {

    // Time first so ids sort in launch order, then a counter so two children

    // launched in the same millisecond cannot collide.

  const value = record[key];

  return typeof value === "number" && Number.isFinite(value) ? value : undefined;

}

/**

 * Whether this failure is the provider going away rather than the work being

 * wrong.

 *

 * Matched on the message because that is all a harness gives: `opencode`

 * reports its provider's error as text, and the shape seen in practice is

 * `APIError: Error from provider (Console): Upstream request failed: Endpoint

 * is unavailable.` The list is deliberately narrow. A false positive re-runs a

 * child that was never going to succeed, which costs minutes and money for the

 * same answer.

 */

export function transientProviderFailure(message: string): boolean {

  const text = message.toLowerCase();

  // A refusal that names the request is not the provider being away, however

  // much of the surrounding wording matches.

  if (/\b(invalid|unauthorized|forbidden|not found|unsupported|quota)\b/.test(text)) return false;

  return [

    "endpoint is unavailable",

    "upstream request failed",

    "service unavailable",

    "temporarily unavailable",

    "overloaded",

    "rate limit",

    "too many requests",

    "connection reset",

    "connection refused",

    "socket hang up",

    "econnreset",

    "etimedout",

    "gateway timeout",

    "bad gateway",

    "502",

    "503",

    "504",

  ].some((needle) => text.includes(needle));

}

/** What the thread may still spend, as the server last reported it. */

export interface ThreadBudget {

  readonly calls: number;

  readonly totalTokens: number;

  readonly costMicrousd: number;

  /** `undefined` where the server set no ceiling: there is nothing counting down. */

  readonly calls: number | undefined;

  readonly totalTokens: number | undefined;

  readonly costMicrousd: number | undefined;

}

export interface ThreadOptions {

   */

  private spend(usage: Record<string, unknown>): void {

    const total = number(usage["total_tokens"]);

    // A ceiling that was never set has no remainder to decrement. Counting one

    // down from `undefined` would have invented a limit the server does not

    // hold, and shown it running out.

    this.remaining = {

      calls: Math.max(0, this.remaining.calls - 1),

      totalTokens: Math.max(0, this.remaining.totalTokens - total),

      calls: this.remaining.calls === undefined ? undefined : Math.max(0, this.remaining.calls - 1),

      totalTokens:

        this.remaining.totalTokens === undefined

          ? undefined

          : Math.max(0, this.remaining.totalTokens - total),

      costMicrousd: this.remaining.costMicrousd,

    };

    // The same report feeds the turn's own tally, which `turn.assistant`

  remaining: Record<string, unknown>,

  limits: Record<string, unknown>,

): ThreadBudget {

  // `null` from the server means unbounded, and is carried as `undefined`

  // rather than collapsed to zero. A ceiling of nothing left and a ceiling that

  // was never set are opposite facts, and `number()` would have printed both as

  // `0 calls` — a session with no limit reading as one with none remaining.

  return {

    calls: number(remaining["calls"] ?? limits["max_calls"]),

    totalTokens: number(remaining["total_tokens"] ?? limits["max_total_tokens"]),

    costMicrousd: number(remaining["cost_microusd"] ?? limits["max_cost_microusd"]),

    calls: optional(remaining["calls"] ?? limits["max_calls"]),

    totalTokens: optional(remaining["total_tokens"] ?? limits["max_total_tokens"]),

    costMicrousd: optional(remaining["cost_microusd"] ?? limits["max_cost_microusd"]),

  };

}

 * expensive model runs into instead.

 */

export function formatBudget(budget: ThreadBudget): string {

  return `${budget.calls} calls · ${compact(budget.totalTokens)} tok · ${dollars(budget.costMicrousd)}`;

  // Only the ceilings that exist. A thread with none shows nothing here, which

  // is the honest reading of a session nothing is counting down.

  const parts = [

    budget.calls === undefined ? undefined : `${String(budget.calls)} calls`,

    budget.totalTokens === undefined ? undefined : `${compact(budget.totalTokens)} tok`,

    budget.costMicrousd === undefined ? undefined : dollars(budget.costMicrousd),

  ].filter((part): part is string => part !== undefined);

  return parts.join(" · ");

}

/** A number the server gave, or `undefined` where it gave `null` for "no limit". */

function optional(value: unknown): number | undefined {

  return typeof value === "number" && Number.isFinite(value) ? value : undefined;

}

function compact(tokens: number): string {

  describePrompt,

  parseDelegateCommand,

  parseOpencodeEvent,

  transientProviderFailure,

} from "../src/coder-delegate.js";

import {

  activityPhrase,

    ]);

  });

});

describe("classifying a child's failure", () => {

  it("recognises the provider going away, in the shape opencode reports it", () => {

    // The message seen in practice, verbatim.

    expect(

      transientProviderFailure(

        "APIError: Error from provider (Console): Upstream request failed: Endpoint is unavailable.",

      ),

    ).toBe(true);

  });

  it("recognises the other ways a provider drops", () => {

    for (const message of [

      "503 Service Unavailable",

      "Provider overloaded, try again",

      "Rate limit exceeded",

      "socket hang up",

      "ECONNRESET",

      "502 Bad Gateway",

    ]) {

      expect(transientProviderFailure(message)).toBe(true);

    }

  });

  it("does not retry a failure that will recur", () => {

    for (const message of [

      "Permission denied by the user",

      "Model not found: nonsense/model",

      "The prompt could not be carried out",

      "Unauthorized: invalid API key",

      // Wording that overlaps a transient shape but names the request.

      "Quota exceeded: too many requests this month",

    ]) {

      expect(transientProviderFailure(message)).toBe(false);

    }

  });

});

describe("retrying a child whose provider dropped", () => {

  /** A harness that fails the first `failures` runs, then succeeds. */

  const flaky = (

    failures: number,

    message: string,

    options: { readonly session?: string; readonly toolsBeforeFailing?: number } = {},

  ) => {

    const runs: Array<string | undefined> = [];

    let seen = 0;

    const built: DelegateHarness = {

      agent: "fake",

      model: "fake/model",

      async *run(input) {

        runs.push(input.resumeSessionId);

        seen += 1;

        if (options.session !== undefined) {

          yield { type: "session", sessionId: options.session };

        }

        for (let index = 0; index < (options.toolsBeforeFailing ?? 0); index += 1) {

          yield { type: "tool", callId: `c${String(seen)}-${String(index)}`, name: "read", target: "f" };

        }

        if (seen <= failures) {

          yield { type: "error", message };

          return;

        }

        yield { type: "text", value: "finished" };

      },

    };

    return { harness: built, runs };

  };

  const fleetFor = (built: DelegateHarness) =>

    new DelegateFleet(new CoderTaskRegistry(), built, {

      maxConcurrent: 1,

      cwd: mkdtempSync(join(tmpdir(), "oa-retry-")),

    });

  it("resumes the session rather than starting the work again", async () => {

    const { harness: built, runs } = flaky(1, "Endpoint is unavailable", {

      session: "ses_abc",

      toolsBeforeFailing: 3,

    });

    const outcome = await fleetFor(built).submit({

      description: "flaky",

      prompt: "do the thing",

      cwd: ".",

      background: false,

    });

    expect(outcome.status).toBe("completed");

    // The retry carried the session, so the three tools already run are not

    // run again from the prompt.

    expect(runs).toEqual([undefined, "ses_abc"]);

  }, 20_000);

  it("gives up after a bounded number of attempts", async () => {

    const { harness: built, runs } = flaky(9, "Endpoint is unavailable", { session: "ses_abc" });

    const outcome = await fleetFor(built).submit({

      description: "always failing",

      prompt: "do the thing",

      cwd: ".",

      background: false,

    });

    expect(outcome.status).toBe("failed");

    expect(runs).toHaveLength(3);

  }, 20_000);

  it("does not retry a failure that will recur", async () => {

    const { harness: built, runs } = flaky(1, "Permission denied by the user", {

      session: "ses_abc",

    });

    const outcome = await fleetFor(built).submit({

      description: "refused",

      prompt: "do the thing",

      cwd: ".",

      background: false,

    });

    expect(outcome.status).toBe("failed");

    expect(runs).toHaveLength(1);

  });

  it("refuses to redo work it cannot resume", async () => {

    // No session reported, and the child already ran tools: re-running from

    // the prompt would apply its edits a second time.

    const { harness: built, runs } = flaky(1, "Endpoint is unavailable", {

      toolsBeforeFailing: 2,

    });

    const outcome = await fleetFor(built).submit({

      description: "unresumable",

      prompt: "do the thing",

      cwd: ".",

      background: false,

    });

    expect(outcome.status).toBe("failed");

    expect(runs).toHaveLength(1);

  });

  it("retries a child that had done nothing yet, session or not", async () => {

    const { harness: built, runs } = flaky(1, "Endpoint is unavailable");

    const outcome = await fleetFor(built).submit({

      description: "nothing done",

      prompt: "do the thing",

      cwd: ".",

      background: false,

    });

    expect(outcome.status).toBe("completed");

    expect(runs).toHaveLength(2);

  }, 20_000);

});