agent-sh 0.15.0 → 0.15.2

package/src/agent/nuclear-form.ts

@@ -0,0 +1,382 @@
+/**
+ * Nuclear form — compact one-liner summaries of conversation actions.
+ *
+ * Used by the three-tier history system:
+ *   Tier 1 (full content) → compacts into → Tier 2 (nuclear one-liners)
+ *   Tier 2 → flushes to → Tier 3 (history file on disk)
+ *
+ * Nuclear entries are the currency of Tier 2 and Tier 3.
+ */
+import type { ChatCompletionMessageParam } from "./llm-client.js";
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface NuclearEntry {
+  /** Global sequence number. */
+  seq: number;
+  /** Timestamp (Date.now()). */
+  ts: number;
+  /** Instance ID — 4-char hex identifying the agent-sh process. */
+  iid: string;
+  /**
+   * Entry kind. Core kinds are "user" | "agent" | "tool" | "error" | "session";
+   * advisors may emit additional labels.
+   */
+  kind: "user" | "agent" | "tool" | "error" | "session" | (string & {});
+  /** Tool name (for kind=tool or kind=error). */
+  tool?: string;
+  /** The one-liner summary — injected in startup context. */
+  sum: string;
+  /** Expanded content — on disk only, fetched by conversation_recall expand. */
+  body?: string;
+  /**
+   * Optional reasoning annotation. Nucleation advisors may populate this
+   * (e.g. by extracting `[why: ...]` from agent text) so the rationale
+   * survives into summaries. Displayed as `{why}` in formatNuclearLine.
+   */
+  why?: string;
+  /**
+   * Optional parent pointer for tree-shaped history. The default
+   * HistoryFile adapter ignores this and treats the file as linear;
+   * tree-aware HistoryAdapter implementations use it to fork and to
+   * walk a single path on resume.
+   */
+  parentSeq?: number;
+}
+
+/**
+ * Create a session-start marker entry. Markers use seq=0 by default —
+ * they are not part of the nuclear sequence and should not advance the
+ * sequence counter when read back from disk.
+ */
+export function createSessionMarker(iid: string, seq: number = 0): NuclearEntry {
+  return { seq, ts: Date.now(), iid, kind: "session", sum: "session start" };
+}
+
+/** Check if an entry is a session-start marker. */
+export function isSessionMarker(entry: NuclearEntry): boolean {
+  return entry.kind === "session";
+}
+
+// ── Tool classification ───────────────────────────────────────────
+
+/** Read-only tools whose results are dropped at Tier 1→2 (agent can re-read). */
+export const READ_ONLY_TOOLS = new Set([
+  "read_file", "grep", "glob", "ls", "search",
+]);
+
+/** Extensions opt their tools in via ToolRegistry.register when readOnly is set. */
+const extraReadOnlyTools = new Set<string>();
+
+export function registerReadOnlyTool(name: string): void {
+  extraReadOnlyTools.add(name);
+}
+
+export function unregisterReadOnlyTool(name: string): void {
+  extraReadOnlyTools.delete(name);
+}
+
+/** State-changing tools whose summaries are kept in nuclear memory. */
+export const WRITE_TOOLS = new Set([
+  "write_file", "edit_file", "write", "edit", "patch",
+]);
+
+// ── Eager nucleation ──────────────────────────────────────────────
+
+/** Body caps by entry kind (in characters). 0 = no body stored.
+ *  These are only recovered via conversation_recall expand — they
+ *  never enter the context window automatically, so be generous. */
+const BODY_CAPS: Record<string, number> = {
+  user: 8000,
+  agent: 8000,
+  tool: 16000,
+  error: 8000,
+};
+
+/**
+ * Produce a nuclear entry eagerly — called at each hook point as messages
+ * arrive, not during compaction. Returns { sum, body }.
+ */
+export function nucleate(
+  kind: "user" | "agent",
+  text: string,
+  iid: string,
+  seq: number,
+): NuclearEntry;
+
+export function nucleate(
+  kind: "tool" | "error",
+  toolName: string,
+  args: Record<string, unknown>,
+  resultContent: string,
+  isError: boolean,
+  iid: string,
+  seq: number,
+): NuclearEntry;
+
+export function nucleate(
+  kindOrName: "user" | "agent" | "tool" | "error",
+  textOrTool: string,
+  arg2: string | Record<string, unknown>,
+  arg3?: string | number,
+  arg4?: boolean | string,
+  arg5?: number | string,
+  arg6?: number,
+): NuclearEntry {
+  if (kindOrName === "user" || kindOrName === "agent") {
+    // Simple overload: nucleate("user", text, iid, seq)
+    const text = textOrTool;
+    const iid = arg2 as string;
+    const seq = arg3 as number;
+    const maxSum = kindOrName === "user" ? 200 : 150;
+    const cap = BODY_CAPS[kindOrName]!;
+    return {
+      seq, ts: Date.now(), iid,
+      kind: kindOrName,
+      sum: `${kindOrName}: "${truncate(text, maxSum)}"`,
+      body: text.length > cap ? truncate(text, cap) : text,
+    };
+  } else {
+    // Tool/error overload: nucleate("tool", toolName, args, resultContent, isError, iid, seq)
+    const toolName = textOrTool;
+    const args = arg2 as Record<string, unknown>;
+    const resultContent = arg3 as string;
+    const isError = arg4 as boolean;
+    const iid = arg5 as string;
+    const seq = arg6 as number;
+    const kind = isError ? "error" : "tool";
+    const summary = summarizeToolCall(toolName, args);
+    const enriched = isError
+      ? `error: ${toolName} ${truncate(resultContent, 80)}`
+      : enrichWithResult(toolName, summary, resultContent);
+
+    let body: string | undefined;
+    if (READ_ONLY_TOOLS.has(toolName)) {
+      // Read-only tools: no body (agent can re-read the file)
+      body = undefined;
+    } else {
+      const cap = BODY_CAPS[kind]!;
+      const fullBody = buildToolBody(toolName, args, resultContent);
+      body = fullBody.length > cap ? truncate(fullBody, cap) : fullBody;
+    }
+
+    return {
+      seq, ts: Date.now(), iid,
+      kind,
+      tool: toolName,
+      sum: enriched,
+      body,
+    };
+  }
+}
+
+/** Build body text for a tool result — command + truncated output. */
+function buildToolBody(toolName: string, args: Record<string, unknown>, result: string): string {
+  const argStr = toolName === "bash" || toolName === "user_shell"
+    ? String(args.command ?? "")
+    : JSON.stringify(args);
+  const maxResult = 12000;
+  const truncated = result.length > maxResult
+    ? result.slice(0, Math.floor(maxResult * 0.6))
+      + `\n[… truncated …]\n`
+      + result.slice(result.length - Math.floor(maxResult * 0.4))
+    : result;
+  return `$ ${argStr}\n${truncated}`;
+}
+
+// ── Nuclear entry generation ──────────────────────────────────────
+
+/**
+ * Generate nuclear entries from a logical turn (a sequence of messages
+ * starting with a user message, followed by assistant + tool messages).
+ */
+export function toNuclearEntries(
+  messages: ChatCompletionMessageParam[],
+  startSeq: number,
+  instanceId: string,
+): NuclearEntry[] {
+  const entries: NuclearEntry[] = [];
+  let seq = startSeq;
+  const ts = Date.now();
+
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      const text = typeof msg.content === "string" ? msg.content : "";
+      // Skip compaction markers
+      if (text.startsWith("[")) continue;
+      entries.push({
+        seq: seq++, ts, iid: instanceId,
+        kind: "user",
+        sum: `user: "${truncate(text, 80)}"`,
+      });
+    } else if (msg.role === "assistant") {
+      // Process tool calls
+      if ("tool_calls" in msg && msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+          if (!("function" in tc)) continue;
+          const name = tc.function.name;
+          let args: Record<string, unknown> = {};
+          try { args = JSON.parse(tc.function.arguments); } catch {}
+
+          // Store the tool call — we'll enrich it when we see the result
+          entries.push({
+            seq: seq++, ts, iid: instanceId,
+            kind: "tool",
+            tool: name,
+            sum: summarizeToolCall(name, args),
+          });
+        }
+      } else if (typeof msg.content === "string" && msg.content) {
+        entries.push({
+          seq: seq++, ts, iid: instanceId,
+          kind: "agent",
+          sum: `agent: "${truncate(msg.content, 60)}"`,
+        });
+      }
+    } else if (msg.role === "tool") {
+      // Enrich the most recent tool entry with result info
+      const content = typeof msg.content === "string" ? msg.content : "";
+      const lastTool = findLastTool(entries);
+      if (lastTool) {
+        const isError = content.startsWith("Error:");
+        if (isError) {
+          lastTool.kind = "error";
+          lastTool.sum = `error: ${lastTool.tool} ${truncate(content.slice(7).trim(), 80)}`;
+        } else {
+          lastTool.sum = enrichWithResult(lastTool.tool ?? "", lastTool.sum, content);
+        }
+      }
+    }
+  }
+
+  return entries;
+}
+
+// ── Formatting ────────────────────────────────────────────────────
+
+/** Format a nuclear entry as a display line (for in-context injection). */
+export function formatNuclearLine(entry: NuclearEntry): string {
+  const d = new Date(entry.ts);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  // ISO-ish compact: 2026-04-13 14:05
+  const stamp = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  const whyTag = entry.why ? ` {${entry.why.length > 80 ? entry.why.slice(0, 77) + "..." : entry.why}}` : "";
+  return `#${entry.seq} [${stamp}] ${entry.sum}${whyTag}`;
+}
+
+// ── Serialization (JSONL for history file) ────────────────────────
+
+/** Serialize a nuclear entry to a JSONL line. */
+export function serializeEntry(entry: NuclearEntry): string {
+  return JSON.stringify(entry);
+}
+
+/** Deserialize a JSONL line to a nuclear entry. Returns null on parse failure. */
+export function deserializeEntry(line: string): NuclearEntry | null {
+  try {
+    const obj = JSON.parse(line);
+    if (typeof obj.seq === "number" && typeof obj.sum === "string") {
+      return obj as NuclearEntry;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Classification helpers ────────────────────────────────────────
+
+/** Check if a nuclear entry represents a read-only action (should be dropped). */
+export function isReadOnly(entry: NuclearEntry): boolean {
+  if (entry.kind !== "tool" || entry.tool == null) return false;
+  return READ_ONLY_TOOLS.has(entry.tool) || extraReadOnlyTools.has(entry.tool);
+}
+
+/** Compile a search query, falling back to whitespace-split AND-of-words on invalid regex. */
+export function compileSearchRegex(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");
+  }
+}
+
+/** Match a writable entry against a search regex; null if filtered or no match. */
+export function matchEntry(entry: NuclearEntry, re: RegExp): { entry: NuclearEntry; line: string } | null {
+  if (isReadOnly(entry)) return null;
+  const text = [entry.sum, entry.body].filter(Boolean).join("\n");
+  return re.test(text) ? { entry, line: formatNuclearLine(entry) } : null;
+}
+
+// ── Internal helpers ──────────────────────────────────────────────
+
+function truncate(text: string, maxLen: number): string {
+  const oneLine = text.replace(/\n/g, " ").trim();
+  return oneLine.length > maxLen ? oneLine.slice(0, maxLen) + "..." : oneLine;
+}
+
+function findLastTool(entries: NuclearEntry[]): NuclearEntry | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i]!.kind === "tool") return entries[i];
+  }
+  return undefined;
+}
+
+function summarizeToolCall(name: string, args: Record<string, unknown>): string {
+  switch (name) {
+    case "bash":
+      return `bash: ${truncate(String(args.command ?? ""), 60)}`;
+    case "user_shell":
+      return `user_shell: ${truncate(String(args.command ?? ""), 60)}`;
+    case "edit_file":
+      return `edit_file ${args.path ?? ""}`;
+    case "write_file":
+    case "write":
+      return `write_file ${args.path ?? args.file_path ?? ""}`;
+    case "read_file":
+      return `read_file ${args.path ?? args.file_path ?? ""}`;
+    case "grep":
+      return `grep "${truncate(String(args.pattern ?? ""), 30)}"`;
+    case "glob":
+      return `glob ${args.pattern ?? ""}`;
+    case "ls":
+      return `ls ${args.path ?? "."}`;
+    default:
+      return `${name}`;
+  }
+}
+
+function enrichWithResult(toolName: string, summary: string, result: string): string {
+  const lines = result.split("\n");
+  const lineCount = lines.length;
+
+  switch (toolName) {
+    case "bash":
+    case "user_shell": {
+      // Extract exit code from result if present
+      const exitMatch = result.match(/exit code[:\s]*(\d+)/i) ?? result.match(/exit\s+(\d+)/);
+      const exitCode = exitMatch ? exitMatch[1] : "0";
+      return `${summary} (exit ${exitCode}, ${lineCount} lines)`;
+    }
+    case "edit_file":
+    case "edit": {
+      // Try to extract +/- counts from result
+      const addMatch = result.match(/\+(\d+)/);
+      const delMatch = result.match(/-(\d+)/);
+      if (addMatch || delMatch) {
+        return `${summary} (+${addMatch?.[1] ?? 0}/-${delMatch?.[1] ?? 0})`;
+      }
+      return `${summary} (edited)`;
+    }
+    case "write_file":
+    case "write": {
+      const created = result.toLowerCase().includes("created") ? "created" : "written";
+      return `${summary} (${created}, ${lineCount} lines)`;
+    }
+    default:
+      return `${summary} (${lineCount} lines)`;
+  }
+}

