toolnexus 0.9.4 → 0.10.0

package/dist/client.d.ts

@@ -44,6 +44,24 @@ export interface ClientOptions {
     /** §8 Gap 2. HTTP transport for LLM requests (retries included). Omit ⇒ global fetch. Scope is the
      * LLM path only; MCP transports use the SDK's own client. */
     fetch?: typeof fetch;
+    /** §8 Resilience. Classify each LLM-call failure into "retry" or "fail". Omit ⇒ the default
+     * classifier (retryable status/network within budget ⇒ retry, else fail) — byte-identical to
+     * today. A "retry" is always bounded by `retries`; the classifier cannot loop unbounded.
+     * There is no "suspend" tier — suspension (§10) stays a user-action pause, not an error path. */
+    onError?: (info: ErrorInfo) => ErrorTier;
+}
+/** §8 Resilience. What to do with a failed LLM call. */
+export type ErrorTier = "retry" | "fail";
+/** §8 Resilience. Context passed to `onError` for each failed LLM attempt. */
+export interface ErrorInfo {
+    /** The thrown network/transport error, when the failure was not an HTTP response. */
+    error?: unknown;
+    /** The HTTP status, when the failure was a non-ok response. */
+    status?: number;
+    /** Zero-based attempt index (0 = first try). */
+    attempt: number;
+    /** Whether `status`/the error is in the default retryable set (429/5xx/network). */
+    retryable: boolean;
 }
 /**
  * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
@@ -166,10 +184,14 @@ export interface RunResult {
     usage: Usage;
     /** The model used. */
     model: string;
-    /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
-    status: "done" | "pending";
+    /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10);
+     * "incomplete" iff a limit stopped the run loudly (§7D) — a maxTurns stop with no final
+     * text is never a silent "done". */
+    status: "done" | "pending" | "incomplete";
     /** The unresolved suspension — present iff status === "pending" (§10). */
     pending?: Request;
+    /** The limit that stopped the run (e.g. "maxTurns") — present iff status === "incomplete". */
+    limit?: string;
 }
 /** Events yielded by client.stream(). */
 export type StreamEvent = {
@@ -224,7 +246,8 @@ export declare class Client {
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */
     private emit;
-    /** Emit the terminal `run` metric event and build the RunResult. */
+    /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
+     * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
     private endRun;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;
@@ -263,7 +286,8 @@ export declare class Client {
     private system;
     /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
     private makeSignal;
-    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal. */
+    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+     * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;

package/dist/client.js

@@ -213,10 +213,11 @@ export class Client {
         this.registry.record(ev);
         this.opts.onMetric?.(ev);
     }
-    /** Emit the terminal `run` metric event and build the RunResult. */
-    endRun(runStart, text, messages, toolCalls, turns, usage) {
+    /** Emit the terminal `run` metric event and build the RunResult. `exhausted` marks a
+     * maxTurns loop exit — with no final text that is a LOUD "incomplete", never "done" (§7D). */
+    endRun(runStart, text, messages, toolCalls, turns, usage, exhausted = false) {
         this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
-        return this.result(text, messages, toolCalls, turns, usage);
+        return this.result(text, messages, toolCalls, turns, usage, exhausted);
     }
     /** Emit a `run` error metric event (once, on a thrown run). */
     emitRunError(runStart, toolCalls, turns, usage, e) {
@@ -291,16 +292,24 @@ export class Client {
         }
         return ctrl.signal;
     }
-    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal. */
+    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+     * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
     async llmFetch(url, init, signal) {
         const retries = this.opts.retries ?? 2;
         const base = this.opts.retryBaseMs ?? 500;
+        // Default classifier = today's behavior, expressed as an onError. A "retry" is always
+        // capped by the budget below (attempt === retries stops regardless of the classifier).
+        const classify = this.opts.onError ?? ((info) => (info.retryable ? "retry" : "fail"));
         let lastErr;
         for (let attempt = 0; attempt <= retries; attempt++) {
             try {
                 const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
-                if (res.ok || !RETRYABLE.has(res.status) || attempt === retries)
+                if (res.ok)
                     return res;
+                const retryable = RETRYABLE.has(res.status);
+                const tier = classify({ status: res.status, attempt, retryable });
+                if (tier === "fail" || attempt === retries)
+                    return res; // caller surfaces the non-ok status
                 const ra = Number(res.headers.get("retry-after"));
                 await delay(ra ? ra * 1000 : base * 2 ** attempt + Math.random() * 100, signal);
             }
@@ -308,7 +317,8 @@ export class Client {
                 if (signal.aborted)
                     throw e; // abort/timeout: don't retry
                 lastErr = e;
-                if (attempt === retries)
+                const tier = classify({ error: e, attempt, retryable: true });
+                if (tier === "fail" || attempt === retries)
                     throw e;
                 await delay(base * 2 ** attempt + Math.random() * 100, signal);
             }
@@ -427,15 +437,19 @@ export class Client {
                         return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage);
                 }
             }
-            return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage);
+            return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true);
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);
             throw e;
         }
     }
