@dudousxd/nestjs-agent-opencode 1.0.0 → 2.0.0

package/dist/index.js

@@ -1999,6 +1999,37 @@ var OpenCodeEventHub = class _OpenCodeEventHub {
   }
 };
 
+// src/turn-limits.ts
+var STOPPED_ERROR_CODE = "opencode_stopped";
+function stopErrorText(stop) {
+  switch (stop.reason) {
+    case "steps":
+      return `The turn was stopped after ${stop.counts.steps - 1} steps, its limit.`;
+    case "compactions":
+      return `The turn was stopped after ${stop.counts.compactions - 1} compactions, its limit.`;
+    case "wall-clock":
+      return "The turn was stopped: it ran longer than allowed.";
+    default:
+      return "The turn was stopped.";
+  }
+}
+__name(stopErrorText, "stopErrorText");
+function cleanLimits(limits) {
+  const ok = /* @__PURE__ */ __name((n) => typeof n === "number" && Number.isFinite(n) && n >= 0, "ok");
+  return {
+    ...ok(limits?.steps) ? {
+      steps: limits.steps
+    } : {},
+    ...ok(limits?.compactions) ? {
+      compactions: limits.compactions
+    } : {},
+    ...ok(limits?.wallClockMs) ? {
+      wallClockMs: limits.wallClockMs
+    } : {}
+  };
+}
+__name(cleanLimits, "cleanLimits");
+
 // src/turns.ts
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -2028,6 +2059,16 @@ function _ts_param2(paramIndex, decorator) {
 __name(_ts_param2, "_ts_param");
 var DEFAULT_TURN_TIMEOUT_MS = 30 * 6e4;
 var DEFAULT_TOOLS_TTL_MS = 7 * 24 * 60 * 6e4;
+var DEFAULT_HOOK_TIMEOUT_MS = 5e3;
+var PARKED_RECHECKS_MS = [
+  250,
+  1e3,
+  3e3,
+  1e4,
+  3e4
+];
+var PARKED_READ_GAP_MS = 250;
+var RELEASED_USAGE_MS = 10 * 6e4;
 var OpenCodeTurns = class {
   static {
     __name(this, "OpenCodeTurns");
@@ -2051,6 +2092,21 @@ var OpenCodeTurns = class {
   spent = /* @__PURE__ */ new Set();
   /** When the tools endpoint was last registered for a location (`server|boot|directory|actor`). */
   toolsIssued = /* @__PURE__ */ new Map();
+  /**
+  * What a turn let go of here had spent, for a settle that follows here (a cancel in this process
+  * that settles after the turn was released). Dropped when the run settles here, or after
+  * {@link RELEASED_USAGE_MS} when it settles elsewhere, so no run is kept for good.
+  */
+  releasedUsage = /* @__PURE__ */ new Map();
+  keepReleasedUsage(runId, usage) {
+    this.releasedUsage.set(runId, usage);
+    setTimeout(() => {
+      if (this.releasedUsage.get(runId) === usage) this.releasedUsage.delete(runId);
+    }, RELEASED_USAGE_MS).unref?.();
+  }
+  /** The turns this process executes, and which turn owns each session (`server|session`). */
+  watches = /* @__PURE__ */ new Map();
+  owners = /* @__PURE__ */ new Map();
   constructor(host, sessions, settings, store, sink, deps, registry, skills, memory, queue, toolsTokens2, pricingStore, agentOptions) {
     this.host = host;
     this.sessions = sessions;
@@ -2063,6 +2119,10 @@ var OpenCodeTurns = class {
     this.memory = memory;
     this.queue = queue;
     this.toolsTokens = toolsTokens2;
+    const hookTimeoutMs = settings.hookTimeoutMs;
+    if (hookTimeoutMs !== void 0 && !(Number.isFinite(hookTimeoutMs) && hookTimeoutMs > 0)) {
+      throw new Error(`hookTimeoutMs must be a positive number of milliseconds, not ${hookTimeoutMs}`);
+    }
     this.prices = new ModelPriceResolver({
       pricingStore,
       catalog: agentOptions?.priceCatalog,
@@ -2334,8 +2394,12 @@ var OpenCodeTurns = class {
     }
   }
   onApplicationShutdown() {
+    for (const runId of [
+      ...this.watches.keys()
+    ]) this.release(runId, "released");
     for (const live of this.live.values()) live.stop();
     this.live.clear();
+    this.owners.clear();
     this.events.close();
   }
   // ---- begin ---------------------------------------------------------------------------------
@@ -2345,7 +2409,8 @@ var OpenCodeTurns = class {
   * durable `begin` re-run after a crash): the run's user message is written once.
   */
   async begin(runId, input) {
-    const earlier = await this.prepareThread(runId, input);
+    const startedAt = this.watches.get(runId)?.startedAt ?? Date.now();
+    const { earlier, rerun } = await this.prepareThread(runId, input);
     const server = await this.host.server(input.actor);
     const known = await this.sessions.get(input.threadId);
     const reusable = known !== null && known.serverKey === server.key && known.bootId === server.bootId && (await this.host.reuse?.({
@@ -2391,7 +2456,12 @@ var OpenCodeTurns = class {
       created
     });
     await this.refreshInstructions(runId, input, server.client, handle.sessionId);
-    return handle;
+    const begun = this.limitsFor(input).wallClockMs !== void 0 ? {
+      ...handle,
+      startedAt
+    } : handle;
+    await this.adopt(runId, input, begun, rerun, void 0, startedAt);
+    return begun;
   }
   async createSession(runId, input, server, earlier, note) {
     const { client } = server;
@@ -2461,10 +2531,16 @@ ${transcript}` : "",
       }
       const firstDropped = messages[lastUser + 1];
       if (firstDropped !== void 0) await this.store.truncateFrom(input.threadId, firstDropped.id);
-      return messages.slice(0, Math.max(lastUser, 0));
+      return {
+        earlier: messages.slice(0, Math.max(lastUser, 0)),
+        rerun: false
+      };
     }
     const mine = messages.findIndex((m) => m.role === "user" && m.runId === runId);
-    if (mine >= 0) return messages.slice(0, mine);
+    if (mine >= 0) return {
+      earlier: messages.slice(0, mine),
+      rerun: true
+    };
     await this.store.appendMessage({
       threadId: input.threadId,
       role: "user",
@@ -2480,7 +2556,10 @@ ${transcript}` : "",
     if (thread !== null && (thread.title === "" || thread.title === "New chat")) {
       await this.store.setTitle(input.threadId, titleOf(input.userText));
     }
-    return messages;
+    return {
+      earlier: messages,
+      rerun: false
+    };
   }
   /** Rewind the session to before its last user message, so the regenerated answer replaces it. */
   async revertLastExchange(client, sessionId) {
@@ -2696,6 +2775,7 @@ ${body}
   // ---- prompt / observe / reply --------------------------------------------------------------
   /** Start listening to the session (so nothing it says is missed), then send the user message. */
   async prompt(runId, input, handle, spent) {
+    await this.adopt(runId, input, handle, true);
     const live = await this.ensureLive(runId, input, handle, false, spent);
     try {
       const prompt = await this.host.promptFor?.({
@@ -2738,7 +2818,24 @@ ${body}
   * back from the session's messages, when the execution ends, what nobody heard after that.
   */
   async observe(runId, input, handle, spent, progress) {
+    const watch = await this.adopt(runId, input, handle, true, progress?.counts);
     const live = await this.ensureLive(runId, input, handle, true, spent, progress);
+    watch.parkedOn = void 0;
+    watch.parkedEnd = void 0;
+    watch.series = false;
+    watch.observing = true;
+    const wall = this.watchClock(watch);
+    try {
+      if (watch.pending !== void 0) await this.requestStop(runId, watch.pending);
+      const milestone = this.marked(watch, await this.observeLive(runId, input, handle, live));
+      if (milestone.kind === "ask") watch.parkedOn = milestone.ask.id;
+      return milestone;
+    } finally {
+      watch.observing = false;
+      if (wall !== void 0) clearTimeout(wall);
+    }
+  }
+  async observeLive(runId, input, handle, live) {
     const { turn, client } = live;
     if (turn.hasMilestone()) return this.reached(runId, input, handle, await turn.next());
     let done = false;
@@ -2778,19 +2875,64 @@ ${body}
   * to go on.
   */
   async reply(runId, input, handle, ask, reply, spent, progress) {
+    const watch = await this.adopt(runId, input, handle, true, progress?.counts);
+    watch.parkedOn = void 0;
+    watch.parkedEnd = void 0;
+    watch.series = false;
+    const stopping = watch.pending !== void 0 || watch.stop !== void 0;
+    const answer = stopping ? refusalOf(ask) : reply;
     const server = await this.host.server(input.actor);
     if (server.key !== handle.serverKey || server.bootId !== handle.bootId) {
-      return this.continueAfterRestart(runId, input, server, ask, reply, spent);
+      if (stopping) return this.stopAfterRestart(watch, runId, input, handle, ask, answer, spent);
+      return this.continueAfterRestart(runId, input, server, ask, answer, spent, handle.startedAt);
     }
     const live = await this.ensureLive(runId, input, handle, false, spent, progress);
-    await live.turn.decide(ask, reply);
+    await live.turn.decide(ask, answer);
     return handle;
   }
-  async continueAfterRestart(runId, input, server, ask, reply, spent) {
+  /**
+  * A stopping turn whose OpenCode server restarted while it waited: there is no session left to
+  * abort, and none is opened or prompted. The ask is settled as refused and the turn ends stopped.
+  */
+  async stopAfterRestart(watch, runId, input, handle, ask, answer, spent) {
+    const live = await this.ensureLive(runId, input, handle, false, spent);
+    await live.turn.decide(ask, answer, {
+      tellOpenCode: false
+    });
+    const reason = watch.pending ?? watch.stop?.reason ?? "stopped";
+    if (watch.stop === void 0) {
+      const stop = {
+        reason,
+        counts: this.counts(watch)
+      };
+      watch.stop = stop;
+      this.hook("onStop", {
+        turnId: runId,
+        reason,
+        counts: stop.counts
+      });
+    }
+    watch.aborted = true;
+    watch.pending = void 0;
+    live.turn.handle({
+      type: "session.execution.interrupted",
+      data: {
+        sessionID: handle.sessionId
+      }
+    });
+    return handle;
+  }
+  async continueAfterRestart(runId, input, server, ask, reply, spent, startedAt) {
     const approved = "approved" in reply && reply.approved === true;
     const note = ask.kind === "approval" ? approved ? `The user approved the action ${ask.action} you asked permission for. Continue the task.` : `The user did not approve the action ${ask.action}. Continue without it and explain.` : `The user answered your question: ${JSON.stringify("answers" in reply ? reply.answers : {})}. Continue.`;
     const thread = await this.store.getThread(input.threadId);
-    const handle = await this.createSession(runId, input, server, thread?.messages ?? [], note);
+    const created = await this.createSession(runId, input, server, thread?.messages ?? [], note);
+    const handle = {
+      ...created,
+      ...startedAt !== void 0 ? {
+        startedAt
+      } : {}
+    };
     await this.refreshInstructions(runId, input, server.client, handle.sessionId);
     this.drop(runId);
     const live = await this.ensureLive(runId, input, handle, false, spent);
@@ -2875,7 +3017,11 @@ ${body}
         this.grants.set(runId, grants);
       }, "onGranted")
     });
-    const stop = await this.events.listen(server.key, server.client, handle.sessionId, (event) => turn.handle(event));
+    const sessionId = handle.sessionId;
+    const stop = await this.events.listen(server.key, server.client, sessionId, (event) => {
+      turn.handle(event);
+      this.sawEvent(runId, sessionId, event);
+    });
     const live = {
       turn,
       input,
@@ -2884,6 +3030,15 @@ ${body}
       stop
     };
     this.live.set(runId, live);
+    this.owners.set(ownerKey(handle), runId);
+    const watch = this.watches.get(runId);
+    if (watch !== void 0 && watch.handle.sessionId !== sessionId) {
+      watch.handle = {
+        ...handle,
+        startedAt: watch.startedAt
+      };
+      watch.ending = false;
+    }
     if (resumed) await turn.catchUp().catch(() => void 0);
     return live;
   }
@@ -2892,11 +3047,46 @@ ${body}
     this.live.get(runId)?.stop();
     this.live.delete(runId);
   }
-  /** Stop following a run and drop the approvals it was granted: it is over. */
+  /**
+  * Stop following a run and drop the approvals it was granted: it is over. Returns the turn this
+  * process executed, now settled (no stop reaches it any more), for its `onTurnEnd`.
+  */
   forget(runId) {
     this.drop(runId);
+    this.releasedUsage.delete(runId);
     for (const grant of this.grants.get(runId) ?? []) this.spent.delete(grant.id);
     this.grants.delete(runId);
+    const watch = this.watches.get(runId);
+    if (watch === void 0) return void 0;
+    watch.settled = true;
+    this.watches.delete(runId);
+    for (const [key, owner] of this.owners) if (owner === runId) this.owners.delete(key);
+    return watch;
+  }
+  /**
+  * A run that ended without settling here (cancelled while this process executed it; whoever
+  * cancelled settled it): stop following it, and end the turn this process executed.
+  */
+  async abandon(runId) {
+    const watch = this.forget(runId);
+    if (watch !== void 0) this.ended(watch, "interrupted", void 0);
+  }
+  /**
+  * Let go of a turn this process executed without settling it here: it was cancelled while parked
+  * (its session ended under it, `interrupted`), another worker took it over, or this process shuts
+  * down (`released`). The per-turn state goes, `onTurnEnd` fires once, and a later stop of the turn
+  * here is ignored. Nothing settles the run here afterwards: whoever answered or cancelled it does.
+  */
+  release(runId, status) {
+    const watch = this.watches.get(runId);
+    if (watch === void 0) return;
+    const seen = this.live.get(runId)?.turn.totalUsage();
+    if (seen !== void 0) this.keepReleasedUsage(runId, seen);
+    this.drop(runId);
+    watch.settled = true;
+    this.watches.delete(runId);
+    for (const [key, owner] of this.owners) if (owner === runId) this.owners.delete(key);
+    this.ended(watch, status, void 0);
   }
   // ---- settle --------------------------------------------------------------------------------
   /** A person was asked something: tell the host (cards in other channels, wake-ups). */
@@ -2969,7 +3159,7 @@ ${body}
   * two milestones.
   */
   spentBy(runId, spent) {
-    const seen = this.live.get(runId)?.turn.totalUsage();
+    const seen = this.live.get(runId)?.turn.totalUsage() ?? this.releasedUsage.get(runId);
     if (spent === void 0) return seen ?? emptyUsage();
     if (seen === void 0) return spent;
     const tokens = /* @__PURE__ */ __name((u) => u.inputTokens + u.outputTokens, "tokens");
@@ -2979,13 +3169,13 @@ ${body}
   * End the run's stream and bookkeeping for how its execution ended. `spent` is what the run spent
   * (the sum of its milestones' `usage`); omit → what the turn this process follows saw.
   */
-  async settle(runId, input, outcome, durationMs, spent) {
+  async settle(runId, input, ended, durationMs, spent) {
+    const outcome = this.withStop(ended, this.watches.get(runId));
     if (outcome.status === "failed") {
-      await this.settleFailed(runId, input, outcome.error, durationMs, spent);
-      return;
+      return this.settleFailed(runId, input, outcome.error, durationMs, spent, outcome.stop);
     }
     const usage = this.spentBy(runId, spent);
-    this.forget(runId);
+    const watch = this.forget(runId);
     const writer = await this.sink.open(runId);
     const result = await this.runResult(runId, input, outcome, durationMs, usage);
     await this.amend(writer, result);
@@ -3020,22 +3210,30 @@ ${body}
       });
     }
     await this.settled(result);
+    if (watch !== void 0) this.ended(watch, outcome.status, outcome.status === "succeeded" ? outcome.stop : void 0);
+    return outcome;
   }
-  async settleFailed(runId, input, error, durationMs = 0, spent) {
+  async settleFailed(runId, input, error, durationMs = 0, spent, stop) {
     const usage = this.spentBy(runId, spent);
-    this.forget(runId);
+    const watch = this.forget(runId);
+    const stopped = stop ?? watch?.stop;
     const writer = await this.sink.open(runId);
     const result = await this.runResult(runId, input, {
       status: "failed",
-      error
+      error,
+      ...stopped !== void 0 ? {
+        stop: stopped
+      } : {}
     }, durationMs, usage);
     const worded = (await this.amend(writer, result)).error;
-    const message = worded ?? streamFailure(new Error(error)).message;
-    this.logger.error(`agent run ${runId} failed: ${error}`);
+    const message = worded ?? (stopped !== void 0 ? error : streamFailure(new Error(error)).message);
+    const code = stopped !== void 0 ? STOPPED_ERROR_CODE : "opencode_failed";
+    if (stopped !== void 0) this.logger.log(`agent run ${runId} stopped: ${stopped.reason}`);
+    else this.logger.error(`agent run ${runId} failed: ${error}`);
     publishAgentRunFailed({
       runId,
       threadId: input.threadId,
-      code: "opencode_failed",
+      code,
       message: error,
       durationMs,
       context: agentRunContext(input)
@@ -3044,23 +3242,370 @@ ${body}
       runId,
       status: "failed",
       durationMs,
-      errorCode: "opencode_failed",
+      errorCode: code,
       errorMessage: error
     });
     await Promise.resolve(this.store.failUnsettledToolCalls?.(runId, RUN_ENDED_BEFORE_TOOL_CALL)).catch(() => 0);
     await this.handoff(writer, input, runId, "failed", error);
     await releaseThreadRun(this.store, input.threadId, runId);
     await writer.fail({
-      code: "opencode_failed",
+      code,
       message
     });
     await this.settled({
       ...result,
       outcome: {
         status: "failed",
-        error: worded ?? error
+        error: worded ?? error,
+        ...stopped !== void 0 ? {
+          stop: stopped
+        } : {}
       }
     });
+    if (watch !== void 0) this.ended(watch, "failed", stopped);
+    return {
+      status: "failed",
+      error,
+      ...stopped !== void 0 ? {
+        stop: stopped
+      } : {}
+    };
+  }
+  // ---- limits, stops and the turn's lifecycle -------------------------------------------------
+  /**
+  * Stop a turn's own work: abort its session so OpenCode starts no new round, only while the turn
+  * still owns the session (a thread's session is reused by its next turn) — checked immediately
+  * before the abort. Acts in the process executing the turn; see {@link OpenCodeStopResult}. The
+  * turn ends failed with `outcome.stop` (code `opencode_stopped`), and `onStop` is called.
+  */
+  stopTurn(turnId, reason) {
+    return this.requestStop(turnId, reason);
+  }
+  /** The turn this process executes, made known here on its first step in this process. */
+  async adopt(runId, input, handle, resumed, counts, startedAt) {
+    const known = this.watches.get(runId);
+    if (known !== void 0) return known;
+    const watch = {
+      runId,
+      input,
+      handle,
+      limits: this.limitsFor(input),
+      startedAt: handle.startedAt ?? startedAt ?? Date.now(),
+      steps: counts?.steps ?? 0,
+      compactions: counts?.compactions ?? 0,
+      observing: false,
+      ending: false,
+      settled: false,
+      aborted: false,
+      checking: false,
+      lastRead: 0
+    };
+    this.watches.set(runId, watch);
+    await this.hook("onTurnStart", {
+      turnId: runId,
+      threadId: input.threadId,
+      sessionId: handle.sessionId,
+      resumed
+    });
+    return watch;
+  }
+  limitsFor(input) {
+    const limits = this.settings.limits;
+    return cleanLimits(typeof limits === "function" ? limits(input) : limits);
+  }
+  /**
+  * One event of the turn's session: counted for the limits, and told to `onTurnEvent`. While the
+  * turn is parked on a person here, it may also say the turn went on without this process
+  * ({@link wentOnElsewhere}).
+  */
+  sawEvent(runId, sessionId, event) {
+    if (sessionOf(event) !== sessionId) return;
+    const watch = this.watches.get(runId);
+    if (watch === void 0 || watch.settled || watch.handle.sessionId !== sessionId) return;
+    if (watch.parkedOn !== void 0 && this.wentOnElsewhere(watch, event)) return;
+    let reached;
+    if (event.type.startsWith("session.execution.")) watch.ending = true;
+    else if (event.type === "session.step.started") {
+      watch.steps += 1;
+      if (passed(watch.steps, watch.limits.steps)) reached = "steps";
+    } else if (event.type === "session.compaction.started") {
+      watch.compactions += 1;
+      if (passed(watch.compactions, watch.limits.compactions)) reached = "compactions";
+    }
+    this.hook("onTurnEvent", {
+      turnId: runId,
+      type: event.type,
+      sessionId
+    });
+    if (reached !== void 0) void this.limitStop(runId, reached);
+  }
+  /**
+  * Whether a turn parked here went on without this process, which then lets it go. While a tool of
+  * the step waits on a person, OpenCode keeps running the step's other tools, so their events say
+  * nothing. What does: a new round (`session.step.started`, which cannot begin while the step
+  * waits), or the store showing the parked ask decided by someone else (another worker answered
+  * it, or a cancel elsewhere settled it) — this process clears the park before it answers. When
+  * the session's execution ends while parked, the store is asked again for a while, as a cancel
+  * elsewhere settles the ask just after it interrupted the session; with the ask still open, the
+  * turn stays here for its answer.
+  */
+  wentOnElsewhere(watch, event) {
+    if (event.type === "session.step.started") {
+      this.release(watch.runId, "released");
+      return true;
+    }
+    const ended = event.type.startsWith("session.execution.");
+    if (ended) watch.parkedEnd = event.type === "session.execution.interrupted" ? "interrupted" : "released";
+    this.checkParked(watch, ended);
+    return false;
+  }
+  /**
+  * Ask the store whether the parked ask was decided elsewhere, and let the turn go when it was —
+  * one read at a time, at most one every {@link PARKED_READ_GAP_MS}. `series`: the session's
+  * execution ended, so the store is asked again over {@link parkedRechecksMs}. An execution that
+  * was interrupted under a parked turn means a cancel elsewhere: when the store cannot say (it has
+  * no `toolCallApproval`, the read fails, the ask is not on file) past the first recheck, or the
+  * rechecks run out with the ask still open, the turn is let go as `interrupted` anyway.
+  */
+  checkParked(watch, series) {
+    if (series) watch.series = true;
+    if (watch.checking) {
+      watch.again = true;
+      return;
+    }
+    watch.checking = true;
+    void this.runParkedChecks(watch);
+  }
+  /**
+  * The checks of {@link checkParked}. `checking` is cleared in the same step the loop returns in,
+  * so a check asked for afterwards starts a new loop; one asked for while it ran (`again`) but not
+  * read because the loop returned starts one too.
+  */
+  async runParkedChecks(watch) {
+    try {
+      await this.parkedChecks(watch);
+    } finally {
+      watch.checking = false;
+      if (watch.again && !watch.settled && watch.parkedOn !== void 0) {
+        watch.checking = true;
+        void this.runParkedChecks(watch);
+      }
+    }
+  }
+  async parkedChecks(watch) {
+    const ask = watch.parkedOn;
+    const gone = /* @__PURE__ */ __name(() => watch.settled || ask === void 0 || watch.parkedOn !== ask, "gone");
+    let step = 0;
+    for (; ; ) {
+      watch.again = false;
+      const wait = watch.lastRead + PARKED_READ_GAP_MS - Date.now();
+      if (wait > 0) await sleep(wait);
+      if (gone()) return;
+      const answer = await this.parkedAsk(ask);
+      watch.lastRead = Date.now();
+      if (gone()) return;
+      if (answer === "decided") {
+        this.release(watch.runId, watch.parkedEnd ?? "released");
+        return;
+      }
+      if (watch.series) {
+        const cancelled = watch.parkedEnd === "interrupted";
+        if (cancelled && answer === "unknown" && step > 0) {
+          this.release(watch.runId, "interrupted");
+          return;
+        }
+        const gap = this.parkedRechecksMs[step];
+        step += 1;
+        if (gap === void 0) {
+          if (cancelled) this.release(watch.runId, "interrupted");
+          return;
+        }
+        await sleep(gap);
+        continue;
+      }
+      if (!watch.again) return;
+    }
+  }
+  /** What the store says of an ask: decided, still open, or nothing it can tell. */
+  async parkedAsk(id) {
+    if (this.store.toolCallApproval === void 0) return "unknown";
+    try {
+      const state = await this.store.toolCallApproval(id);
+      if (state == null) return "unknown";
+      return state.status === "pending_approval" ? "open" : "decided";
+    } catch {
+      return "unknown";
+    }
+  }
+  /**
+  * The waits between the store's rereads of a parked ask after its execution ended (cumulative
+  * 0.25, 1.25, 4.25, 14.25 and 44.25 seconds after the first). Overridden by tests only.
+  *
+  * @internal
+  */
+  parkedRechecksMs = PARKED_RECHECKS_MS;
+  /** A limit's stop: what it did is the engine's to log, there is no caller to tell. */
+  async limitStop(runId, reason) {
+    const result = await this.requestStop(runId, reason);
+    if (result === "unconfirmed") this.logger.warn(`run ${runId}: passed its ${reason} limit, but its owner could not be read`);
+  }
+  /** The wall-clock bound of an observation: a timer for what is left of it, if anything. */
+  watchClock(watch) {
+    const max = watch.limits.wallClockMs;
+    if (max === void 0) return void 0;
+    const left = watch.startedAt + max - Date.now();
+    if (left <= 0) {
+      watch.pending ??= "wall-clock";
+      return void 0;
+    }
+    const timer = setTimeout(() => void this.limitStop(watch.runId, "wall-clock"), left);
+    timer.unref?.();
+    return timer;
+  }
+  counts(watch) {
+    return {
+      steps: watch.steps,
+      compactions: watch.compactions,
+      elapsedMs: Date.now() - watch.startedAt
+    };
+  }
+  async requestStop(runId, reason) {
+    const watch = this.watches.get(runId);
+    if (watch === void 0 || watch.settled || watch.stop !== void 0) return "ignored";
+    const live = this.live.get(runId);
+    if (watch.parkedOn !== void 0) {
+      watch.pending ??= reason;
+      return "pending";
+    }
+    if (watch.ending || live?.turn.finished === true) return this.landed(watch, reason);
+    if (!watch.observing || live === void 0) {
+      watch.pending ??= reason;
+      return "pending";
+    }
+    watch.pending = void 0;
+    let active;
+    try {
+      active = await this.activeRun(watch.input.threadId);
+    } catch (error) {
+      this.logger.warn(`run ${runId}: could not read the thread's run: ${errorText(error, "error")}`);
+      return "unconfirmed";
+    }
+    if (watch.settled || watch.stop !== void 0 || this.live.get(runId) !== live) return "ignored";
+    if (active !== null && active !== runId) return "ignored";
+    if (this.owners.get(ownerKey(watch.handle)) !== runId) return "ignored";
+    if (watch.ending || live.turn.finished) return this.landed(watch, reason);
+    const stop = {
+      reason,
+      counts: this.counts(watch)
+    };
+    watch.stop = stop;
+    watch.aborted = true;
+    try {
+      await live.client.session.interrupt({
+        sessionID: watch.handle.sessionId
+      });
+    } catch (error) {
+      this.logger.warn(`run ${runId}: could not abort the session: ${errorText(error, "error")}`);
+    }
+    this.hook("onStop", {
+      turnId: runId,
+      reason,
+      counts: stop.counts
+    });
+    return "aborted";
+  }
+  /** A stop that arrived while the answer settles: recorded and reported, the answer kept. */
+  landed(watch, reason) {
+    const stop = {
+      reason,
+      counts: this.counts(watch)
+    };
+    watch.stop = stop;
+    watch.pending = void 0;
+    this.hook("onStop", {
+      turnId: watch.runId,
+      reason,
+      counts: stop.counts
+    });
+    return "settling";
+  }
+  /** The milestone as the runner journals it: the limits' counts on an ask, the stop on an end. */
+  marked(watch, milestone) {
+    if (milestone.kind === "finished") return {
+      ...milestone,
+      outcome: this.withStop(milestone.outcome, watch)
+    };
+    if (milestone.progress === void 0) return milestone;
+    const counts = {
+      steps: watch.steps,
+      compactions: watch.compactions
+    };
+    return {
+      ...milestone,
+      progress: {
+        ...milestone.progress,
+        counts
+      }
+    };
+  }
+  /**
+  * How a turn a stop landed on ends. An answer that settled anyway is kept, with the stop on it; an
+  * execution that failed on its own keeps its error, with the stop on it; an execution the stop
+  * aborted ends failed with the stop's own text. One interrupted by a person's cancel stays so.
+  */
+  withStop(outcome, watch) {
+    const stop = watch?.stop;
+    if (stop === void 0) return outcome;
+    if (outcome.status !== "interrupted") return outcome.stop !== void 0 ? outcome : {
+      ...outcome,
+      stop
+    };
+    if (!watch?.aborted) return outcome;
+    return {
+      status: "failed",
+      error: stopErrorText(stop),
+      stop
+    };
+  }
+  /** `onTurnEnd`, once per turn this process executed; not waited for. */
+  ended(watch, status, stop) {
+    this.hook("onTurnEnd", {
+      turnId: watch.runId,
+      status,
+      ...stop !== void 0 ? {
+        stop
+      } : {}
+    });
+  }
+  /**
+  * A lifecycle hook, from the settings and the host, called at once. The promise settles when both
+  * have, or after `hookTimeoutMs` (default 5 s) — only `onTurnStart` is waited for. Errors are
+  * logged, never the turn's.
+  */
+  hook(name, event) {
+    const calls = [];
+    for (const target of [
+      this.settings,
+      this.host
+    ]) {
+      const fn = target[name];
+      if (typeof fn !== "function") continue;
+      calls.push(Promise.resolve().then(() => fn.call(target, event)).catch((error) => this.logger.warn(`${name} failed: ${errorText(error, "error")}`)));
+    }
+    if (calls.length === 0) return Promise.resolve();
+    const ms = this.settings.hookTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+    let timer;
+    const late = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        this.logger.warn(`${name} took longer than ${ms}ms; the turn went on`);
+        resolve();
+      }, ms);
+      timer.unref?.();
+    });
+    return Promise.race([
+      Promise.all(calls).then(() => void 0),
+      late
+    ]).finally(() => clearTimeout(timer));
   }
   /** Starts the next queued message of the thread; set by the runner (it owns `start`). */
   startNext;
@@ -3123,6 +3668,28 @@ OpenCodeTurns = _ts_decorate2([
     Object
   ])
 ], OpenCodeTurns);
+function passed(count, limit) {
+  return limit !== void 0 && count > limit;
+}
+__name(passed, "passed");
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms).unref?.());
+}
+__name(sleep, "sleep");
+function refusalOf(ask) {
+  return ask.kind === "approval" ? {
+    approved: false,
+    reason: "The turn was stopped."
+  } : {
+    answers: {},
+    skipped: true
+  };
+}
+__name(refusalOf, "refusalOf");
+function ownerKey(handle) {
+  return `${handle.serverKey}|${handle.sessionId}`;
+}
+__name(ownerKey, "ownerKey");
 function titleOf(text) {
   const trimmed = text.trim().replace(/\s+/g, " ");
   return trimmed.length > 60 ? `${trimmed.slice(0, 57)}...` : trimmed || "New chat";
@@ -3296,7 +3863,7 @@ var OpenCodeAgentRunner = class {
         await this.turns.interrupt(input).catch(() => void 0);
         await this.turns.settle(runId, input, {
           status: "interrupted"
-        }, Date.now() - started);
+        }, Date.now() - started, spent);
         return;
       }
       await this.turns.settleFailed(runId, input, errorText(error, "the turn failed"), Date.now() - started);
@@ -3452,6 +4019,7 @@ export {
   OpenCodeToolsTokens,
   OpenCodeTurn,
   OpenCodeTurns,
+  STOPPED_ERROR_CODE,
   addUsage,
   emptyUsage,
   keyValueOpenCodeSessionStore,