@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/lifecycle/subagent-manager.ts

@@ -0,0 +1,392 @@
+/**
+ * subagent-manager.ts - Tracks subagents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are scheduled on a ConcurrencyLimiter and auto-started as running
+ * agents complete. Foreground agents bypass the limiter (they block the parent anyway).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Model } from "@earendil-works/pi-ai";
+import { debugLog } from "#src/debug";
+import type { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import {
+  type InvocationLimitOverrides,
+  Subagent,
+  type SubagentLifecycleObserver,
+} from "#src/lifecycle/subagent";
+import type { SubagentSession } from "#src/lifecycle/subagent-session";
+import { SubagentState } from "#src/lifecycle/subagent-state";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
+
+import type { RunConfig } from "#src/runtime";
+import type {
+  AgentInvocation,
+  CompactionInfo,
+  ParentSessionInfo,
+  SubagentInvocationIdentity,
+  SubagentType,
+  ThinkingLevel,
+} from "#src/types";
+
+/**
+ * Session-retention windows (minutes). `SettingsManager` satisfies this
+ * structurally; a live getter (`getRetentionPolicy`) lets the sweep read the
+ * current values without a construction-time settings dependency.
+ */
+export interface RetentionPolicy {
+  readonly consumedSessionRetentionMinutes: number;
+  readonly unconsumedSessionRetentionMinutes: number;
+}
+
+const DEFAULT_RETENTION_POLICY: RetentionPolicy = {
+  consumedSessionRetentionMinutes: 10,
+  unconsumedSessionRetentionMinutes: 720,
+};
+
+/** Observer interface for agent lifecycle notifications. */
+export interface SubagentManagerObserver {
+  onSubagentStarted(record: Subagent): void;
+  onSubagentCompleted(record: Subagent): void;
+  /** Fires when a resumed run reaches a terminal state (distinct from a fresh completion). */
+  onSubagentResumed(record: Subagent): void;
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void;
+  /** Fires synchronously after a background agent record is created (before run). */
+  onSubagentCreated(record: Subagent): void;
+}
+
+export interface SubagentManagerOptions {
+  /** Assembly factory that produces a born-complete SubagentSession per spawn. */
+  createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+  /** Concurrency limiter — schedules background run thunks FIFO against the limit. */
+  limiter: ConcurrencyLimiter;
+  /** Base working directory handed to a workspace provider (the parent cwd). */
+  baseCwd: string;
+  getRunConfig?: () => RunConfig;
+  /** Live accessor for the session-retention windows; defaults applied when absent. */
+  getRetentionPolicy?: () => RetentionPolicy;
+  observer?: SubagentManagerObserver;
+}
+
+export interface AgentSpawnConfig {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  wrapUpTurns?: number;
+  maxDurationSeconds?: number;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  /**
+   * Skip the maxConcurrent queue check for this spawn - start immediately even
+   * if the configured concurrency limit would otherwise queue it. Useful for
+   * callers (e.g. cross-extension RPC) that must not be deferred by the queue.
+   */
+  bypassQueue?: boolean;
+  /** Resolved invocation snapshot captured for UI display. */
+  invocation?: AgentInvocation;
+  /** Lifecycle identity for the fresh parent invocation. */
+  lifecycleInvocation?: SubagentInvocationIdentity;
+  /** Parent abort signal - when aborted, the subagent is also stopped. */
+  signal?: AbortSignal;
+  /** Per-subagent lifecycle observer — replaces onSessionCreated callback. */
+  observer?: SubagentLifecycleObserver;
+  /** Parent session identity - grouped fields that travel together from the tool boundary. */
+  parentSession?: ParentSessionInfo;
+}
+
+export class SubagentManager {
+  private agents = new Map<string, Subagent>();
+  private sweepInterval: ReturnType<typeof setInterval>;
+  private readonly observer?: SubagentManagerObserver;
+  private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+  private readonly limiter: ConcurrencyLimiter;
+  private readonly baseCwd: string;
+  private getRunConfig?: () => RunConfig;
+  private getRetentionPolicy?: () => RetentionPolicy;
+  private _workspaceProvider?: WorkspaceProvider;
+
+  /** The registered workspace provider, or undefined when none is registered. */
+  get workspaceProvider(): WorkspaceProvider | undefined {
+    return this._workspaceProvider;
+  }
+
+  constructor(options: SubagentManagerOptions) {
+    this.createSubagentSession = options.createSubagentSession;
+    this.limiter = options.limiter;
+    this.baseCwd = options.baseCwd;
+    this.observer = options.observer;
+    this.getRunConfig = options.getRunConfig;
+    this.getRetentionPolicy = options.getRetentionPolicy;
+    // Periodically release the heavy session of terminal agents past their
+    // retention window. The lightweight record (with its result) is kept for the
+    // session lifetime, so get_subagent_result never misses in-session.
+    this.sweepInterval = setInterval(() => this.sweep(), 60_000);
+    this.sweepInterval.unref();
+  }
+
+  /**
+   * Register the single workspace provider. Throws if one is already
+   * registered (chaining is out of scope — see ADR 0002). Returns a disposer
+   * that clears the slot only if this provider is still the active one.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    if (this._workspaceProvider) {
+      throw new Error(
+        "A WorkspaceProvider is already registered; only one is supported.",
+      );
+    }
+    this._workspaceProvider = provider;
+    return () => {
+      if (this._workspaceProvider === provider) this._workspaceProvider = undefined;
+    };
+  }
+
+  /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
+  private buildObserver(options: AgentSpawnConfig): SubagentLifecycleObserver {
+    return {
+      onStarted: (agent) => {
+        this.observer?.onSubagentStarted(agent);
+      },
+      onSessionCreated: options.observer?.onSessionCreated
+        ? (agent) => options.observer!.onSessionCreated!(agent)
+        : undefined,
+      onRunFinished: (agent) => {
+        try { this.observer?.onSubagentCompleted(agent); } catch (err) { debugLog("onSubagentCompleted observer", err); }
+      },
+      onResumeFinished: (agent) => {
+        try { this.observer?.onSubagentResumed(agent); } catch (err) { debugLog("onSubagentResumed observer", err); }
+      },
+      onCompacted: (agent, info) => {
+        this.observer?.onSubagentCompacted(agent, info);
+      },
+    };
+  }
+
+  /**
+   * Spawn an agent and return its ID immediately (for background use).
+   * If the concurrency limit is reached, the agent is queued.
+   */
+  spawn(
+    snapshot: ParentSnapshot,
+    type: SubagentType,
+    prompt: string,
+    options: AgentSpawnConfig,
+  ): string {
+    const id = randomUUID().slice(0, 17);
+    const record = new Subagent({
+      id,
+      type,
+      description: options.description,
+      invocation: options.invocation,
+      isBackground: options.isBackground ?? false,
+      lifecycleInvocation: options.lifecycleInvocation,
+      state: new SubagentState({
+        phase: options.isBackground ? "queued" : "running",
+        startedAt: Date.now(),
+      }),
+      execution: {
+        createSubagentSession: this.createSubagentSession,
+        snapshot,
+        prompt,
+        baseCwd: this.baseCwd,
+        observer: this.buildObserver(options),
+        getRunConfig: this.getRunConfig,
+        getWorkspaceProvider: () => this._workspaceProvider,
+        model: options.model,
+        maxTurns: options.maxTurns,
+        wrapUpTurns: options.wrapUpTurns,
+        maxDurationSeconds: options.maxDurationSeconds,
+        thinkingLevel: options.thinkingLevel,
+        parentSession: options.parentSession,
+        signal: options.signal,
+      },
+    });
+    this.agents.set(id, record);
+
+    if (options.isBackground) {
+      this.observer?.onSubagentCreated(record);
+    }
+
+    if (options.isBackground && !options.bypassQueue) {
+      // Schedule on the limiter — scheduleVia captures the limiter promise
+      // eagerly, so a queued agent is awaitable from spawn; guardedRun guards
+      // against abort-while-queued when the slot frees.
+      const timeoutMs = (this.getRunConfig?.().maxQueueWaitSeconds ?? 900) * 1000;
+      record.scheduleVia((thunk) => this.limiter.schedule(thunk, {
+        timeoutMs,
+        onTimeout: () => record.queueTimedOut(timeoutMs),
+      }));
+      return id;
+    }
+
+    record.start();
+    return id;
+  }
+
+  /**
+   * Spawn an agent and wait for completion (foreground use).
+   * Foreground agents bypass the concurrency queue.
+   */
+  async spawnAndWait(
+    snapshot: ParentSnapshot,
+    type: SubagentType,
+    prompt: string,
+    options: Omit<AgentSpawnConfig, "isBackground">,
+  ): Promise<Subagent> {
+    const id = this.spawn(snapshot, type, prompt, { ...options, isBackground: false });
+    const record = this.agents.get(id)!;
+    await record.promise;
+    return record;
+  }
+
+  /**
+   * Resume an existing agent session with a new prompt.
+   * Delegates to Subagent.resume(), which owns the observer subscription lifecycle.
+   */
+  async resume(
+    id: string,
+    prompt: string,
+    invocation: SubagentInvocationIdentity,
+    limits?: InvocationLimitOverrides,
+    signal?: AbortSignal,
+  ): Promise<Subagent | undefined> {
+    const agent = this.agents.get(id);
+    if (!agent?.isSessionReady()) return undefined;
+    await agent.resume(prompt, invocation, limits, signal);
+    return agent;
+  }
+
+  getRecord(id: string): Subagent | undefined {
+    return this.agents.get(id);
+  }
+
+  listAgents(): Subagent[] {
+    return [...this.agents.values()].sort(
+      (a, b) => b.startedAt - a.startedAt,
+    );
+  }
+
+  abort(id: string): boolean {
+    const record = this.agents.get(id);
+    if (!record) return false;
+
+    // A queued agent has not started; stop it through the same terminal funnel
+    // a running agent's stop uses. Its scheduled thunk becomes a no-op (phase
+    // guard) when its slot finally opens.
+    if (record.phase === "queued") {
+      record.stopQueued();
+      return true;
+    }
+
+    return record.abort();
+  }
+
+  /**
+   * Remove a record from the map and tear its session down.
+   * The map is updated first so the record is unreachable while its child's
+   * extensions shut down.
+   */
+  private removeRecord(id: string, record: Subagent): Promise<void> {
+    this.agents.delete(id);
+    return record.disposeSession();
+  }
+
+  /**
+   * Release the heavy session of any terminal agent past its retention window.
+   * The record (with its result) is retained for the session lifetime; only the
+   * live `AgentSession` is freed. A consumed agent releases on the short window,
+   * measured from the later of completion or consumption (so a late read still
+   * gets a full resume window); an unconsumed agent holds until the long cap.
+   */
+  private sweep() {
+    const policy = this.getRetentionPolicy?.() ?? DEFAULT_RETENTION_POLICY;
+    const now = Date.now();
+    for (const record of this.agents.values()) {
+      if (record.isActive()) continue;
+      if (!record.isSessionReady()) continue; // already released, or never had a session
+      const referenceAt = record.consumed
+        ? Math.max(record.completedAt ?? 0, record.consumedAt ?? 0)
+        : record.completedAt ?? 0;
+      const windowMinutes = record.consumed
+        ? policy.consumedSessionRetentionMinutes
+        : policy.unconsumedSessionRetentionMinutes;
+      // Fire-and-forget: the sweep runs on an interval with no one to await it,
+      // and Subagent.releaseSession() already swallows a failing teardown.
+      if (now - referenceAt >= windowMinutes * 60_000) void record.releaseSession();
+    }
+  }
+
+  /**
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   */
+  async clearCompleted(): Promise<void> {
+    const teardowns: Promise<void>[] = [];
+    for (const [id, record] of this.agents) {
+      if (record.isActive()) continue;
+      teardowns.push(this.removeRecord(id, record));
+    }
+    await Promise.all(teardowns);
+  }
+
+  /** Whether any agents are still running or queued. */
+  // fallow-ignore-next-line unused-class-member
+  hasRunning(): boolean {
+    return [...this.agents.values()].some(r => r.isActive());
+  }
+
+  /** Abort all running and queued agents immediately. */
+  abortAll(): number {
+    let count = 0;
+    for (const record of this.agents.values()) {
+      if (record.phase === "queued") {
+        record.stopQueued();
+        count++;
+      } else if (record.abort()) {
+        count++;
+      }
+    }
+    // Drop pending thunks (their promises resolve).
+    this.limiter.clear();
+    return count;
+  }
+
+  /** Wait for all running and queued agents to complete (including queued ones). */
+  // fallow-ignore-next-line unused-class-member
+  async waitForAll(): Promise<void> {
+    // Every spawned agent has a settled-on-completion promise (the limiter starts
+    // queued ones as slots free), so a single allSettled covers the queued case.
+    // The loop only catches agents spawned during the wait.
+    let pending = this.pendingPromises();
+    while (pending.length > 0) {
+      await Promise.allSettled(pending);
+      pending = this.pendingPromises();
+    }
+  }
+
+  /** Promises of all running/queued agents that have one. */
+  private pendingPromises(): Promise<void>[] {
+    return [...this.agents.values()]
+      .filter(r => r.isActive())
+      .map(r => r.promise)
+      .filter((p): p is Promise<void> => p != null);
+  }
+
+  /**
+   * Tear down every record, resolving once each child's extensions have shut
+   * down. The registry is emptied before the teardowns are awaited, so nothing
+   * can reach a dying record; `allSettled` keeps one failing child from
+   * abandoning its siblings.
+   */
+  async dispose(): Promise<void> {
+    clearInterval(this.sweepInterval);
+    // Drop pending thunks
+    this.limiter.clear();
+    const teardowns = [...this.agents.values()].map(record => record.disposeSession());
+    this.agents.clear();
+    await Promise.allSettled(teardowns);
+  }
+}