-    result(text, messages, toolCalls, turns, usage) {
-        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" };
+    result(text, messages, toolCalls, turns, usage, exhausted = false) {
+        const incomplete = exhausted && text === "";
+        const r = { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: incomplete ? "incomplete" : "done" };
+        if (incomplete)
+            r.limit = "maxTurns";
+        return r;
     }
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
     pendingRun(runStart, request, messages, toolCalls, turns, usage) {
@@ -536,7 +550,7 @@ export class Client {
                 if (halted)
                     return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
             }
-            return this.endRun(runStart, "", messages, toolCalls, turns, usage);
+            return this.endRun(runStart, "", messages, toolCalls, turns, usage, true);
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);
@@ -646,7 +660,7 @@ export class Client {
                     yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
                 }
             }
-            yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage) };
+            yield { type: "done", result: this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);
@@ -755,7 +769,7 @@ export class Client {
                 }
                 messages.push({ role: "user", content: results });
             }
-            yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage) };
+            yield { type: "done", result: this.endRun(runStart, "", messages, toolCalls, turns, usage, true) };
         }
         catch (e) {
             this.emitRunError(runStart, toolCalls, turns, usage, e);

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * as agents from "./agents/index.js";

package/dist/index.js

@@ -10,3 +10,4 @@ export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";
+export * as agents from "./agents/index.js";

package/dist/toolkit.d.ts

@@ -18,6 +18,13 @@ export interface ToolkitOptions {
     skillProvider?: () => SkillDef[] | Promise<SkillDef[]>;
     /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
     skillsFilter?: Record<string, boolean>;
+    /** Drop tools by their FINAL exposed name across every source (MCP `server_tool`, builtins,
+     * native, a2a, extras), applied after aggregation — the simple "just turn these off" list.
+     * Empty/undefined ⇒ nothing disabled. Composes with builtins/skillsFilter/server allowlists. */
+    disableTools?: string[];
+    /** Drop skills by name from the `skill` catalog — sugar over a drop-list in `skillsFilter`
+     * (each name folded in as `false`, without overriding an explicit filter entry). */
+    disableSkills?: string[];
     /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
     skillSampleLimit?: number;
     extraTools?: Tool[];

package/dist/toolkit.js

@@ -14,7 +14,9 @@ export class Toolkit {
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
     a2aConfig, 
     /** MCP serve profile read from a top-level `mcpServer` config block. */
-    mcpServerConfig) {
+    mcpServerConfig, 
+    /** Final-name drop-list (§4A) applied across every source after aggregation. */
+    disableTools = []) {
         this.mcp = mcp;
         this.skill = skill;
         this.a2aConfig = a2aConfig;
@@ -24,8 +26,11 @@ export class Toolkit {
         // front, then apply the normal first-wins dedupe for MCP/skill/agents/extras.
         const extraNames = new Set(extraTools.map((t) => t.name));
         const activeBuiltins = builtins.filter((b) => !extraNames.has(b.name));
+        const disabled = new Set(disableTools);
         const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...activeBuiltins, ...agents, ...extraTools];
         for (const t of all) {
+            if (disabled.has(t.name))
+                continue; // §4A drop-list by final exposed name
             if (this.byName.has(t.name)) {
                 console.warn(`[toolnexus] duplicate tool name "${t.name}" — keeping first`);
                 continue;
@@ -51,10 +56,15 @@ export class Toolkit {
                 }
             }
             const dataDefs = [...(opts.skills ?? []), ...providerDefs];
+            // disableSkills is sugar over a skillsFilter drop-list: fold each name in as false
+            // WITHOUT overriding an explicit skillsFilter entry (explicit entries win).
+            const filter = opts.disableSkills && opts.disableSkills.length > 0
+                ? { ...Object.fromEntries(opts.disableSkills.map((n) => [n, false])), ...opts.skillsFilter }
+                : opts.skillsFilter;
             skill = loadSkills({
                 dirs: opts.skillsDir,
                 skills: dataDefs.length > 0 ? dataDefs : undefined,
-                filter: opts.skillsFilter,
+                filter,
                 sampleLimit: opts.skillSampleLimit,
             });
         }
@@ -93,7 +103,7 @@ export class Toolkit {
         if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "mcpServer" in opts.mcpConfig) {
             mcpServerConfig = opts.mcpConfig.mcpServer;
         }
-        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig);
+        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig, opts.disableTools ?? []);
     }
     tools() {
         return [...this.byName.values()];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/home.test.ts test/compaction.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [

package/src/agents/agent.ts

@@ -0,0 +1,129 @@
+/**
+ * Level-1 subagent surface — SPEC.md §7D.
+ *
+ * One new noun: `agent(name, spec)`. An Agent is (identity/system prompt × a
+ * filtered toolkit view × the shipped client loop), and — the §7A/§7B axiom
+ * completed locally — an Agent IS a Tool: `asTool()` bridges it into the classic
+ * API's `extraTools`; `run()` executes one-shot against a private runtime.
+ * Everything compiles down to the six host verbs in runtime.ts.
+ */
+import fs from "node:fs"
+import { defineTool } from "../native.js"
+import type { Answer, Request, Tool } from "../types.js"
+import { AgentRuntime, isVerbError, type AgentDef, type Budget, type Handle, type RuntimeOptions, type TaskResult } from "./runtime.js"
+
+/** The declarative agent spec (§7D Level-1 surface). */
+export interface AgentSpec {
+  /** Required routing description — what a delegating model sees. */
+  does: string
+  /** The toolkit VIEW for this agent (scoping is the security model). */
+  uses?: { tools?: Tool[] }
+  /** Identity: inline soul text (becomes the system prompt). */
+  soul?: string
+  /** Path form of `soul` — read when the registry is built. */
+  soulFile?: string
+  /** Declaring agents here IS the subagent wiring: they become the `task`
+   * tool's only reachable targets. No team ⇒ no `task` tool. */
+  team?: Agent[]
+  budget?: Budget
+  /** Model id; default "inherit" (the runtime's `llm.model`). */
+  model?: string
+  /** §10 interpreter authority for this agent's subtree. */
+  waitFor?: (request: Request) => Promise<Answer>
+  onSpawn?: AgentDef["onSpawn"]
+  onClose?: AgentDef["onClose"]
+}
+
+/** Runtime options for a one-shot `run`/`asTool` (the registry is derived). */
+export type AgentRunOptions = Omit<RuntimeOptions, "registry">
+
+/** A one-shot run's result, with the runtime attached for durable resume. */
+export interface AgentRunResult extends TaskResult {
+  /** The runtime that ran this agent — call `runtime.resume(answer)` after a
+   * `status:"pending"` result to continue from the checkpoint. */
+  runtime: AgentRuntime
+}
+
+export class Agent {
+  constructor(readonly name: string, readonly spec: AgentSpec) {}
+
+  /**
+   * Collect this agent plus its transitive team graph into a runtime registry —
+   * the registry IS the reachable graph; unreachable agents are not present.
+   */
+  registry(acc: Record<string, AgentDef> = {}): Record<string, AgentDef> {
+    if (acc[this.name]) return acc
+    let soul = this.spec.soul ?? ""
+    if (this.spec.soulFile) soul = fs.readFileSync(this.spec.soulFile, "utf8")
+    acc[this.name] = {
+      name: this.name,
+      does: this.spec.does,
+      soul,
+      model: this.spec.model ?? "inherit",
+      tools: this.spec.uses?.tools,
+      team: (this.spec.team ?? []).map((a) => a.name),
+      budget: this.spec.budget,
+      waitFor: this.spec.waitFor,
+      onSpawn: this.spec.onSpawn,
+      onClose: this.spec.onClose,
+    }
+    for (const t of this.spec.team ?? []) t.registry(acc)
+    return acc
+  }
+
+  /** Build a runtime scoped to this agent's reachable team graph. */
+  createRuntime(opts: AgentRunOptions = {}): AgentRuntime {
+    return new AgentRuntime({ ...opts, registry: this.registry() })
+  }
+
+  /**
+   * Level 1: one-shot. Builds a runtime, runs this agent to completion, and tears
+   * the tree down — unless the run suspends durably (`status:"pending"`), in which
+   * case the tree stays parked and `result.runtime.resume(answer)` continues it.
+   */
+  async run(prompt: string, opts: AgentRunOptions = {}): Promise<AgentRunResult> {
+    const runtime = this.createRuntime(opts)
+    const h = runtime.spawn(runtime.root, this.name)
+    if (isVerbError(h)) {
+      return { text: h.error, isError: true, status: "error", turns: 0, totalTokens: 0, runtime }
+    }
+    const woke = runtime.wake(h, prompt)
+    if (!woke.ok) {
+      return { ...(await runtime.wait(h as Handle)), runtime }
+    }
+    const r = await runtime.wait(h as Handle)
+    if (r.status !== "pending") await runtime.close(runtime.root)
+    return { ...r, runtime }
+  }
+
+  /**
+   * The bridge: an Agent IS a Tool. Drop the result into the classic API's
+   * `extraTools`; the agent's own loop runs in isolation and the classic run
+   * receives one tool result carrying only the final text + metadata
+   * `{agent, turns, totalTokens}`.
+   */
+  asTool(opts: AgentRunOptions = {}): Tool {
+    return defineTool({
+      name: this.name,
+      description: this.spec.does,
+      inputSchema: {
+        type: "object",
+        properties: { prompt: { type: "string", description: "The task for this agent" } },
+        required: ["prompt"],
+      },
+      run: async (args: Record<string, unknown>) => {
+        const r = await this.run(String(args.prompt), opts)
+        return {
+          output: r.text,
+          isError: r.isError,
+          metadata: { agent: this.name, turns: r.turns, totalTokens: r.totalTokens },
+        }
+      },
+    })
+  }
+}
+
+/** The one new noun: define an agent. */
+export function agent(name: string, spec: AgentSpec): Agent {
+  return new Agent(name, spec)
+}

package/src/agents/compaction.ts

@@ -0,0 +1,148 @@
+/**
+ * Context compaction (SPEC.md §7F) — keep a long-lived agent under budget.
+ *
+ * A long-running agent grows its transcript until it overflows the model's window.
+ * `compactor(opts)` returns a **`beforeLLM` hook** (§8) that summarizes the older
+ * transcript and keeps a recent tail. It rides the existing seam: the client loop
+ * applies a `beforeLLM` message rewrite by *replacing* the working transcript, and
+ * that array flows on into `RunResult.messages` and the `ConversationStore`. So
+ * compaction is a pure `messages → messages` helper and adds **no loop behavior** —
+ * it is the canonical use of the §8 `beforeLLM` hook.
+ *
+ * Invariants (SPEC §7F):
+ *   1. At/below `maxTokens` the hook is a **no-op** — it returns nothing and the run
+ *      is byte-identical to a run with no compactor.
+ *   2. **Tool-pair safety** — the retained tail always begins at a `user` turn, so no
+ *      `tool` message is ever orphaned from the `assistant` carrying its `tool_call_id`.
+ *   3. The **leading system prompt** (identity / soul / skills) is preserved verbatim;
+ *      only the body between it and the tail is summarized.
+ *
+ *   import { agents } from "toolnexus"
+ *   const client = createClient({
+ *     …,
+ *     hooks: { beforeLLM: agents.compactor({ maxTokens: 120_000, summarize }) },
+ *   })
+ */
+
+/**
+ * A chat message in the working transcript. Structural and provider-neutral — only the
+ * fields compaction reasons about are named; anything else on the message is carried
+ * through untouched.
+ */
+export interface Message {
+  role: string
+  content?: unknown
+  tool_calls?: unknown[]
+  tool_call_id?: string
+  [key: string]: unknown
+}
+
+/**
+ * Cheap, deterministic token estimate: `ceil(chars/4)` over each message's JSON
+ * serialization, summed. This is an *estimator*, not a tokenizer — exactness is the
+ * host's call. Override via `CompactorOptions.countTokens` for a real tokenizer.
+ */
+export function estimateTokens(messages: Message[]): number {
+  let total = 0
+  for (const m of messages) total += Math.ceil(JSON.stringify(m).length / 4)
+  return total
+}
+
+/** Options for {@link compactor}. */
+export interface CompactorOptions {
+  /** Compact only when the transcript estimate exceeds this; at/below ⇒ no-op. */
+  maxTokens: number
+  /** Keep at least this many tokens of the most recent tail. Default `maxTokens/2`. */
+  keepTail?: number
+  /** Produce a summary of the older messages. MAY call an LLM (async). Required. */
+  summarize: (older: Message[]) => Promise<string> | string
+  /** Token estimator; default `ceil(chars/4)` summed over messages. */
+  countTokens?: (messages: Message[]) => number
+  /**
+   * When set, inject a pre-compact system reminder telling the model to persist
+   * durable facts via the §7E `memory` tool before the head is summarized. Off by
+   * default. Composes with the memory builtin.
+   */
+  flushToMemory?: boolean
+}
+
+/** The event a `beforeLLM` hook receives (§8). */
+export interface BeforeLLMEvent {
+  messages: Message[]
+  tools: unknown[]
+  model: string
+  turn: number
+}
+
+/** The system reminder injected when `flushToMemory` is set. */
+const FLUSH_TO_MEMORY_REMINDER =
+  "Before continuing: if anything from earlier is worth keeping, save it with the memory tool now — the earlier transcript is about to be summarized."
+
+/** Prefix on the summary system message; hosts/tests key off this to detect a compaction. */
+const SUMMARY_PREFIX = "[Summary of earlier conversation]\n"
+
+/**
+ * Build a `beforeLLM` hook (§8) that compacts the transcript once it exceeds
+ * `maxTokens`. Below budget it returns nothing (a byte-identical no-op); above it, it
+ * replaces the transcript with `[leading system prompt, summary system message,
+ * (flush reminder?), …recent tail]`, splitting at a clean `user` boundary so tool
+ * groups are never broken.
+ */
+export function compactor(
+  opts: CompactorOptions,
+): (ev: BeforeLLMEvent) => Promise<{ messages: Message[] } | undefined> {
+  const count = opts.countTokens ?? estimateTokens
+  const keepTail = opts.keepTail ?? Math.floor(opts.maxTokens / 2)
+
+  return async (ev: BeforeLLMEvent): Promise<{ messages: Message[] } | undefined> => {
+    const msgs = ev.messages
+    if (count(msgs) <= opts.maxTokens) return undefined // under budget → no-op
+
+    // Preserve a leading system prompt verbatim (identity / soul / skills — never summarized).
+    const headEnd = msgs[0]?.role === "system" ? 1 : 0
+    const system = msgs.slice(0, headEnd)
+
+    const split = findTailStart(msgs, headEnd, keepTail, count)
+    if (split <= headEnd) return undefined // nothing safely compactible
+
+    const older = msgs.slice(headEnd, split)
+    if (older.length === 0) return undefined
+    const tail = msgs.slice(split)
+
+    const flushNote: Message[] = opts.flushToMemory
+      ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
+      : []
+
+    const summary = await opts.summarize(older)
+    const summaryMsg: Message = { role: "system", content: `${SUMMARY_PREFIX}${summary}` }
+
+    return { messages: [...system, summaryMsg, ...flushNote, ...tail] }
+  }
+}
+
+/**
+ * Locate the index where the retained tail begins. Tool-pair safety requires the tail
+ * to start at a `user` turn: the largest user-boundary tail that still fits `keepTail`.
+ * If no user boundary fits within `keepTail`, fall back to the most recent user turn
+ * (favoring safety over size). Returns `msgs.length` (no tail) only when there is no
+ * user turn after the head at all.
+ */
+function findTailStart(
+  msgs: Message[],
+  headEnd: number,
+  keepTail: number,
+  count: (messages: Message[]) => number,
+): number {
+  let split = msgs.length
+  for (let i = msgs.length - 1; i > headEnd; i--) {
+    if (count(msgs.slice(i)) > keepTail) break
+    if (msgs[i].role === "user") split = i
+  }
+  if (split !== msgs.length) return split
+
+  // No user boundary fit within keepTail — extend back to the most recent user turn.
+  for (let i = msgs.length - 1; i > headEnd; i--) {
+    if (msgs[i].role === "user") return i
+  }
+  return msgs.length
+}