agent-sh 0.14.8 → 0.14.10

package/examples/extensions/ash-acp-bridge/src/index.ts

@@ -11,7 +11,7 @@
  * In agent-shell (Emacs):
  *   (setq agent-shell-agentsh-acp-command '("agent-sh-acp"))
  */
-import { createCore, NoopHistory, type AgentShellCore } from "agent-sh";
+import { createCore, type AgentShellCore } from "agent-sh";
 import { loadExtensions } from "agent-sh/extension-loader";
 import { loadBuiltinExtensions } from "agent-sh/extensions";
 import { activateAgent } from "agent-sh/agent";
@@ -486,7 +486,6 @@ async function handleSessionNew(id: number | string, params: Record<string, unkn
     core = createCore({
       model: cliArgs.model,
       provider: cliArgs.provider,
-      history: new NoopHistory(),
     });
     wireEvents(core);
 

package/examples/extensions/ash-scheme/index.ts

@@ -319,6 +319,36 @@ function format(v: unknown): string {
 }
 
 // ── evaluator ─────────────────────────────────────────────────────
+// LIPS 0.20.x has no character type, so a `#\…` literal reads as an unbound
+// symbol. preprocessSchemeSource expands each to a 1-char string instead.
+const NAMED_CHARS: Record<string, string> = {
+  newline: "\n", linefeed: "\n", nl: "\n",
+  space: " ", tab: "\t", return: "\r",
+  null: "\u0000", nul: "\u0000",
+  delete: "\u007f", rubout: "\u007f",
+  escape: "\u001b", altmode: "\u001b",
+  backspace: "\u0008", alarm: "\u0007", page: "\u000c",
+};
+
+// The char after `#\` as a 1-char string + its span, or null for an unknown
+// multi-char name (left untranslated so it surfaces as an error).
+function resolveCharLiteral(source: string, start: number): { ch: string; span: number } | null {
+  let j = start;
+  while (j < source.length && /[A-Za-z0-9]/.test(source[j])) j++;
+  const run = source.slice(start, j);
+  if (run.length <= 1) {
+    const ch = source[start];
+    return ch === undefined ? null : { ch, span: 1 };
+  }
+  const hex = /^[xX]([0-9a-fA-F]+)$/.exec(run);
+  if (hex) {
+    const cp = parseInt(hex[1], 16);
+    if (cp >= 0 && cp <= 0x10ffff) return { ch: String.fromCodePoint(cp), span: run.length };
+  }
+  const named = NAMED_CHARS[run.toLowerCase()];
+  return named === undefined ? null : { ch: named, span: run.length };
+}
+
 // LIPS implements string literals via JSON.parse, which rejects backslash
 // escapes outside JSON's tiny set (\" \\ \/ \b \f \n \r \t \uXXXX). Models
 // routinely write \s \w \d etc. in regex strings. Pre-process: promote any
@@ -339,6 +369,14 @@ function preprocessSchemeSource(source: string): string {
     if (!inStr) {
       if (c === ";") { inComment = true; out += c; continue; }
       if (c === '"') { inStr = true; out += c; continue; }
+      if (c === "#" && source[i + 1] === "\\") {
+        const lit = resolveCharLiteral(source, i + 2);
+        if (lit) {
+          out += JSON.stringify(lit.ch);
+          i += 1 + lit.span; // skip '\' + the name/char; loop's i++ skips '#'
+          continue;
+        }
+      }
       out += c;
       continue;
     }
@@ -518,6 +556,11 @@ async function evaluate(env: any, source: string, timeoutMs: number) {
       msg = formatParenDiagnostic(source, msg);
     } else if (/Bad escaped character in JSON|Unexpected.*JSON|JSON at position/.test(msg)) {
       msg = formatStringEscapeDiagnostic(source, msg);
+    } else if (msg.includes("Unbound variable `#\\")) {
+      msg += "\n  This runtime has no character type — characters are 1-char strings." +
+        " `#\\newline`, `#\\space`, `#\\tab`, `#\\return`, `#\\xNN`, and `#\\<char>`" +
+        " are accepted (read as strings); other `#\\<name>` forms are not." +
+        " Use a string literal instead, e.g. \"\\n\".";
     }
     return { ok: false as const, error: msg };
   } finally {
@@ -1370,6 +1413,25 @@ function installStdShims(env: any): void {
   });
   defineIfMissing("char-upcase",   (c: any) => String(c).toUpperCase());
   defineIfMissing("char-downcase", (c: any) => String(c).toLowerCase());
+  // Characters are 1-char strings; char? therefore can't tell a char from a
+  // length-1 string.
+  const charStr = (c: any) => (typeof c === "string" ? c : String(c));
+  const codeOf = (c: any) => charStr(c).codePointAt(0) ?? 0;
+  defineIfMissing("char->integer", (c: any) => codeOf(c));
+  defineIfMissing("integer->char", (n: any) => String.fromCodePoint(Math.max(0, Math.floor(Number(n) || 0))));
+  defineIfMissing("char?", (x: any) => typeof x === "string" && Array.from(x).length === 1);
+  defineIfMissing("char=?",  (a: any, b: any) => charStr(a) === charStr(b));
+  defineIfMissing("char<?",  (a: any, b: any) => codeOf(a) <  codeOf(b));
+  defineIfMissing("char>?",  (a: any, b: any) => codeOf(a) >  codeOf(b));
+  defineIfMissing("char<=?", (a: any, b: any) => codeOf(a) <= codeOf(b));
+  defineIfMissing("char>=?", (a: any, b: any) => codeOf(a) >= codeOf(b));
+  defineIfMissing("char-ci=?", (a: any, b: any) => charStr(a).toLowerCase() === charStr(b).toLowerCase());
+  defineIfMissing("char-alphabetic?", (c: any) => /^\p{L}$/u.test(charStr(c)));
+  defineIfMissing("char-numeric?",    (c: any) => /^\p{Nd}$/u.test(charStr(c)));
+  defineIfMissing("char-whitespace?", (c: any) => /^\s$/.test(charStr(c)));
+  defineIfMissing("char-upper-case?", (c: any) => { const s = charStr(c); return s.length === 1 && s === s.toUpperCase() && s !== s.toLowerCase(); });
+  defineIfMissing("char-lower-case?", (c: any) => { const s = charStr(c); return s.length === 1 && s === s.toLowerCase() && s !== s.toUpperCase(); });
+  defineIfMissing("digit-value", (c: any) => { const s = charStr(c); return /^[0-9]$/.test(s) ? Number(s) : false; });
   defineIfMissing("string-normalize-spaces", (s: any, sep?: any, repl?: any) => {
     const str = String(s).trim();
     const splitOn = sep === undefined ? /\s+/ : (sep instanceof RegExp ? sep : new RegExp(String(sep)));
@@ -1500,9 +1562,9 @@ function installStdShims(env: any): void {
 }
 
 // Canonical names we claim coverage for. R = R7RS small base; S = SRFI-1;
-// K = Racket racket/base/list/string/format. Continuations, ports, bytevectors,
-// and char predicates are intentionally omitted — they'd be misleading
-// "coverage" without real functionality.
+// K = Racket racket/base/list/string/format. Continuations, ports, and
+// bytevectors are intentionally omitted — they'd be misleading "coverage"
+// without real functionality. Characters are modeled as 1-char strings.
 const COVERAGE_CHECKLIST: string[] = [
   // R7RS § 6.1 equivalence
   "eq?", "eqv?", "equal?",
@@ -1584,6 +1646,10 @@ const COVERAGE_CHECKLIST: string[] = [
   // Racket strings & chars (gaps)
   "string-titlecase", "string-pad", "string-pad-right",
   "char-upcase", "char-downcase",
+  "char->integer", "integer->char", "char?",
+  "char=?", "char<?", "char>?", "char<=?", "char>=?", "char-ci=?",
+  "char-alphabetic?", "char-numeric?", "char-whitespace?",
+  "char-upper-case?", "char-lower-case?", "digit-value",
   "string-normalize-spaces", "build-string",
   // Racket hash
   "make-hash", "hash", "hash?", "hash-ref", "hash-set!", "hash-set",
@@ -1841,6 +1907,10 @@ function installBindings(
   env.set("string-contains", stringContains);
   env.set("string-append", (...parts: unknown[]) =>
     parts.map((p) => (p === undefined || p === null ? "" : String(p))).join(""));
+  // LIPS' native `string` returns only its first argument; override to actually
+  // concatenate (chars are 1-char strings here, so that's the right semantics).
+  env.set("string", (...parts: unknown[]) =>
+    parts.map((p) => (p === undefined || p === null ? "" : String(p))).join(""));
   env.set("number->string", (n: unknown) => String(n));
   env.set("string->number", (s: unknown) => {
     if (typeof s !== "string") return false;
@@ -1949,6 +2019,10 @@ const DESCRIPTION = [
   "  - R7RS truthy semantics: anything that isn't `#f` is true. `(if str …)`,",
   "    `(if 0 …)`, `(if '() …)` all take the then-branch.",
   "  - `#t`/`#f` work as expected. `equal?`, `eq?`, `eqv?`, `string=?` all work.",
+  "  - Characters are 1-char strings (no separate char type). `#\\newline`,",
+  "    `#\\space`, `#\\tab`, `#\\return`, `#\\xNN`, and `#\\<char>` literals read as",
+  "    the equivalent string; `char->integer`/`integer->char`/`char?`/`char=?`/",
+  "    `char-whitespace?` etc. operate on them. A bare newline is just \"\\n\".",
   "  - SRFI-1: `member`, `assq`/`assv`/`assoc`, `delete-duplicates`, `first`",
   "    through `fifth`, `last`, `take`, `drop`, `iota`, `any`, `every`, `count`,",
   "    `find`, `filter-map`, `append-map`, `concatenate`, `partition`, `remove`,",

package/examples/extensions/ashi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanyilun/ashi",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Ash in an interactive TUI — agent-sh's built-in agent without the shell underneath",
   "type": "module",
   "main": "dist/cli.js",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.74.0",
-    "agent-sh": "^0.14.7",
+    "agent-sh": "^0.14.8",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11"
   },

package/examples/extensions/ashi/src/capture.ts

@@ -1,6 +1,6 @@
 import type { ExtensionContext } from "agent-sh/types";
 import type { MultiSessionStore } from "./multi-session-store.js";
-import type { AgentMessage } from "./session-store.js";
+import type { AgentShMessage as AgentMessage } from "agent-sh/session-store";
 
 /** Maintains an `(entryId | null)[]` parallel to the live messages array;
  *  null slots are synthetics like compaction summaries that have no entry. */

package/examples/extensions/ashi/src/cli.ts

@@ -2,7 +2,7 @@
 /**
  * ashi — ash (agent-sh's built-in agent) in an interactive TUI.
  */
-import { createCore, NoopHistory } from "agent-sh/core";
+import { createCore } from "agent-sh/core";
 import { loadBuiltinExtensions } from "agent-sh/extensions";
 import { loadExtensions } from "agent-sh/extension-loader";
 import { activateAgent } from "agent-sh/agent";
@@ -36,8 +36,8 @@ import * as path from "node:path";
 
 function parseArgs(argv: string[]): AppConfig & { extensions?: string[]; continueLast: boolean } {
   let model: string | undefined;
-  let apiKey: string | undefined = process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY;
-  let baseURL: string | undefined = process.env.OPENAI_BASE_URL;
+  let apiKey: string | undefined;
+  let baseURL: string | undefined;
   let provider: string | undefined;
   let backend: string | undefined;
   let continueLast = false;
@@ -134,7 +134,7 @@ async function main(): Promise<void> {
   const store = new MultiSessionStore(sessionsDir, cwd, { resumeSessionId: resumeId });
   const getStore = (): MultiSessionStore => store;
 
-  const core = createCore({ ...config, history: new NoopHistory() });
+  const core = createCore(config);
 
   let stopFrontend: (() => void) | null = null;
 
@@ -153,7 +153,7 @@ async function main(): Promise<void> {
 
   activateAgent(ctx);
   activateShellContext(ctx);
-  await loadBuiltinExtensions(ctx);
+  await loadBuiltinExtensions(ctx, ["rolling-history"]);
 
   const shell = new Shell({
     bus: core.bus,
@@ -183,7 +183,6 @@ async function main(): Promise<void> {
   registerRenderDefaults(ctx);
   registerDefaultSchemaRenderers(ctx);
 
-  ctx.advise("conversation:format-prior-history", () => null);
   ctx.advise("system-prompt:build", (next) => `${next()}\n\n<cwd>${process.cwd()}</cwd>`);
 
   const handle = mountAshi(ctx, getStore, capture);

package/examples/extensions/ashi/src/compaction.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "agent-sh/types";
 import type { MultiSessionStore } from "./multi-session-store.js";
 import type { Capture } from "./capture.js";
-import type { AgentMessage } from "./session-store.js";
+import type { AgentShMessage as AgentMessage } from "agent-sh/session-store";
 
 const KEEP_RECENT_TOKEN_BUDGET = 20_000;
 const FORCE_KEEP_RECENT_TOKEN_BUDGET = 4_000;
@@ -81,6 +81,10 @@ export function isSafeCutPoint(messages: AgentMessage[], idx: number): boolean {
 export function estimateMessageTokens(m: AgentMessage): number {
   let chars = 0;
   if (typeof m.content === "string") chars += m.content.length;
-  if (m.tool_calls) for (const t of m.tool_calls) chars += (t.function?.arguments?.length ?? 0);
+  if (m.role === "assistant" && m.tool_calls) {
+    for (const t of m.tool_calls) {
+      if (t.type === "function") chars += t.function.arguments.length;
+    }
+  }
   return Math.ceil(chars * APPROX_TOKENS_PER_CHAR) + 20;
 }

package/examples/extensions/ashi/src/frontend.ts

@@ -28,6 +28,7 @@ import type { ToolCallView, ToolResultView } from "./hooks.js";
 import { createToolHookResolver } from "./hooks.js";
 import { loadGroupMaxVisible } from "./display-config.js";
 import { classifySubmit, deriveChangeHandlerResult } from "./shell-mode.js";
+import { UserShellIntents } from "./user-shell-intents.js";
 
 const GROUPABLE_KINDS = new Set(["read", "search"]);
 const TOOL_KIND: Record<string, string> = {
@@ -37,7 +38,7 @@ const TOOL_KIND: Record<string, string> = {
 import { BusAutocompleteProvider } from "./autocomplete.js";
 import { StatusFooter } from "./status-footer.js";
 import type { MultiSessionStore } from "./multi-session-store.js";
-import { stripContextWrappers, type SessionEntry } from "./session-store.js";
+import { stripContextWrappers, type SessionEntry } from "agent-sh/session-store";
 import { formatSessionRow } from "./session-commands.js";
 import { resumeSession } from "./session-commands.js";
 import { applyBranchMessages } from "./commands.js";
@@ -300,8 +301,7 @@ export function mountAshi(
   let processing = false;
   const queuedQueries: string[] = [];
   const queuedShellLines: { line: string; private: boolean }[] = [];
-  /** FIFO matching pty-writes to their shell:command-start events. */
-  const pendingUserBlockPrivacy: boolean[] = [];
+  const pendingUserShell = new UserShellIntents();
 
   const renderQueueSlot = (): void => {
     queueSlot.clear();
@@ -325,7 +325,7 @@ export function mountAshi(
       tui.requestRender();
       return;
     }
-    pendingUserBlockPrivacy.push(!!opts?.private);
+    pendingUserShell.push({ private: !!opts?.private });
     if (opts?.private) bus.emit("shell:user-exec-exclude-next", {});
     bus.emit("shell:pty-write", { data: line + "\n" });
   };
@@ -442,21 +442,22 @@ export function mountAshi(
       }
       if (m.tool_calls) {
         for (const tc of m.tool_calls) {
+          if (tc.type !== "function") continue;
           const id = tc.id ?? "";
-          const name = tc.function?.name ?? "tool";
+          const name = tc.function.name ?? "tool";
           const kind = TOOL_KIND[name];
           if (kind && GROUPABLE_KINDS.has(kind)) {
             const mergeable = findMergeableGroup(kind);
             const group = mergeable
               ?? (() => { const g = new ToolGroup(kind, groupMaxVisible); chat.addChild(g); return g; })();
-            group.addCall(id, name, detailFromArgs(tc.function?.arguments));
+            group.addCall(id, name, detailFromArgs(tc.function.arguments));
             if (id) toolMap.set(id, { kind: "group", group, name });
             continue;
           }
           const pair = renderToolPair({
             toolCallId: id, name, title: name, kind: undefined,
-            displayDetail: detailFromArgs(tc.function?.arguments),
-            rawInput: tc.function?.arguments,
+            displayDetail: detailFromArgs(tc.function.arguments),
+            rawInput: tc.function.arguments,
           });
           chat.addChild(pair.call);
           chat.addChild(pair.result);
@@ -636,12 +637,11 @@ export function mountAshi(
   let activeUserShell: { pair: ToolPair; command: string; isPrivate: boolean } | null = null;
   bus.on("shell:command-start", ({ command }) => {
     if (agentShellActive) return;
-    // Defensive: bash DEBUG-trap integrations have been observed firing
-    // before any user input, with an empty command body.
-    if (!command.trim()) return;
+    const intent = pendingUserShell.consume();
+    if (!intent) return;
     finalizeThinking();
     if (activeAssistant) { activeAssistant.finalize(); activeAssistant = null; }
-    const isPrivate = pendingUserBlockPrivacy.shift() ?? false;
+    const isPrivate = intent.private;
     const name = isPrivate ? "user_bash_private" : "user_bash";
     const pair = renderToolPair({
       toolCallId: `user-shell-${Date.now()}`, name, title: name,
@@ -681,7 +681,7 @@ export function mountAshi(
     // Shell queue drains first so its output lands in the next turn's <shell_events>.
     while (queuedShellLines.length > 0) {
       const item = queuedShellLines.shift()!;
-      pendingUserBlockPrivacy.push(item.private);
+      pendingUserShell.push({ private: item.private });
       if (item.private) bus.emit("shell:user-exec-exclude-next", {});
       bus.emit("shell:pty-write", { data: item.line + "\n" });
     }

package/examples/extensions/ashi/src/multi-session-store.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
-import { SessionStore, type AgentMessage } from "./session-store.js";
+import { SessionStore, type AgentShMessage as AgentMessage } from "agent-sh/session-store";
 
 export interface SessionInfo {
   id: string;
@@ -55,13 +55,10 @@ export class MultiSessionStore {
       for (const name of names) {
         if (!name.endsWith(".jsonl")) continue;
         const id = name.slice(0, -".jsonl".length);
-        try {
-          const raw = fs.readFileSync(path.join(dir, `${id}.jsonl.meta`), "utf-8");
-          const meta = JSON.parse(raw) as { createdAt?: number };
-          if (typeof meta.createdAt === "number" && (!best || meta.createdAt > best.createdAt)) {
-            best = { id, createdAt: meta.createdAt };
-          }
-        } catch { /* skip unreadable meta */ }
+        const createdAt = readHeaderTimestamp(path.join(dir, name));
+        if (createdAt !== null && (!best || createdAt > best.createdAt)) {
+          best = { id, createdAt };
+        }
       }
       if (best) return best.id;
     }
@@ -69,6 +66,21 @@ export class MultiSessionStore {
     return undefined;
   }
 
+  setName(id: string, name: string): void {
+    fs.writeFileSync(this.metaFile(id), JSON.stringify({ name }));
+  }
+
+  private readName(id: string): string | undefined {
+    try {
+      const m = JSON.parse(fs.readFileSync(this.metaFile(id), "utf-8")) as { name?: string };
+      return typeof m.name === "string" ? m.name : undefined;
+    } catch { return undefined; }
+  }
+
+  private metaFile(id: string): string {
+    return path.join(this.dir, `${id}.jsonl.meta`);
+  }
+
   /** One-time import from the previous storage format (sessions stored as
    *  directories with tree.jsonl + snapshots/). Each old session is replayed
    *  from its most recent snapshot into a new flat `.jsonl` file, then the
@@ -140,12 +152,12 @@ export class MultiSessionStore {
       const filePath = path.join(this.dir, name);
       try {
         const store = new SessionStore(filePath);
-        const meta = store.getMeta();
+        const root = store.getEntry(store.getRootId());
         result.push({
           id,
           filePath,
-          createdAt: meta.createdAt,
-          name: meta.name,
+          createdAt: root?.timestamp ?? 0,
+          name: this.readName(id),
           preview: store.getPreview(),
           entryCount: store.getAllEntries().length,
         });
@@ -172,6 +184,17 @@ function newSessionFileId(): string {
   return `${ts}_${suffix}`;
 }
 
+function readHeaderTimestamp(filePath: string): number | null {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const nl = raw.indexOf("\n");
+    const firstLine = nl < 0 ? raw : raw.slice(0, nl);
+    const e = JSON.parse(firstLine) as { type?: string; timestamp?: number };
+    if (e.type === "session" && typeof e.timestamp === "number") return e.timestamp;
+  } catch { /* unreadable */ }
+  return null;
+}
+
 function writeImportedSession(
   newFile: string,
   id: string,
@@ -191,5 +214,5 @@ function writeImportedSession(
   }
   fs.writeFileSync(newFile, lines.join("\n") + "\n");
   fs.writeFileSync(newFile + ".leaf", parent);
-  fs.writeFileSync(newFile + ".meta", JSON.stringify({ createdAt: ts, ...(name ? { name } : {}) }));
+  if (name) fs.writeFileSync(newFile + ".meta", JSON.stringify({ name }));
 }

package/examples/extensions/ashi/src/session-commands.ts

@@ -35,7 +35,7 @@ export function registerSessionCommands(
       bus.emit("ui:error", { message: "name: expected a name" });
       return;
     }
-    getStore().current().setName(name);
+    getStore().setName(getStore().current().id, name);
     bus.emit("ui:info", { message: `session named: ${name}` });
   });
 

package/examples/extensions/ashi/src/user-shell-intents.ts

@@ -0,0 +1,17 @@
+/** Pending intents for ashi-issued shell pty-writes. shell:command-start fires
+ *  for any OSC 9997 — orphans (bash DEBUG-trap noise) are dropped on consume. */
+export interface UserShellIntent {
+  private: boolean;
+}
+
+export class UserShellIntents {
+  private q: UserShellIntent[] = [];
+
+  push(intent: UserShellIntent): void {
+    this.q.push(intent);
+  }
+
+  consume(): UserShellIntent | null {
+    return this.q.shift() ?? null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.14.8",
+  "version": "0.14.10",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "workspaces": [
@@ -73,6 +73,18 @@
       "types": "./dist/agent/types.d.ts",
       "default": "./dist/agent/types.js"
     },
+    "./store": {
+      "types": "./dist/agent/store.d.ts",
+      "default": "./dist/agent/store.js"
+    },
+    "./session-store": {
+      "types": "./dist/agent/session-store.d.ts",
+      "default": "./dist/agent/session-store.js"
+    },
+    "./entry-format": {
+      "types": "./dist/agent/entry-format.d.ts",
+      "default": "./dist/agent/entry-format.js"
+    },
     "./agent/subagent": {
       "types": "./dist/agent/subagent.d.ts",
       "default": "./dist/agent/subagent.js"

package/dist/agent/conversation-state.d.ts

@@ -1,142 +0,0 @@
-import type { ChatCompletionMessageParam } from "./llm-client.js";
-import type { ImageContent } from "./types.js";
-import { type NuclearEntry } from "./nuclear-form.js";
-import type { HandlerFunctions } from "../utils/handler-registry.js";
-/** Search hit shape returned by the `history:search` handler. */
-export interface HistoryHit {
-    entry: NuclearEntry;
-    line: string;
-}
-export interface CompactResult {
-    before: number;
-    after: number;
-    evictedCount: number;
-    [extra: string]: unknown;
-}
-/**
- * Conversation state with eager nucleation — shell-history shaped.
- *
- * Every add nucleates into a one-line NuclearEntry and flushes to disk.
- * Compaction evicts turns, replacing them with their nuclear one-liners
- * in context; the originals stay searchable via `conversation_recall`
- * and survive restarts in `~/.agent-sh/history`.
- *
- * Nucleation and history I/O go through advisable handlers — extensions
- * swap strategies without touching this class. When no handlers are
- * provided (subagents, tests), both become no-ops and this becomes a
- * plain message buffer.
- */
-export declare class ConversationState {
-    private messages;
-    private messagesDirty;
-    private cachedMessagesJson;
-    private toolErrors;
-    private nuclearEntries;
-    private nuclearBySeq;
-    private recallArchive;
-    readonly instanceId: string;
-    private readonly handlers;
-    private nextSeq;
-    private lastApiTokenCount;
-    private lastApiMessageCount;
-    private pendingMessages;
-    constructor(handlers?: HandlerFunctions, instanceId?: string);
-    /** Get JSON.stringify of messages, cached until next mutation. */
-    private getMessagesJson;
-    private invalidateMessagesCache;
-    addUserMessage(text: string): void;
-    addAssistantMessage(content: string | null, toolCalls?: {
-        id: string;
-        function: {
-            name: string;
-            arguments: string;
-        };
-    }[], extras?: Record<string, unknown>): void;
-    addToolResult(toolCallId: string, content: string | ImageContent[], isError?: boolean): void;
-    /** Add tool results as a user message (for inline tool protocol). */
-    addToolResultInline(content: string): void;
-    /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
-    addSystemNote(text: string): void;
-    appendUserMessage(text: string): void;
-    private hasOpenToolCalls;
-    private flushPendingMessages;
-    getMessages(): ChatCompletionMessageParam[];
-    /** Drop tool messages with no matching preceding tool_call — strict
-     *  providers (DeepSeek) 400, and compaction can leave such orphans. */
-    private dropOrphanToolMessages;
-    /**
-     * If a stream was interrupted mid-tool-execution, an assistant message
-     * with tool_calls can land in history without matching tool results.
-     * Strict providers (DeepSeek) 400 on this. Stub each missing result
-     * with a [cancelled] marker so the protocol stays valid.
-     */
-    private stubDanglingToolCalls;
-    /**
-     * DeepSeek 400s if any assistant in a thinking-mode conversation is
-     * missing reasoning_content. Cross-alias here (OpenRouter streams as
-     * `reasoning`, DeepSeek input expects `reasoning_content`) and stub
-     * gaps (text-only turns, pre-fix messages) with empty string.
-     */
-    private normalizeReasoningConsistency;
-    /**
-     * Replace the messages array wholesale — the write side for custom
-     * compaction strategies. Invalidates API token baseline since the
-     * new array's token count is unknown.
-     */
-    replaceMessages(messages: ChatCompletionMessageParam[]): void;
-    private pruneToolErrors;
-    private eagerNucleateUser;
-    /** Nucleate an agent text response. Called by agent-loop when the loop finishes without tool calls. */
-    eagerNucleateAgent(text: string): void;
-    /** Nucleate tool call results. One entry per tool call, enriched with result. */
-    eagerNucleateTools(results: Array<{
-        toolName: string;
-        args: Record<string, unknown>;
-        content: string | ImageContent[];
-        isError: boolean;
-    }>): void;
-    /** Track an entry in memory (nuclear list + recall archive). */
-    private recordNuclearEntry;
-    private appendToHistory;
-    /** Bump and return the global sequence counter. For extensions that
-     *  synthesize their own NuclearEntries (e.g. compaction summaries that
-     *  should land in the same sequence space as kernel-produced entries). */
-    allocateSeq(): number;
-    /** Clear nuclear bookkeeping and reset the seq counter. For extensions
-     *  that swap sessions (multi-session history adapters) so the in-memory
-     *  nuclear list, recall archive, and seq counter don't carry over from
-     *  the previous session's tree. */
-    resetForSession(nextSeq: number): void;
-    updateApiTokenCount(promptTokens: number): void;
-    estimatePromptTokens(): number;
-    estimateTokens(): number;
-    /**
-     * Two-tier pin compaction: evict lowest-priority turns (replaced by
-     * their nuclear one-liners), slim the window before the last verbatim
-     * turn, drop read-only tool results entirely. Extensions replace the
-     * whole strategy by advising `conversation:compact` and skipping next.
-     */
-    compact(maxPromptTokens: number, recentTurnsToKeep?: number, force?: boolean): CompactResult | null;
-    /**
-     * Inject prior session history as a context preamble. The preamble
-     * layout goes through the `conversation:format-prior-history` handler,
-     * so extensions can swap the flat list for grouped/richer rendering.
-     */
-    loadPriorHistory(entries: NuclearEntry[]): void;
-    search(query: string): Promise<string>;
-    expand(seq: number): Promise<string>;
-    browse(): Promise<string>;
-    getNuclearEntries(): readonly NuclearEntry[];
-    getNuclearEntryCount(): number;
-    getNuclearSummary(): string | null;
-    getRecallArchiveSize(): number;
-    clear(): void;
-    private buildNuclearBlock;
-    /** Index of the nuclear block in messages[], or -1 if not present. */
-    private nuclearBlockIdx;
-    private updateNuclearBlockInMessages;
-    private slimTurn;
-    private parseTurns;
-    private inferPriority;
-    private turnToText;
-}