package/src/agent/providers/deepseek.ts

@@ -0,0 +1,39 @@
+/**
+ * Native DeepSeek (api.deepseek.com). V4 ignores reasoning_effort for
+ * on/off — disable lives in a separate `thinking` field that defaults
+ * to enabled. The hook always attaches; provider registration via env
+ * is opt-in alongside any settings.json entry.
+ */
+import type { AgentContext } from "../host-types.js";
+import { resolveApiKey } from "../../cli/auth/keys.js";
+
+const BASE_URL = "https://api.deepseek.com";
+const DEFAULT_MODELS = [
+  { id: "deepseek-v4-flash", reasoning: true, echoReasoning: true, contextWindow: 1_000_000 },
+  { id: "deepseek-v4-pro", reasoning: true, echoReasoning: true, contextWindow: 1_000_000 },
+];
+
+function buildReasoningParams(level: string, _model?: string): Record<string, unknown> {
+  return level === "off"
+    ? { thinking: { type: "disabled" } }
+    : { thinking: { type: "enabled" }, reasoning_effort: level };
+}
+
+export default function activate(ctx: AgentContext): void {
+  ctx.agent.providers.configure("deepseek", {
+    reasoningParams: buildReasoningParams,
+    // Native DeepSeek reports caching as flat hit/miss counts, not the
+    // OpenAI-standard prompt_tokens_details.cached_tokens the default reads.
+    cacheTokens: (u) => {
+      const hit = u.prompt_cache_hit_tokens;
+      return typeof hit === "number" ? hit : undefined;
+    },
+  });
+  ctx.agent.providers.register({
+    id: "deepseek",
+    apiKey: resolveApiKey("deepseek").key ?? undefined,
+    baseURL: BASE_URL,
+    defaultModel: DEFAULT_MODELS[0].id,
+    models: DEFAULT_MODELS,
+  });
+}