package/src/lifecycle/subagent-session.ts

@@ -0,0 +1,287 @@
+/**
+ * subagent-session.ts — The born-complete child-session value object (issue #265).
+ *
+ * A SubagentSession wraps one SDK AgentSession plus its turn-driving and teardown.
+ * It is born complete: `createSubagentSession()` returns a fully usable instance
+ * (session created, extensions bound, recursion guard applied), so the only thing
+ * left for `Subagent` to do is coordinate — drive the turn loop, steer, dispose.
+ *
+ * Turn driving lives here, on the object that owns the AgentSession, rather than
+ * reaching through `subagentSession.session` from `Subagent` (Law of Demeter).
+ */
+
+import {
+  type AgentSession,
+  type AgentSessionEvent,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
+import { emitChildSessionShutdown } from "#src/lifecycle/child-shutdown";
+import { isInvocationTimeout } from "#src/lifecycle/invocation-control";
+import { getSessionContextPercent, type SessionStatsLike } from "#src/lifecycle/usage";
+import { extractText } from "#src/session/context";
+import { getAgentConversation } from "#src/session/conversation";
+import type { SessionMessage } from "#src/types";
+
+export type TurnLoopOutcome = "completed" | "turn_limit" | "timeout" | "cancelled";
+
+/** Outcome of one invocation's model turn loop. */
+export interface TurnLoopResult {
+  responseText: string;
+  outcome: TurnLoopOutcome;
+  /** Whether the agent received the configured wrap-up instruction. */
+  wrappedUp: boolean;
+}
+
+/** Strict limits for one fresh or resumed invocation. */
+export interface TurnLoopOptions {
+  maxTurns: number;
+  wrapUpTurns: number;
+  signal?: AbortSignal;
+}
+
+/** Session-level facts known at creation, supplied by the factory. */
+export interface SubagentSessionMeta {
+  /** Path to the persisted session JSONL file, if the session was persisted. */
+  outputFile: string | undefined;
+  /** Child session id — the registry key carried on session-created/disposed events. */
+  sessionId: string;
+  /** Child session directory — carried on the completed event as transcript location. */
+  sessionDir: string;
+  agentName: string;
+  /** Parent context prepended to the run prompt, captured at spawn time. */
+  parentContext: string | undefined;
+  lifecycle: ChildLifecyclePublisher;
+}
+
+/**
+ * One child AgentSession plus its turn-driving and teardown — born complete.
+ */
+export class SubagentSession {
+  private disposed = false;
+
+  constructor(
+    private readonly _session: AgentSession,
+    private readonly meta: SubagentSessionMeta,
+  ) {}
+
+  /**
+   * Wrapped session — for lifecycle-internal use only.
+   * @internal consumers outside lifecycle/ use the delegate methods below.
+   */
+  get session(): AgentSession {
+    return this._session;
+  }
+
+  /** Stable Pi session identifier for transcript attribution. */
+  get sessionId(): string {
+    return this.meta.sessionId;
+  }
+
+  get outputFile(): string | undefined {
+    return this.meta.outputFile;
+  }
+
+  /** Drive the initial invocation and publish its child-session outcome. */
+  async runTurnLoop(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult> {
+    const effectivePrompt = this.meta.parentContext
+      ? this.meta.parentContext + prompt
+      : prompt;
+    const result = await this.executePrompt(effectivePrompt, opts);
+    this.meta.lifecycle.completed({
+      sessionDir: this.meta.sessionDir,
+      agentName: this.meta.agentName,
+      outcome: result.outcome,
+      wrappedUp: result.wrappedUp,
+    });
+    return result;
+  }
+
+  /** Re-prompt the same session with a fresh invocation budget. */
+  async resumeTurnLoop(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult> {
+    return this.executePrompt(prompt, opts);
+  }
+
+  private async executePrompt(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult> {
+    const session = this._session;
+    let turnCount = 0;
+    let wrappedUp = false;
+    let hardLimitRequiredAbort = false;
+    const wrapUpAt = opts.maxTurns - Math.min(opts.wrapUpTurns, opts.maxTurns - 1);
+
+    const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
+      if (event.type !== "turn_end") return;
+
+      turnCount++;
+      const assistantContinues = turnNeedsContinuation(event);
+      if (
+        !wrappedUp &&
+        opts.wrapUpTurns > 0 &&
+        turnCount >= wrapUpAt &&
+        turnCount < opts.maxTurns &&
+        assistantContinues
+      ) {
+        wrappedUp = true;
+        void session.steer(
+          "You are approaching your hard turn limit. Stop exploring and provide your final answer now.",
+        );
+      }
+
+      if (turnCount >= opts.maxTurns && assistantContinues) {
+        hardLimitRequiredAbort = true;
+        void session.abort();
+      }
+    });
+
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, opts.signal);
+
+    try {
+      await session.prompt(prompt);
+    } finally {
+      unsubTurns();
+      collector.unsubscribe();
+      cleanupAbort();
+    }
+
+    const responseText = collector.getText().trim() || getLastAssistantText(session);
+    const outcome = resolveTurnLoopOutcome(opts.signal, hardLimitRequiredAbort);
+    return { responseText, outcome, wrappedUp };
+  }
+
+  /** Deliver a steer to the live session. */
+  async steer(message: string): Promise<void> {
+    await this._session.steer(message);
+  }
+
+  /** Abort the current SDK operation. */
+  async abort(): Promise<void> {
+    await this._session.abort();
+  }
+
+  /** Return the session's conversation as formatted text. */
+  getConversation(): string {
+    return getAgentConversation(this._session);
+  }
+
+  /** Return the session context window utilization (0-100), or null when unavailable. */
+  getContextPercent(): number | null {
+    return getSessionContextPercent(this._session);
+  }
+
+  /** Subscribe to session events. Satisfies `SubscribableSession`. */
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void {
+    return this._session.subscribe(fn);
+  }
+
+  /** Return session token statistics. Satisfies `SessionLike`. */
+  getSessionStats(): SessionStatsLike {
+    return this._session.getSessionStats();
+  }
+
+  /** The session's message history. */
+  get messages(): readonly unknown[] {
+    return this._session.messages as readonly unknown[];
+  }
+
+  /** The session's message history, typed for Pi's session-rendering machinery. */
+  get agentMessages(): readonly SessionMessage[] {
+    return this._session.messages;
+  }
+
+  /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
+  getToolDefinition(name: string): ToolDefinition | undefined {
+    return this._session.getToolDefinition(name);
+  }
+
+  /**
+   * Tear down: child `session_shutdown` + session.dispose() + emit `disposed`
+   * (registry unregister).
+   *
+   * The order is load-bearing. The shutdown emit runs first because
+   * `AgentSession.dispose()` invalidates the extension runner, after which every
+   * handler's context throws (#709). The `disposed` event runs last because it
+   * unregisters the child from the permission system, so a shutdown handler
+   * still resolves against a live registration.
+   *
+   * Idempotent: the guard is set before the first await, so concurrent callers
+   * (a retention sweep racing a manager teardown) emit and dispose exactly once.
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    await emitChildSessionShutdown(this._session);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
+    this._session.dispose?.();
+    this.meta.lifecycle.disposed({ sessionId: this.meta.sessionId });
+  }
+}
+
+// ── Private turn-loop helpers ───────────────────────────────────────────────────
+
+/**
+ * Subscribe to a session and collect the last assistant message text.
+ * Returns an object with a `getText()` getter and an `unsubscribe` function.
+ */
+function collectResponseText(session: AgentSession) {
+  let text = "";
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "message_start") {
+      text = "";
+    }
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      text += event.assistantMessageEvent.delta;
+    }
+  });
+  return { getText: () => text, unsubscribe };
+}
+
+/** Get the last assistant text from the completed session history. */
+function getLastAssistantText(session: AgentSession): string {
+  for (let i = session.messages.length - 1; i >= 0; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "assistant") continue;
+    const text = extractText(msg.content).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * Wire an AbortSignal to abort a session.
+ * Returns a cleanup function to remove the listener.
+ */
+function forwardAbortSignal(
+  session: AgentSession,
+  signal?: AbortSignal,
+): () => void {
+  if (!signal) return () => {};
+  const onAbort = (): void => {
+    void session.abort();
+  };
+  if (signal.aborted) {
+    onAbort();
+    return () => {};
+  }
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}
+
+function turnNeedsContinuation(event: Extract<AgentSessionEvent, { type: "turn_end" }>): boolean {
+  if (event.message.role !== "assistant") return false;
+  if (event.message.stopReason === "length") return true;
+  return event.message.content.some((content) => content.type === "toolCall");
+}
+
+function resolveTurnLoopOutcome(
+  signal: AbortSignal | undefined,
+  hardLimitRequiredAbort: boolean,
+): TurnLoopOutcome {
+  if (signal?.aborted) {
+    return isInvocationTimeout(signal.reason) ? "timeout" : "cancelled";
+  }
+  return hardLimitRequiredAbort ? "turn_limit" : "completed";
+}