pi-famulus 0.1.2 → 0.1.3

package/src/subagent/model-spec.ts

@@ -6,8 +6,23 @@
  * candidate set (scopedModels whitelist when non-empty, else all available).
  *
  * Spec grammar: `[provider/|provider:]id[:thinking]`
- *   - thinking suffix: minimal|low|medium|high|xhigh (unrecognized suffixes
- *     are treated as part of the id, e.g. OpenRouter's ":exacto")
+ *   - thinking suffix: one of VALID_THINKING_LEVELS (pi core parity;
+ *     src/thinking-levels.ts is the single source of truth). Unrecognized
+ *     suffixes are NOT silently kept in the id: when the full spec fails to
+ *     match, the resolver retries without the trailing ":suffix" and adapts
+ *     with a warning — the same semantics as pi's
+ *     parseModelPattern(allowInvalidThinkingLevelFallback). The retry only
+ *     fires on a full-spec no-match, so literal ids whose trailing ':segment'
+ *     is not a valid level (OpenRouter ":exacto") still win at exact match.
+ *     Note the converse: an id literally ending in a valid level (":high")
+ *     is read as a thinking override, never as a literal id.
+ *     A "provider:id" separator is never a thinking suffix: when the
+ *     trailing ':' is the spec's first separator and its prefix is a known
+ *     provider (case-insensitive; candidate.provider or the first '/' segment
+ *     of candidate.id), the colon is left in the base ("openai:off" /
+ *     "openai:max" / "openai:nonexistent" stay hard no-matches). Detection
+ *     runs before valid-level splitting so a recognized level cannot bypass
+ *     the guard. Bare "gpt-5.2:off" and "openai:gpt-5.2:off" still split.
  *   - provider prefix: "provider/id" or "provider:id" both accepted
  *   - bare id: exact unique match, else case-insensitive substring on id/name
  */
@@ -19,10 +34,24 @@ export interface ModelCandidate {
 }
 
 export type ModelResolution =
-  | { ok: true; provider: string; id: string; thinking?: string }
-  | { ok: false; error: "no-match" | "ambiguous"; candidates: string[]; thinking?: string };
+  | { ok: true; provider: string; id: string; thinking?: string; warning?: string }
+  | {
+      ok: false;
+      error: "no-match" | "ambiguous";
+      candidates: string[];
+      thinking?: string;
+      /** Set when a trailing ":suffix" was stripped and retried unsuccessfully. */
+      suffixHint?: string;
+    };
 
-const THINKING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh"]);
+/**
+ * Thinking levels pi core accepts — re-exported from the single source of
+ * truth (src/thinking-levels.ts) for convenience of resolver callers.
+ */
+export { VALID_THINKING_LEVELS } from "../thinking-levels";
+import { VALID_THINKING_LEVELS } from "../thinking-levels";
+
+const THINKING_LEVELS = new Set<string>(VALID_THINKING_LEVELS);
 
 function label(c: ModelCandidate): string {
   return `${c.provider}/${c.id}`;
@@ -49,10 +78,42 @@ function splitProviderPrefix(spec: string): { provider: string; id: string } | n
   return null;
 }
 
-export function resolveModelSpec(spec: string, candidates: ModelCandidate[]): ModelResolution {
-  const { base, thinking } = splitThinkingSuffix(spec.trim());
+/**
+ * Provider names the separator guard recognizes: each candidate's `provider`
+ * field, plus the first `/` segment of its id. OpenRouter ids look like
+ * `openai/gpt-5.2:exacto`; if the scoped whitelist omits the openai provider
+ * itself, that nested prefix still has to count, or `openai:nonexistent`
+ * retries as `openai` and unique-fuzzy-matches the OpenRouter id.
+ */
+function knownProviders(candidates: ModelCandidate[]): string[] {
+  const out: string[] = [];
+  for (const c of candidates) {
+    out.push(c.provider);
+    const slash = c.id.indexOf("/");
+    if (slash > 0) out.push(c.id.slice(0, slash));
+  }
+  return out;
+}
+
+/**
+ * True when the ':' at `idx` is the "provider:id" separator rather than a
+ * thinking suffix: it is the spec's first separator and the text before it
+ * names a known provider (case-insensitive). Stripping it would retry the
+ * bare provider name, which fuzzy-matches unrelated ids (e.g.
+ * "openai:nonexistent" → the OpenRouter id "openai/gpt-5.2:exacto") and
+ * silently drops the requested id.
+ */
+function isProviderSeparator(spec: string, idx: number, providers: readonly string[]): boolean {
+  const provider = spec.slice(0, idx);
+  if (/[/:]/.test(provider)) return false;
+  const needle = provider.toLowerCase();
+  return providers.some((p) => p.toLowerCase() === needle);
+}
+
+/** The three matching rules, shared by both resolution passes. */
+function matchBase(base: string, candidates: ModelCandidate[]): ModelResolution {
   if (base.length === 0) {
-    return { ok: false, error: "no-match", candidates: candidates.map(label), thinking };
+    return { ok: false, error: "no-match", candidates: candidates.map(label) };
   }
 
   // 1) provider-qualified exact match
@@ -61,17 +122,17 @@ export function resolveModelSpec(spec: string, candidates: ModelCandidate[]): Mo
     const hit = candidates.find(
       (c) => c.provider === qualified.provider && c.id === qualified.id,
     );
-    if (hit) return { ok: true, provider: hit.provider, id: hit.id, thinking };
+    if (hit) return { ok: true, provider: hit.provider, id: hit.id };
     // Fall through: maybe the whole thing is a bare id containing a separator.
   }
 
   // 2) bare-id exact match (must be unique across providers)
   const exact = candidates.filter((c) => c.id === base);
   if (exact.length === 1) {
-    return { ok: true, provider: exact[0].provider, id: exact[0].id, thinking };
+    return { ok: true, provider: exact[0].provider, id: exact[0].id };
   }
   if (exact.length > 1) {
-    return { ok: false, error: "ambiguous", candidates: exact.map(label), thinking };
+    return { ok: false, error: "ambiguous", candidates: exact.map(label) };
   }
 
   // 3) case-insensitive substring on id or display name
@@ -82,26 +143,83 @@ export function resolveModelSpec(spec: string, candidates: ModelCandidate[]): Mo
       (c.name !== undefined && c.name.toLowerCase().includes(needle)),
   );
   if (fuzzy.length === 1) {
-    return { ok: true, provider: fuzzy[0].provider, id: fuzzy[0].id, thinking };
+    return { ok: true, provider: fuzzy[0].provider, id: fuzzy[0].id };
   }
   if (fuzzy.length > 1) {
-    return { ok: false, error: "ambiguous", candidates: fuzzy.map(label), thinking };
+    return { ok: false, error: "ambiguous", candidates: fuzzy.map(label) };
+  }
+  return { ok: false, error: "no-match", candidates: candidates.map(label) };
+}
+
+export function resolveModelSpec(spec: string, candidates: ModelCandidate[]): ModelResolution {
+  const trimmed = spec.trim();
+  const providers = knownProviders(candidates);
+  const lastColon = trimmed.lastIndexOf(":");
+  // Known-provider / first-colon detection runs BEFORE valid thinking-suffix
+  // splitting. Otherwise a recognized level (off/max, newly in this PR's
+  // parity list) strips the separator, matchBase("openai") fuzzy-matches an
+  // unrelated id, and the retry guard at the bottom never sees the spec.
+  const skipThinkingSplit =
+    lastColon > 0 &&
+    lastColon < trimmed.length - 1 &&
+    isProviderSeparator(trimmed, lastColon, providers);
+  const { base, thinking } = skipThinkingSplit
+    ? { base: trimmed, thinking: undefined }
+    : splitThinkingSuffix(trimmed);
+  const first = matchBase(base, candidates);
+  if (first.ok || thinking !== undefined || first.error === "ambiguous") {
+    // Success, a valid thinking suffix, or an ambiguity: all final. Ambiguity
+    // is semantic, not syntax — report it instead of adapting past it.
+    return { ...first, thinking };
+  }
+
+  // Unknown trailing ":suffix" on a no-match: mirror pi core's
+  // parseModelPattern(allowInvalidThinkingLevelFallback) — strip the suffix,
+  // retry, and adapt with a warning instead of failing the whole call. The
+  // retry only fires when the full spec matched nothing, so literal ids
+  // containing a colon (OpenRouter ":exacto") are unaffected.
+  const idx = trimmed.lastIndexOf(":");
+  if (idx <= 0 || idx === trimmed.length - 1) return first;
+  if (isProviderSeparator(trimmed, idx, providers)) return first;
+  const suffix = trimmed.slice(idx + 1);
+  const retriedBase = trimmed.slice(0, idx);
+  const retried = matchBase(retriedBase, candidates);
+  if (retried.ok) {
+    return {
+      ...retried,
+      warning:
+        `unknown thinking level "${suffix}" in model spec "${trimmed}"; ` +
+        `using the model's default thinking ` +
+        `(valid levels: ${VALID_THINKING_LEVELS.join(", ")})`,
+    };
   }
-  return { ok: false, error: "no-match", candidates: candidates.map(label), thinking };
+  return {
+    ...retried,
+    suffixHint:
+      `":${suffix}" is not a valid thinking level ` +
+      `(valid: ${VALID_THINKING_LEVELS.join(", ")}); ` +
+      `retried without it as "${retriedBase}"`,
+  };
 }
 
 /** Render a resolution failure as an actionable error message. */
 export function modelResolutionError(spec: string, res: ModelResolution & { ok: false }): string {
   const list = res.candidates.slice(0, 20).join(", ");
   const more = res.candidates.length > 20 ? `, … +${res.candidates.length - 20} more` : "";
+  const hint = res.suffixHint ? ` (${res.suffixHint})` : "";
   if (res.error === "ambiguous") {
+    // With a suffixHint the ambiguity belongs to the retried base, not the
+    // full spec — say so, and name the dropped suffix either way.
     return (
-      `model spec "${spec}" is ambiguous (matches: ${list}${more}). ` +
+      (res.suffixHint
+        ? `model spec "${spec}" is ambiguous on the retried base`
+        : `model spec "${spec}" is ambiguous`) +
+      ` (matches: ${list}${more}).${hint} ` +
       `Qualify with "provider/<id>".`
     );
   }
   return (
-    `model spec "${spec}" matched nothing. ` +
+    `model spec "${spec}" matched nothing.${hint} ` +
     `Available: ${list || "none"}${more}. ` +
     `Use subagent({action:"models"}) to list selectable models.`
   );

package/src/subagent/overrun.ts

@@ -0,0 +1,176 @@
+/**
+ * Overrun wake inputs (design doc §4.6 child lifecycle): which foreground
+ * shell each child is blocked on, and the builder that turns a runner
+ * overrun tick into the wake payload.
+ *
+ * Zero pi dependency; the output-file stat is injected so tests can drive it.
+ */
+import { formatSubagentOverrun, type SubagentOverrunInfo } from "../format";
+import type { FormattedWake, OverrunShell } from "../wake";
+import type { ConversationTurn } from "./types";
+
+export interface ChildShell {
+  taskId: string;
+  command: string;
+  startedAt: number;
+  outputPath: string;
+}
+
+/** Output that changed within this window counts as growing on a first reading. */
+export const OUTPUT_GROWING_WINDOW_MS = 60_000;
+
+/**
+ * Foreground shells per child. Child bash records a shell when the manager
+ * starts it and clears it when the call returns or throws; a child runs at
+ * most one foreground shell at a time (no background bash in children).
+ */
+export class ChildShellTracker {
+  private readonly shells = new Map<string, ChildShell>();
+  /** Output size at the previous overrun reading, per task. */
+  private readonly sizes = new Map<string, number>();
+
+  start(childId: string, shell: ChildShell): void {
+    this.shells.set(childId, shell);
+  }
+
+  end(childId: string, taskId: string): void {
+    if (this.shells.get(childId)?.taskId === taskId) this.shells.delete(childId);
+    this.sizes.delete(taskId);
+  }
+
+  current(childId: string): ChildShell | undefined {
+    return this.shells.get(childId);
+  }
+
+  /** Record a size reading and return the previous one for the same task. */
+  swapSize(taskId: string, size: number): number | undefined {
+    const previous = this.sizes.get(taskId);
+    this.sizes.set(taskId, size);
+    return previous;
+  }
+}
+
+/** What the runner knows at an overrun tick. */
+export interface OverrunTick {
+  childId: string;
+  elapsedMs: number;
+  budgetMs: number;
+  reminder: number;
+  nextReminderMs: number;
+  lastEventAt: number;
+  /** Time left until the opt-in hard ceiling aborts the child; null when none is set. */
+  hardRemainingMs: number | null;
+}
+
+export interface OverrunInfoDeps {
+  now: () => number;
+  /** Run id and display name; undefined once the child's run is gone. */
+  lookupChild: (childId: string) => { runId: string; name: string } | undefined;
+  conversation: (childId: string) => ConversationTurn[];
+  shells: ChildShellTracker;
+  /** Output file size and mtime; null when it cannot be read. */
+  stat: (path: string) => { size: number; mtimeMs: number } | null;
+}
+
+function lastActivityText(turns: ConversationTurn[]): string {
+  const last = turns[turns.length - 1];
+  return last ? `${last.role}: ${last.text}` : "";
+}
+
+function describeShell(deps: OverrunInfoDeps, shell: ChildShell): OverrunShell {
+  const now = deps.now();
+  const st = deps.stat(shell.outputPath);
+  let outputBytes: number | null = null;
+  let outputIdleMs: number | null = null;
+  let growing: boolean | null = null;
+  if (st) {
+    outputBytes = st.size;
+    outputIdleMs = Math.max(0, now - st.mtimeMs);
+    const previous = deps.shells.swapSize(shell.taskId, st.size);
+    growing = (previous !== undefined && st.size > previous) || outputIdleMs < OUTPUT_GROWING_WINDOW_MS;
+  }
+  return {
+    taskId: shell.taskId,
+    command: shell.command,
+    elapsedMs: Math.max(0, now - shell.startedAt),
+    outputPath: shell.outputPath,
+    outputBytes,
+    outputIdleMs,
+    growing,
+  };
+}
+
+export function buildOverrunInfo(deps: OverrunInfoDeps, tick: OverrunTick): SubagentOverrunInfo | undefined {
+  const child = deps.lookupChild(tick.childId);
+  if (!child) return undefined;
+  const shell = deps.shells.current(tick.childId);
+  return {
+    runId: child.runId,
+    childId: tick.childId,
+    name: child.name,
+    elapsedMs: tick.elapsedMs,
+    budgetMs: tick.budgetMs,
+    reminder: tick.reminder,
+    nextReminderMs: tick.nextReminderMs,
+    ...(tick.hardRemainingMs !== null ? { hardCeilingMs: tick.hardRemainingMs } : {}),
+    lastActivity: {
+      agoMs: Math.max(0, deps.now() - tick.lastEventAt),
+      text: lastActivityText(deps.conversation(tick.childId)),
+    },
+    ...(shell ? { shell: describeShell(deps, shell) } : {}),
+  };
+}
+
+export interface OverrunNotifierDeps {
+  now: () => number;
+  registry: {
+    list(): { runId: string; children: { childId: string; name: string }[] }[];
+    handle(childId: string): { conversation(): ConversationTurn[] } | undefined;
+  };
+  shells: ChildShellTracker;
+  stat: OverrunInfoDeps["stat"];
+  /** Parent wake (NotifyCenter.notify). */
+  notify: (wake: FormattedWake) => void;
+  logEvent: (type: string, fields: Record<string, unknown>) => void;
+}
+
+/**
+ * The runner's onOverrun: build the payload, log `agent.overrun`, wake the
+ * parent. A child whose run is already gone produces neither.
+ */
+export function createOverrunNotifier(deps: OverrunNotifierDeps): (tick: OverrunTick) => void {
+  const infoDeps: OverrunInfoDeps = {
+    now: deps.now,
+    lookupChild: (childId) => {
+      for (const run of deps.registry.list()) {
+        const child = run.children.find((c) => c.childId === childId);
+        if (child) return { runId: run.runId, name: child.name };
+      }
+      return undefined;
+    },
+    conversation: (childId) => deps.registry.handle(childId)?.conversation() ?? [],
+    shells: deps.shells,
+    stat: deps.stat,
+  };
+  return (tick) => {
+    const info = buildOverrunInfo(infoDeps, tick);
+    if (!info) return;
+    const shell = info.shell;
+    deps.logEvent("agent.overrun", {
+      child_id: info.childId,
+      run_id: info.runId,
+      reminder: info.reminder,
+      elapsed_ms: info.elapsedMs,
+      budget_ms: info.budgetMs,
+      ...(shell
+        ? {
+            shell_task_id: shell.taskId,
+            shell_elapsed_ms: shell.elapsedMs,
+            ...(shell.outputBytes !== null ? { output_bytes: shell.outputBytes } : {}),
+            ...(shell.growing !== null ? { growing: shell.growing } : {}),
+          }
+        : {}),
+    });
+    deps.notify(formatSubagentOverrun(info));
+  };
+}

package/src/subagent/pi-runtime.ts

@@ -137,13 +137,13 @@ function resolveModel(deps: PiRuntimeDeps, req: ChildRunRequest): ResolvedModel
     if (!res.ok) throw new Error(modelResolutionError(req.model, res));
     const model = findModel(res.provider, res.id);
     if (!model) throw new Error(`model ${res.provider}/${res.id} is not usable in this session`);
-    return { model, thinkingOverride: res.thinking };
+    return { model, thinkingOverride: res.thinking, warning: res.warning };
   }
   if (req.agent.model !== undefined) {
     const res = resolveModelSpec(req.agent.model, candidates);
     if (res.ok) {
       const model = findModel(res.provider, res.id);
-      if (model) return { model, thinkingOverride: res.thinking };
+      if (model) return { model, thinkingOverride: res.thinking, warning: res.warning };
     }
     return {
       model: deps.getParentModel(),

package/src/subagent/registry.ts

@@ -10,8 +10,10 @@
  * - lineage: v1 = same runId.
  *
  * Wiring contract: the runner must be constructed with
- * `acquire: (req) => registry.admitChild(req.childId)` so every generation
- * (initial start and resume) passes through admission. startChild() wires the
+ * `acquire: (req, ticket) => registry.admitChild(req.childId, ticket)` so every
+ * generation (initial start and resume) passes through admission. Forward the
+ * ticket: without it admitChild falls back to the handle's current status and
+ * a stale queued request can admit a newer resume. startChild() wires the
  * first generation's result; admitChild() wires subsequent generations.
  *
  * Zero pi dependency.
@@ -47,6 +49,8 @@ export interface RunRecord {
     result?: ChildResult;
     startedAt: number;
     endedAt?: number;
+    /** User turns so far: 1 for the launch, +1 per accepted resume. */
+    turn?: number;
   }[];
   status: "running" | "completed" | "partial" | "failed" | "interrupted";
   createdAt: number;
@@ -109,6 +113,7 @@ interface InternalChild {
   result?: ChildResult;
   startedAt: number;
   endedAt?: number;
+  turn: number;
   handle?: ChildHandle;
   shouldStart?: () => boolean;
 }
@@ -157,6 +162,10 @@ class FailedChildHandle implements ChildHandle {
     return Promise.reject(this.dead());
   }
 
+  extend(): never {
+    throw this.dead();
+  }
+
   interrupt(): Promise<void> {
     return Promise.resolve();
   }
@@ -303,6 +312,7 @@ export class SubagentRegistry implements RunRegistry {
       agent: info.agent,
       status: "pending",
       startedAt: this.now(),
+      turn: 1,
     };
     run.children.push(child);
     this.children.set(child.childId, child);
@@ -360,7 +370,7 @@ export class SubagentRegistry implements RunRegistry {
    * and wires result settlement for resumed generations. Returns the slot
    * releaser.
    */
-  async admitChild(childId: string): Promise<() => void> {
+  async admitChild(childId: string, ticket?: { current: () => boolean }): Promise<() => void> {
     await this.acquireSlot();
     let released = false;
     const release = () => {
@@ -377,6 +387,15 @@ export class SubagentRegistry implements RunRegistry {
       release();
       throw new ChildCancelledError();
     }
+    // The generation that queued this request settled while it waited
+    // (interrupt/dispose; maybe a newer resume is queued behind other
+    // children): hand the slot on, without touching the child's status.
+    // Without a ticket, fall back to the handle's status.
+    const stale = ticket ? !ticket.current() : (child.handle?.status() ?? "pending") !== "pending";
+    if (stale) {
+      release();
+      throw new ChildCancelledError("settled while queued");
+    }
     this.transitionChild(child, "running");
     const handle = child.handle;
     if (handle) {
@@ -387,6 +406,64 @@ export class SubagentRegistry implements RunRegistry {
     return release;
   }
 
+  /**
+   * Resume an ended child: a new user turn on its session. Returns once the
+   * request is accepted; admission runs in the background (design.md §4.6
+   * "Child lifecycle", resume rows). Until a slot is granted the child is
+   * pending. `queuedBehind` is null when a slot was free at request time,
+   * otherwise how many children were already waiting for one.
+   */
+  async resumeChild(
+    childId: string,
+    message: string,
+    opts: { timeoutMs?: number } = {},
+  ): Promise<{ queuedBehind: number | null }> {
+    const child = this.children.get(childId);
+    if (!child) throw new Error(`unknown child ${childId}`);
+    const handle = child.handle;
+    if (!handle) throw new Error(`subagent ${childId} has no live session to resume`);
+    const queuedBehind = this.activeSlots >= this.maxChildren ? this.slotWaiters.length : null;
+    const previous = {
+      status: child.status,
+      result: child.result,
+      startedAt: child.startedAt,
+      endedAt: child.endedAt,
+    };
+    const accepted = handle.resume(message, opts);
+    // Mark the child queued before awaiting: with a free slot, admitChild's
+    // continuation can run first and move it to running, which must win.
+    child.status = "pending";
+    child.result = undefined;
+    child.endedAt = undefined;
+    child.startedAt = this.now();
+    child.turn += 1;
+    try {
+      await accepted;
+    } catch (err) {
+      // Undo this attempt's +1 even if a concurrent accepted resume has
+      // already moved the child to running (the pending guard would skip).
+      child.turn -= 1;
+      if (child.status === "pending") {
+        child.status = previous.status;
+        child.result = previous.result;
+        child.startedAt = previous.startedAt;
+        child.endedAt = previous.endedAt;
+      }
+      throw err;
+    }
+    // Wired at request time, not admission: a turn that never gets a slot
+    // (interrupt/dispose while queued, abort drain bound) still settles here.
+    handle.result.then((result) => this.settleChild(childId, result));
+    if (child.status === "pending") {
+      const run = this.runs.get(child.runId);
+      if (run) {
+        this.recomputeRunStatus(run);
+        this.emit(run);
+      }
+    }
+    return { queuedBehind };
+  }
+
   /** Current generation's result promise for a child (post-resume aware). */
   getResult(childId: string): Promise<ChildResult> | undefined {
     return this.children.get(childId)?.handle?.result;
@@ -570,6 +647,7 @@ function snapshot(run: InternalRun): RunRecord {
       result: c.result,
       startedAt: c.startedAt,
       endedAt: c.endedAt,
+      turn: c.turn,
     })),
   };
 }