package/src/agent/providers/ollama.ts

@@ -0,0 +1,92 @@
+/**
+ * Ollama provider — local daemon or Ollama Cloud.
+ *
+ * Cloud auth:  agent-sh auth login ollama-cloud
+ * Local host:  OLLAMA_HOST (default http://localhost:11434)
+ *
+ * Catalog comes from /api/tags; per-model context length is fetched
+ * from /api/show. Chat goes through the OpenAI-compatible /v1 shim.
+ */
+import type { AgentContext } from "../host-types.js";
+import { resolveApiKey } from "../../cli/auth/keys.js";
+
+const ECHO_REASONING_PATTERNS: RegExp[] = [/deepseek/i];
+
+export default function activate(ctx: AgentContext): void {
+  const cloudKey = resolveApiKey("ollama-cloud").key ?? process.env.OLLAMA_API_KEY;
+  const host = cloudKey
+    ? "https://ollama.com"
+    : (process.env.OLLAMA_HOST ?? "http://localhost:11434").replace(/\/$/, "");
+  const id = cloudKey ? "ollama-cloud" : "ollama";
+
+  const sdkKey = cloudKey || "no-key";
+  const noAuth = !cloudKey;
+  const baseURL = `${host}/v1`;
+  const headers: Record<string, string> = {};
+  if (cloudKey) headers.Authorization = `Bearer ${cloudKey}`;
+
+  ctx.agent.providers.configure(id, {
+    reasoningParams: (level) => {
+      if (level === "off") return { reasoning_effort: "none" };
+      return { reasoning_effort: level === "xhigh" ? "high" : level };
+    },
+  });
+
+  ctx.agent.providers.register({ id, apiKey: sdkKey, baseURL, models: [], noAuth });
+
+  fetchCatalog(host, headers).then((models) => {
+    if (models.length === 0) return;
+    ctx.agent.providers.register({
+      id,
+      apiKey: sdkKey,
+      baseURL,
+      defaultModel: models[0]!.id,
+      models,
+      noAuth,
+    });
+  }).catch(() => {});
+}
+
+async function fetchCatalog(
+  host: string,
+  headers: Record<string, string>,
+): Promise<{ id: string; contextWindow?: number; echoReasoning: boolean }[]> {
+  const tagsRes = await fetch(`${host}/api/tags`, { headers });
+  if (!tagsRes.ok) return [];
+  const tagsData = await tagsRes.json() as { models?: { name: string }[] };
+  const names = (tagsData.models ?? []).map((m) => m.name);
+  if (names.length === 0) return [];
+
+  const ctxs = await Promise.all(
+    names.map((name) => fetchContextLength(host, headers, name).catch(() => undefined)),
+  );
+  return names.map((name, i) => ({
+    id: name,
+    contextWindow: ctxs[i],
+    echoReasoning: ECHO_REASONING_PATTERNS.some((re) => re.test(name)),
+  }));
+}
+
+async function fetchContextLength(
+  host: string,
+  headers: Record<string, string>,
+  name: string,
+): Promise<number | undefined> {
+  const res = await fetch(`${host}/api/show`, {
+    method: "POST",
+    headers: { ...headers, "Content-Type": "application/json" },
+    body: JSON.stringify({ name }),
+  });
+  if (!res.ok) return undefined;
+  const data = await res.json() as { model_info?: Record<string, unknown> };
+  const info = data.model_info ?? {};
+  const arch = info["general.architecture"] as string | undefined;
+  if (arch) {
+    const ctx = info[`${arch}.context_length`];
+    if (typeof ctx === "number") return ctx;
+  }
+  for (const [k, v] of Object.entries(info)) {
+    if (k.endsWith(".context_length") && typeof v === "number") return v;
+  }
+  return undefined;
+}

