agent-sh 0.15.0 → 0.15.1

package/src/agent/entry-format.ts

@@ -0,0 +1,19 @@
+/** Display line for synthetic summary blocks and conversation_recall.
+ *  The leading `#${id}` is the token the LLM uses to reference an
+ *  entry when calling `recall:expand`. */
+import type { Entry } from "./store.js";
+
+interface SummaryPayload {
+  sum?: string;
+  why?: string;
+}
+
+export function formatEntryLine(e: Entry): string {
+  const d = new Date(e.ts);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const stamp = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  const p = e.payload as SummaryPayload;
+  const sum = p.sum ?? `(${e.kind})`;
+  const whyTag = p.why ? ` {${p.why.length > 80 ? p.why.slice(0, 77) + "..." : p.why}}` : "";
+  return `#${e.id} [${stamp}] ${sum}${whyTag}`;
+}

package/src/agent/events.ts

@@ -0,0 +1,151 @@
+/** Agent-protocol events. Speak this to be a backend; consume it to be a frontend. */
+import type { ContentBlock } from "../core/event-bus.js";
+import type { Model, ProviderRegistration } from "./host-types.js";
+import type { ImageContent, ToolDefinition, ToolResultDisplay } from "./types.js";
+
+export interface AgentIdentity {
+  name: string;
+  version: string;
+  model?: string;
+  provider?: string;
+  contextWindow?: number;
+}
+
+declare module "../core/event-bus.js" {
+  interface BusEvents {
+    /** Sync pipe: extensions append core tool names; unioned with settings.coreTools. */
+    "agent:core-tools:collect": { names: string[] };
+
+    "agent:providers": { providers: ProviderRegistration[] };
+    "agent:providers:changed": Record<string, never>;
+    "provider:configure": {
+      id: string;
+      reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
+      cacheTokens?: (usage: Record<string, unknown>) => number | undefined;
+    };
+
+    "agent:models-changed": Record<string, never>;
+    "config:switch-provider": { provider: string };
+
+    "agent:info": AgentIdentity;
+    "agent:tools": { tools: ToolDefinition[] };
+    "agent:instructions": { instructions: Array<{ name: string; text: string }> };
+    "agent:skills": { skills: Array<{ name: string; description: string; filePath: string }> };
+
+    "agent:submit": { query: string; images?: ImageContent[] };
+    "agent:cancel-request": { silent?: boolean };
+    "agent:append-user-message": { text: string };
+    "agent:query": { query: string };
+    "agent:reset-session": Record<string, never>;
+    "agent:compact-request": Record<string, never>;
+
+    "agent:thinking-chunk": { text: string };
+    "agent:response-chunk": { blocks: ContentBlock[] };
+    "agent:response-done": { response: string };
+    "agent:usage": { prompt_tokens: number; completion_tokens: number; total_tokens: number; cached_prompt_tokens?: number };
+
+    "agent:processing-start": Record<string, never>;
+    "agent:processing-done": Record<string, never>;
+    "agent:cancelled": Record<string, never>;
+    "agent:error": { message: string };
+
+    "agent:tool-call": { tool: string; args: Record<string, unknown> };
+    "agent:tool-output": {
+      tool: string;
+      output: string;
+      exitCode: number | null;
+    };
+    "agent:tool-batch": {
+      groups: Array<{
+        kind: string;
+        tools: Array<{ name: string; displayDetail?: string }>;
+      }>;
+    };
+    "agent:tool-batch-complete": {
+      results: Array<{ name: string; isError: boolean; errorSummary?: string }>;
+    };
+    "agent:tool-started": {
+      title: string;
+      /** Canonical tool name; `title` is the display label and may differ. */
+      name?: string;
+      toolCallId?: string;
+      kind?: string;
+      icon?: string;
+      locations?: { path: string; line?: number | null }[];
+      rawInput?: unknown;
+      displayDetail?: string;
+      /** highlight.js identifier for rawInput.source. */
+      sourceLanguage?: string;
+      batchIndex?: number;
+      batchTotal?: number;
+    };
+    "agent:tool-completed": {
+      toolCallId?: string;
+      exitCode: number | null;
+      rawOutput?: unknown;
+      kind?: string;
+      resultDisplay?: ToolResultDisplay;
+    };
+    "agent:tool-output-chunk": { chunk: string };
+
+    "tool:interactive-start": Record<string, never>;
+    "tool:interactive-end": Record<string, never>;
+
+    "agent:subagent-started": { taskId: string; task: string };
+    "agent:subagent-completed": { taskId: string; task: string; result: string; isError: boolean };
+
+    "agent:terminal-intercept": {
+      command: string;
+      cwd: string;
+      intercepted: boolean;
+      output: string;
+    };
+
+    "conversation:message-appended": {
+      role: "user" | "assistant" | "tool" | "system";
+      content: string;
+      toolName?: string;
+      toolArgs?: Record<string, unknown>;
+      isError?: boolean;
+    };
+    "conversation:after-compact": {
+      beforeTokens: number;
+      afterTokens: number;
+      evictedCount: number;
+    };
+
+    "context:get-stats": {
+      activeTokens: number;
+      totalTokens: number;
+      budgetTokens: number;
+    };
+    "context:snapshot": {
+      messages: unknown[];
+      contextWindow: number;
+      activeTokens: number;
+    };
+    "context:compact": {
+      strategy?:
+        | { kind: "two-tier-pin"; target: number; keepRecent?: number; force?: boolean }
+        | { kind: "rewind"; toIndex: number }
+        | { kind: "replace"; messages: unknown[] };
+      stats?: { before: number; after: number; evictedCount: number };
+    };
+
+    "config:switch-model": { id: string; provider: string };
+    "config:get-models": { models: Model[]; active: Model | null };
+    "config:set-thinking": { level: string };
+    "config:get-thinking": { level: string; levels: string[]; supported: boolean };
+
+    "llm:request": {
+      messages: unknown[];
+      tools?: unknown;
+      model?: string;
+      max_tokens?: number;
+      reasoning_effort?: string;
+    };
+    "llm:chunk": { chunk: unknown };
+  }
+}
+
+export {};

package/src/agent/extensions/rolling-history/constants.ts

@@ -0,0 +1 @@
+export const RECALL_CACHE_KIND = "recall-cache";

package/src/agent/extensions/rolling-history/index.ts

@@ -0,0 +1,202 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "../../../shell/host-types.js";
+import type { AgentShMessage } from "../../llm-client.js";
+import { contentText, type ToolDefinition } from "../../types.js";
+import { SharedFileStore, newEntryId, type Store, type Entry } from "../../store.js";
+import { CONFIG_DIR, getSettings } from "../../../core/settings.js";
+import { deserializeEntry, isReadOnly } from "../../nuclear-form.js";
+import {
+  activate as activateSummaryStrategy,
+  nuclearToEntry,
+  readSummaryLines,
+  type SummaryCtx,
+} from "./strategy.js";
+import { recallSearch, recallExpand, recallBrowse } from "./recall.js";
+
+const TOOL_NAME = "conversation_recall";
+const INSTRUCTION_NAME = "recall-guidance";
+const INSTRUCTION_TEXT =
+  "When starting a task that may have been discussed before (conventions, preferences, corrections, prior examples), " +
+  "use conversation_recall to search history for relevant prior entries. " +
+  "Treat recurring user guidance as standing preferences. " +
+  "If a search returns nothing useful, try: shorter queries, alternate terms, or browse to scan the full timeline. " +
+  "Recall only covers this and recent sessions — for older context, also search the filesystem (grep, glob).";
+
+/** One-time migration: old ~/.agent-sh/history → rolling-history store. */
+export function migrateFromLegacy(
+  storeDir: string,
+  legacyPath: string,
+  ctx: Pick<ExtensionContext, "bus">,
+): void {
+  const sentinel = path.join(storeDir, ".migrated");
+  if (fs.existsSync(sentinel)) return;
+
+  const newFile = path.join(storeDir, "history.jsonl");
+  if (fs.existsSync(newFile) && fs.statSync(newFile).size > 0) {
+    try { fs.writeFileSync(sentinel, ""); } catch { /* ignore */ }
+    return;
+  }
+
+  if (!fs.existsSync(legacyPath)) {
+    try { fs.writeFileSync(sentinel, ""); } catch { /* ignore */ }
+    return;
+  }
+
+  let migrated = 0;
+  try {
+    const lines = fs.readFileSync(legacyPath, "utf-8").split("\n").filter(Boolean);
+    const entries: Entry[] = [];
+    for (const line of lines) {
+      const ne = deserializeEntry(line);
+      if (!ne) continue;
+      if (isReadOnly(ne)) continue;
+      entries.push(nuclearToEntry(ne, newEntryId()));
+    }
+    if (entries.length > 0) {
+      fs.writeFileSync(newFile, entries.map((e) => JSON.stringify(e) + "\n").join(""));
+      migrated = entries.length;
+    }
+  } catch {
+    return; // retry next start
+  }
+
+  try { fs.writeFileSync(sentinel, ""); } catch { /* ignore */ }
+  if (migrated > 0) {
+    ctx.bus.emit("ui:info", { message: `history: migrated ${migrated} entries from legacy ~/.agent-sh/history` });
+  }
+}
+
+export default function activate(ctx: ExtensionContext): void {
+  const { maxBytes, prefetchEntries } = ctx.getExtensionSettings("rolling-history", {
+    maxBytes: undefined as number | undefined,
+    prefetchEntries: 50,
+  });
+  const storeDir = ctx.getStoragePath("rolling-history");
+  const settings = getSettings();
+  const legacyPath = settings.historyFilePath ?? path.join(CONFIG_DIR, "history");
+  migrateFromLegacy(storeDir, legacyPath, ctx);
+  const summaryStore = new SharedFileStore({
+    filePath: path.join(storeDir, "history.jsonl"),
+    maxBytes,
+  });
+
+  // `/history off` gates only writes — store.append and the linkMessage
+  // back-stamp. Everything else (meta.tool stamping, compact's reorg,
+  // recall reads) runs identically on both sides. Tool + instruction stay
+  // registered either way so toggling never perturbs the tools array or
+  // system prompt (LLM prompt cache is preserved).
+  let enabled = true;
+  const gatedStore: Store = {
+    append: (entries, opts) => enabled ? summaryStore.append(entries, opts) : Promise.resolve(),
+    findById: (id) => summaryStore.findById(id),
+    readRecent: (n) => summaryStore.readRecent(n),
+    search: (q) => summaryStore.search(q),
+  };
+
+  const summaryCtx: SummaryCtx = {
+    store: gatedStore,
+    bus: { on: (e, f) => ctx.bus.on(e, f) },
+    advise: (op, f) => { ctx.advise(op, f as Parameters<typeof ctx.advise>[1]); },
+    iid: ctx.instanceId,
+    getMessages: () => (ctx.call("conversation:get-messages") as AgentShMessage[] | undefined) ?? [],
+    replaceMessages: (msgs) => { ctx.call("conversation:replace-messages", msgs); },
+    estimateTokens: () => (ctx.call("conversation:estimate-tokens") as number | undefined) ?? 0,
+    estimatePromptTokens: () => (ctx.call("conversation:estimate-prompt-tokens") as number | undefined) ?? 0,
+    linkMessage: (index, entryId) => { if (enabled) ctx.call("conversation:link", index, entryId); },
+  };
+  activateSummaryStrategy(summaryCtx);
+
+  const toolDef: ToolDefinition = {
+    name: TOOL_NAME,
+    displayName: "recall",
+    description:
+      "Browse, search, or expand evicted conversation turns. " +
+      "Use when you need context from earlier in the conversation that was compacted away. " +
+      "Search is regex-based and covers both summaries and full body text. " +
+      "If search doesn't find what you expect, try broader/shorter terms or browse to scan the timeline.",
+    input_schema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["browse", "search", "expand"],
+          description: "browse: list evicted turns, search: regex search, expand: show full turn",
+        },
+        query: { type: "string", description: "Search query (for action=search)" },
+        turn_id: { type: "string", description: "Turn ID to expand (for action=expand)" },
+      },
+      required: ["action"],
+    },
+    execute: async (args) => {
+      const action = args.action as string;
+      let content: string;
+      if (action === "search") {
+        content = await recallSearch(summaryStore, (args.query as string) ?? "");
+      } else if (action === "expand") {
+        content = await recallExpand(summaryStore, args.turn_id as string);
+      } else {
+        content = await recallBrowse(summaryStore);
+      }
+      return { content, exitCode: 0, isError: false };
+    },
+    formatResult: (args, result) => {
+      const action = args.action as string;
+      const text = contentText(result.content);
+      if (result.isError) return { summary: "error" };
+      if (action === "search") {
+        if (text.startsWith("No results")) return { summary: "0 matches" };
+        const m = text.match(/^Found (\d+)/);
+        return { summary: m ? `${m[1]} matches` : "search done" };
+      }
+      if (action === "browse") {
+        if (text.startsWith("No conversation")) return { summary: "empty" };
+        return { summary: "browsed" };
+      }
+      if (text.includes("no expanded content")) return { summary: "not found" };
+      return { summary: "expanded" };
+    },
+    getDisplayInfo: () => ({ kind: "search", icon: "⟲" }),
+  };
+
+  if (ctx.agent) {
+    ctx.agent.registerTool(toolDef);
+    ctx.agent.registerInstruction(INSTRUCTION_NAME, INSTRUCTION_TEXT);
+  }
+
+  ctx.registerCommand("history", "Toggle conversation history writes (on / off / status).", (args) => {
+    const arg = args.trim().toLowerCase();
+    if (arg === "" || arg === "status") {
+      ctx.bus.emit("ui:info", { message: `history: writes ${enabled ? "on" : "off"} — recall remains available for prior sessions` });
+      return;
+    }
+    if (arg === "on") {
+      if (enabled) { ctx.bus.emit("ui:info", { message: "history: already on" }); return; }
+      enabled = true;
+      ctx.bus.emit("ui:info", { message: "history: on — new turns will be summarized" });
+      return;
+    }
+    if (arg === "off") {
+      if (!enabled) { ctx.bus.emit("ui:info", { message: "history: already off" }); return; }
+      enabled = false;
+      ctx.bus.emit("ui:info", { message: "history: off — new turns won't be summarized (recall still available)" });
+      return;
+    }
+    ctx.bus.emit("ui:info", { message: `history: unknown arg "${arg}" (use on / off / status)` });
+  });
+
+  if (prefetchEntries > 0) {
+    Promise.resolve().then(async () => {
+      const lines = await readSummaryLines(summaryStore, prefetchEntries);
+      if (lines.length === 0) return;
+      const current = (ctx.call("conversation:get-messages") as AgentShMessage[] | undefined) ?? [];
+      ctx.call("conversation:replace-messages", [
+        ...current,
+        {
+          role: "user",
+          content: `[Prior session history — loaded from the summary store]\n${lines.join("\n")}`,
+        },
+      ]);
+    }).catch(() => {});
+  }
+}