package/src/agent/providers/openai-compatible.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenAI Chat Completions-compatible local/3rd-party server (Ollama, LM
+ * Studio, vLLM, llama.cpp, …). No reasoning hook — the right shape depends
+ * on which model the server is serving; user extensions can add one.
+ */
+import type { AgentContext } from "../host-types.js";
+
+export default function activate(ctx: AgentContext): void {
+  const baseURL = process.env.OPENAI_BASE_URL;
+  if (!baseURL) return;
+
+  // Local servers often need no key; SDK still wants a non-empty string.
+  const apiKey = process.env.OPENAI_API_KEY || "no-key";
+  const id = "openai-compatible";
+
+  ctx.agent.providers.register({ id, apiKey, baseURL, models: [] });
+  fetchModels(baseURL, apiKey).then((models) => {
+    if (models.length === 0) return;
+    ctx.agent.providers.register({
+      id,
+      apiKey,
+      baseURL,
+      defaultModel: models[0],
+      models,
+    });
+  }).catch(() => { /* leave empty — user supplies via --model */ });
+}
+
+async function fetchModels(baseURL: string, apiKey: string): Promise<string[]> {
+  const headers: Record<string, string> = {};
+  if (apiKey && apiKey !== "no-key") headers.Authorization = `Bearer ${apiKey}`;
+  const res = await fetch(`${baseURL.replace(/\/$/, "")}/models`, { headers });
+  if (!res.ok) return [];
+  const data = await res.json() as { data?: { id: string }[] };
+  return (data.data ?? []).map((m) => m.id);
+}

package/src/agent/providers/openai.ts

@@ -0,0 +1,52 @@
+/**
+ * Cloud OpenAI (api.openai.com). reasoning_effort vocabulary diverges per
+ * family: o-series has no off; gpt-5-codex floors at "low"; plain gpt-5
+ * floors at "minimal"; gpt-5.1+ accepts "none" as documented full off.
+ * Top tier: only gpt-5.1-codex-max and gpt-5.[4-9]+ accept "xhigh"; others
+ * clamp to "high".
+ */
+import type { AgentContext } from "../host-types.js";
+import { resolveApiKey } from "../../cli/auth/keys.js";
+
+const CLOUD_MODELS = [
+  { id: "gpt-5", reasoning: true },
+  { id: "gpt-4.1", reasoning: false },
+  { id: "gpt-4o", reasoning: false },
+  { id: "gpt-4o-mini", reasoning: false },
+  { id: "o3", reasoning: true },
+  { id: "o3-mini", reasoning: true },
+];
+
+function offEffortFor(model: string): string | null {
+  if (/^o\d/.test(model)) return null;
+  if (model.startsWith("gpt-5-codex")) return "low";
+  if (/^gpt-5\.[1-9]/.test(model)) return "none";
+  if (/^gpt-5(?!\.)/.test(model)) return "minimal";
+  return null;
+}
+
+function supportsXhigh(model: string): boolean {
+  if (model.startsWith("gpt-5.1-codex-max")) return true;
+  return /^gpt-5\.[4-9]/.test(model);
+}
+
+function buildReasoningParams(level: string, model?: string): Record<string, unknown> {
+  if (level !== "off") {
+    const effort = level === "xhigh" && !(model && supportsXhigh(model)) ? "high" : level;
+    return { reasoning_effort: effort };
+  }
+  const off = model ? offEffortFor(model) : null;
+  return off ? { reasoning_effort: off } : {};
+}
+
+export default function activate(ctx: AgentContext): void {
+  if (process.env.OPENAI_BASE_URL) return; // openai-compatible handles this
+
+  ctx.agent.providers.configure("openai", { reasoningParams: buildReasoningParams });
+  ctx.agent.providers.register({
+    id: "openai",
+    apiKey: resolveApiKey("openai").key ?? undefined,
+    defaultModel: CLOUD_MODELS[0].id,
+    models: CLOUD_MODELS,
+  });
+}