package/src/agent/extensions/rolling-history/recall.ts

@@ -0,0 +1,131 @@
+import type { Store, Entry } from "../../store.js";
+import type { AgentShMessage } from "../../llm-client.js";
+import { formatEntryLine } from "../../entry-format.js";
+import { RECALL_CACHE_KIND } from "./constants.js";
+import { readSummaryLines } from "./strategy.js";
+
+interface SummaryPayload {
+  sum: string;
+  body?: string;
+  iid?: string;
+  tool?: string;
+  why?: string;
+}
+
+interface RecallCachePayload {
+  fullMessage: AgentShMessage;
+}
+
+function turnToText(msgs: AgentShMessage[]): string {
+  const lines: string[] = [];
+  for (const m of msgs) {
+    if (m.role === "user") {
+      lines.push(`[user] ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`);
+    } else if (m.role === "assistant") {
+      if (typeof m.content === "string" && m.content) lines.push(`[assistant] ${m.content}`);
+      if ("tool_calls" in m && m.tool_calls) {
+        for (const tc of m.tool_calls) {
+          if ("function" in tc) lines.push(`[tool_call] ${tc.function.name}(${tc.function.arguments})`);
+        }
+      }
+    } else if (m.role === "tool") {
+      lines.push(`[tool] ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`);
+    } else {
+      lines.push(`[${m.role}] ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function firstMatchExcerpt(text: string, regex: RegExp): string | null {
+  const idx = text.search(regex);
+  if (idx === -1) return null;
+  const lineStart = text.lastIndexOf("\n", idx) + 1;
+  const lineEnd = text.indexOf("\n", idx);
+  const line = text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd).trim();
+  if (line.length > 120) {
+    const matchInLine = idx - lineStart;
+    const start = Math.max(0, matchInLine - 40);
+    const end = Math.min(line.length, matchInLine + 80);
+    return (start > 0 ? "…" : "") + line.slice(start, end) + (end < line.length ? "…" : "");
+  }
+  return line;
+}
+
+function buildSearchRegex(query: string): RegExp {
+  try {
+    return new RegExp(query, "i");
+  } catch {
+    const words = query.split(/\s+/).filter((w) => w.length > 0);
+    const escaped = words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const lookaheads = escaped.map((w) => `(?=.*${w})`).join("");
+    return new RegExp(lookaheads, "i");
+  }
+}
+
+/** Cache entries are ephemeral, so this only resolves for the
+ *  current process. */
+async function findCacheChild(store: Store, parentId: string): Promise<RecallCachePayload | null> {
+  const recent = await store.readRecent();
+  for (let i = recent.length - 1; i >= 0; i--) {
+    const e = recent[i]!;
+    if (e.kind === RECALL_CACHE_KIND && e.parentId === parentId) {
+      return e.payload as unknown as RecallCachePayload;
+    }
+  }
+  return null;
+}
+
+export async function recallSearch(store: Store, query: string): Promise<string> {
+  if (!query.trim()) return "No query provided.";
+  const regex = buildSearchRegex(query);
+  const hits: string[] = [];
+  const seenParents = new Set<string>();
+
+  const matches = await store.search(query);
+  for (const m of matches) {
+    // Cache hits surface via their parent summary; summary hits are their own parent.
+    let parentEntry: Entry | null = null;
+    if (m.entry.kind === RECALL_CACHE_KIND) {
+      if (!m.entry.parentId) continue;
+      parentEntry = await store.findById(m.entry.parentId);
+    } else {
+      parentEntry = m.entry;
+    }
+    if (!parentEntry || seenParents.has(parentEntry.id)) continue;
+    seenParents.add(parentEntry.id);
+
+    const cache = await findCacheChild(store, parentEntry.id);
+    const excerptSource = cache
+      ? turnToText([cache.fullMessage])
+      : (parentEntry.payload as unknown as SummaryPayload).body ?? "";
+    const excerpt = excerptSource ? firstMatchExcerpt(excerptSource, regex) : null;
+    const header = formatEntryLine(parentEntry);
+    hits.push(excerpt ? `${header}\n  ${excerpt}` : header);
+  }
+
+  if (hits.length === 0) return `No results found for "${query}".`;
+  const total = hits.length;
+  const summary = `Found ${total} match${total === 1 ? "" : "es"} for "${query}"`;
+  return `${summary}\n\n${hits.slice(0, 30).join("\n\n")}`;
+}
+
+export async function recallExpand(store: Store, id: string): Promise<string> {
+  const entry = await store.findById(id);
+  if (!entry) return `Entry ${id}: not found.`;
+  if (entry.kind === RECALL_CACHE_KIND) return `Entry ${id}: not expandable.`;
+  const header = formatEntryLine(entry);
+
+  const cache = await findCacheChild(store, id);
+  if (cache) return `${header}\n\n${turnToText([cache.fullMessage])}`;
+
+  const body = (entry.payload as unknown as SummaryPayload).body;
+  if (body) return `${header}\n\n${body}`;
+  return `${header}\n\n(no expanded content available — recall cache may have been cleared)`;
+}
+
+export async function recallBrowse(store: Store, limit = 25): Promise<string> {
+  const lines = await readSummaryLines(store, limit);
+  if (lines.length === 0) return "No conversation history.";
+  return ["Recent summary entries:", ...lines.map((l) => `  ${l}`)].join("\n");
+}