agent-sh 0.9.0 → 0.10.0

package/dist/agent/history-file.d.ts

@@ -12,20 +12,29 @@ export declare class HistoryFile {
      */
     append(entries: NuclearEntry[]): Promise<void>;
     /**
-     * Read the most recent N entries from the history file.
+     * Read the most recent N entries from the history file, filtered.
+     * Read-only tool calls (read_file, grep, glob, ls) are excluded so
+     * the returned entries are all meaningful conversation turns.
      */
     readRecent(maxEntries?: number): Promise<NuclearEntry[]>;
     /**
-     * Search history entries by regex/keyword.
+     * Search history entries by regex/keyword, scanning the file from the
+     * end. Caps at ~20 MB of content to bound cost on 100 MB history files.
      */
     search(query: string): Promise<{
         entry: NuclearEntry;
         line: string;
     }[]>;
+    /** Find a single entry by sequence number, streaming from the file end. */
+    findBySeq(seq: number): Promise<NuclearEntry | null>;
+    getSize(): Promise<number>;
     /**
-     * Get file size in bytes. Returns 0 if file doesn't exist.
+     * Yield lines from the file in reverse order (newest-first). Buffers
+     * pre-first-newline bytes across chunks to stitch lines that straddle
+     * a boundary; carries raw bytes (not strings) so UTF-8 characters split
+     * by a chunk boundary are never decoded mid-codepoint.
      */
-    getSize(): Promise<number>;
+    private streamReverseLines;
     /**
      * Truncate from the front if file exceeds historyMaxBytes.
      * Uses a lock file for the rewrite operation.

package/dist/agent/history-file.js

@@ -1,17 +1,16 @@
 /**
- * Persistent history file — Tier 3 of the three-tier history system.
+ * Persistent history file — append-only JSONL at ~/.agent-sh/history.
  *
- * Append-only JSONL file at ~/.agent-sh/history. Multiple agent-sh
- * instances can write concurrently — each line is under PIPE_BUF so
- * O_APPEND writes are atomic. Only truncation (which rewrites the file)
- * uses a lock file for safety.
+ * Multiple agent-sh instances can write concurrently — each line is under
+ * PIPE_BUF so O_APPEND writes are atomic. Only truncation (which rewrites
+ * the file) uses a lock file for safety.
  */
 import * as fs from "node:fs/promises";
 import * as fss from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
 import { CONFIG_DIR, getSettings } from "../settings.js";
-import { serializeEntry, deserializeEntry, formatNuclearLine, } from "./nuclear-form.js";
+import { serializeEntry, deserializeEntry, formatNuclearLine, isReadOnly, } from "./nuclear-form.js";
 const HISTORY_PATH = path.join(CONFIG_DIR, "history");
 const LOCK_PATH = HISTORY_PATH + ".lock";
 const LOCK_STALE_MS = 10_000; // consider lock stale after 10s
@@ -34,29 +33,27 @@ export class HistoryFile {
         await this.maybeTruncate();
     }
     /**
-     * Read the most recent N entries from the history file.
+     * Read the most recent N entries from the history file, filtered.
+     * Read-only tool calls (read_file, grep, glob, ls) are excluded so
+     * the returned entries are all meaningful conversation turns.
      */
     async readRecent(maxEntries) {
         maxEntries ??= getSettings().historyStartupEntries;
-        let content;
-        try {
-            content = await fs.readFile(this.filePath, "utf-8");
-        }
-        catch {
-            return [];
-        }
-        const lines = content.trim().split("\n").filter(Boolean);
-        const recent = lines.slice(-maxEntries);
-        const entries = [];
-        for (const line of recent) {
+        const want = maxEntries * 3 + 10;
+        const recent = []; // newest-first
+        for await (const line of this.streamReverseLines()) {
             const entry = deserializeEntry(line);
-            if (entry)
-                entries.push(entry);
+            if (entry && !isReadOnly(entry))
+                recent.push(entry);
+            if (recent.length >= want)
+                break;
         }
-        return entries;
+        // Caller expects oldest-to-newest order.
+        return recent.reverse().slice(-maxEntries);
     }
     /**
-     * Search history entries by regex/keyword.
+     * Search history entries by regex/keyword, scanning the file from the
+     * end. Caps at ~20 MB of content to bound cost on 100 MB history files.
      */
     async search(query) {
         if (!query.trim())
@@ -67,28 +64,37 @@ export class HistoryFile {
         }
         catch {
             const words = query.split(/\s+/).filter((w) => w.length > 0);
-            const pattern = words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
-            regex = new RegExp(pattern, "i");
-        }
-        let content;
-        try {
-            content = await fs.readFile(this.filePath, "utf-8");
-        }
-        catch {
-            return [];
+            const escaped = words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+            const lookaheads = escaped.map((w) => `(?=.*${w})`).join("");
+            regex = new RegExp(lookaheads, "i");
         }
+        const budgetBytes = 20 * 1024 * 1024;
+        let scanned = 0;
         const results = [];
-        for (const line of content.trim().split("\n")) {
+        for await (const line of this.streamReverseLines()) {
+            scanned += line.length + 1;
+            if (scanned > budgetBytes)
+                break;
             const entry = deserializeEntry(line);
-            if (entry && regex.test(entry.sum)) {
+            if (!entry || isReadOnly(entry))
+                continue;
+            // Body can hold ~4000 chars the summary truncates — search both.
+            const searchText = [entry.sum, entry.body].filter(Boolean).join("\n");
+            if (regex.test(searchText)) {
                 results.push({ entry, line: formatNuclearLine(entry) });
             }
         }
         return results;
     }
-    /**
-     * Get file size in bytes. Returns 0 if file doesn't exist.
-     */
+    /** Find a single entry by sequence number, streaming from the file end. */
+    async findBySeq(seq) {
+        for await (const line of this.streamReverseLines()) {
+            const entry = deserializeEntry(line);
+            if (entry && entry.seq === seq)
+                return entry;
+        }
+        return null;
+    }
     async getSize() {
         try {
             const stat = await fs.stat(this.filePath);
@@ -98,6 +104,74 @@ export class HistoryFile {
             return 0;
         }
     }
+    /**
+     * Yield lines from the file in reverse order (newest-first). Buffers
+     * pre-first-newline bytes across chunks to stitch lines that straddle
+     * a boundary; carries raw bytes (not strings) so UTF-8 characters split
+     * by a chunk boundary are never decoded mid-codepoint.
+     */
+    async *streamReverseLines(chunkBytes = 1 << 20) {
+        let handle;
+        let fileSize;
+        try {
+            const stat = await fs.stat(this.filePath);
+            fileSize = stat.size;
+            if (fileSize === 0)
+                return;
+            handle = await fs.open(this.filePath, "r");
+        }
+        catch {
+            return;
+        }
+        try {
+            let position = fileSize;
+            let pending = Buffer.alloc(0);
+            while (position > 0) {
+                const readSize = Math.min(chunkBytes, position);
+                position -= readSize;
+                const buf = Buffer.alloc(readSize);
+                await handle.read(buf, 0, readSize, position);
+                // pending: start-bytes of a line whose first \n lives in this chunk.
+                const combined = Buffer.concat([buf, pending]);
+                const newlineIdxs = [];
+                for (let i = 0; i < combined.length; i++) {
+                    if (combined[i] === 0x0A)
+                        newlineIdxs.push(i);
+                }
+                if (newlineIdxs.length === 0) {
+                    pending = combined;
+                    continue;
+                }
+                const firstNl = newlineIdxs[0];
+                const lastNl = newlineIdxs[newlineIdxs.length - 1];
+                // Post-last-\n: a line straddling into the later chunk (completed
+                // here because `pending` was appended at the end of `combined`).
+                const trailing = combined.subarray(lastNl + 1);
+                if (trailing.length > 0)
+                    yield trailing.toString("utf-8");
+                for (let i = newlineIdxs.length - 1; i >= 1; i--) {
+                    const seg = combined.subarray(newlineIdxs[i - 1] + 1, newlineIdxs[i]);
+                    if (seg.length > 0)
+                        yield seg.toString("utf-8");
+                }
+                // Pre-first-\n: partial if there's more file to the left, else complete.
+                const leading = combined.subarray(0, firstNl);
+                if (position === 0) {
+                    if (leading.length > 0)
+                        yield leading.toString("utf-8");
+                    pending = Buffer.alloc(0);
+                }
+                else {
+                    pending = leading;
+                }
+            }
+            if (pending.length > 0)
+                yield pending.toString("utf-8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
     // ── Truncation ──────────────────────────────────────────────────
     /**
      * Truncate from the front if file exceeds historyMaxBytes.

package/dist/agent/nuclear-form.d.ts

@@ -15,17 +15,42 @@ export interface NuclearEntry {
     ts: number;
     /** Instance ID — 4-char hex identifying the agent-sh process. */
     iid: string;
-    /** Entry kind. */
-    kind: "user" | "agent" | "tool" | "error";
+    /**
+     * 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. */
+    /** 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;
 }
+/**
+ * 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 declare function createSessionMarker(iid: string, seq?: number): NuclearEntry;
+/** Check if an entry is a session-start marker. */
+export declare function isSessionMarker(entry: NuclearEntry): boolean;
 /** Read-only tools whose results are dropped at Tier 1→2 (agent can re-read). */
 export declare const READ_ONLY_TOOLS: Set<string>;
 /** State-changing tools whose summaries are kept in nuclear memory. */
 export declare const WRITE_TOOLS: Set<string>;
+/**
+ * Produce a nuclear entry eagerly — called at each hook point as messages
+ * arrive, not during compaction. Returns { sum, body }.
+ */
+export declare function nucleate(kind: "user" | "agent", text: string, iid: string, seq: number): NuclearEntry;
+export declare function nucleate(kind: "tool" | "error", toolName: string, args: Record<string, unknown>, resultContent: string, isError: boolean, iid: string, seq: number): NuclearEntry;
 /**
  * Generate nuclear entries from a logical turn (a sequence of messages
  * starting with a user message, followed by assistant + tool messages).

package/dist/agent/nuclear-form.js

@@ -1,3 +1,15 @@
+/**
+ * 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, seq = 0) {
+    return { seq, ts: Date.now(), iid, kind: "session", sum: "session start" };
+}
+/** Check if an entry is a session-start marker. */
+export function isSessionMarker(entry) {
+    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([
@@ -7,6 +19,76 @@ export const READ_ONLY_TOOLS = new Set([
 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 = {
+    user: 8000,
+    agent: 8000,
+    tool: 16000,
+    error: 8000,
+};
+export function nucleate(kindOrName, textOrTool, arg2, arg3, arg4, arg5, arg6) {
+    if (kindOrName === "user" || kindOrName === "agent") {
+        // Simple overload: nucleate("user", text, iid, seq)
+        const text = textOrTool;
+        const iid = arg2;
+        const seq = arg3;
+        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;
+        const resultContent = arg3;
+        const isError = arg4;
+        const iid = arg5;
+        const seq = arg6;
+        const kind = isError ? "error" : "tool";
+        const summary = summarizeToolCall(toolName, args);
+        const enriched = isError
+            ? `error: ${toolName} ${truncate(resultContent, 80)}`
+            : enrichWithResult(toolName, summary, resultContent);
+        let body;
+        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, args, result) {
+    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
@@ -82,7 +164,8 @@ export function formatNuclearLine(entry) {
     const pad = (n) => 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())}`;
-    return `#${entry.seq} [${stamp}] ${entry.sum}`;
+    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. */
@@ -138,8 +221,6 @@ function summarizeToolCall(name, args) {
             return `glob ${args.pattern ?? ""}`;
         case "ls":
             return `ls ${args.path ?? "."}`;
-        case "display":
-            return `display: ${truncate(String(args.command ?? ""), 60)}`;
         default:
             return `${name}`;
     }

package/dist/agent/skills.d.ts

@@ -4,11 +4,9 @@ export interface Skill {
     filePath: string;
     baseDir: string;
 }
-/**
- * Discover global skills (stable across cwd changes).
- * Default: ~/.agents/skills/, plus any skillPaths from settings.
- */
+/** Discover global skills (stable across cwd changes). Cached per-process. */
 export declare function discoverGlobalSkills(): Skill[];
+export declare function invalidateGlobalSkillsCache(): void;
 /**
  * Discover project-level skills from .agents/skills/ in cwd hierarchy.
  * Scans from cwd up to git root.

package/dist/agent/skills.js

@@ -124,11 +124,13 @@ function addUnique(target, source, seen) {
         }
     }
 }
-/**
- * Discover global skills (stable across cwd changes).
- * Default: ~/.agents/skills/, plus any skillPaths from settings.
- */
+// Global skill sources are stable within a session, so cache the result
+// to skip filesystem scans on every system-prompt:build.
+let _cachedGlobalSkills = null;
+/** Discover global skills (stable across cwd changes). Cached per-process. */
 export function discoverGlobalSkills() {
+    if (_cachedGlobalSkills)
+        return _cachedGlobalSkills;
     const seen = new Set();
     const skills = [];
     addUnique(skills, scanDir(path.join(os.homedir(), ".agent-sh", "skills")), seen);
@@ -136,8 +138,12 @@ export function discoverGlobalSkills() {
     for (const p of settings.skillPaths ?? []) {
         addUnique(skills, scanDir(path.resolve(expandHome(p))), seen);
     }
+    _cachedGlobalSkills = skills;
     return skills;
 }
+export function invalidateGlobalSkillsCache() {
+    _cachedGlobalSkills = null;
+}
 /**
  * Discover project-level skills from .agents/skills/ in cwd hierarchy.
  * Scans from cwd up to git root.

package/dist/agent/subagent.d.ts

@@ -29,6 +29,29 @@ export interface SubagentOptions {
     signal?: AbortSignal;
     /** Max tool loop iterations (default 20). */
     maxIterations?: number;
+    /**
+     * Ambient context rebuilt per iteration, same shape the parent's
+     * streamResponse uses. If provided, the subagent sees budget,
+     * metacognitive signals, in-flight siblings, etc.
+     */
+    dynamicContext?: string;
+    /**
+     * Per-subagent token budget. When total (prompt+completion) tokens
+     * exceed this, the subagent terminates gracefully on the next
+     * iteration. The parent's daily budget still counts these tokens
+     * via onUsage; this is an additional per-call cap.
+     */
+    budgetTokens?: number;
+    /**
+     * Invoked after every streamed LLM response with its usage totals.
+     * The parent uses this to forward to its event bus so global budget
+     * tracking stays accurate.
+     */
+    onUsage?: (usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    }) => void;
 }
 /**
  * Run a subagent to completion.

package/dist/agent/subagent.js

@@ -4,7 +4,7 @@ import { ConversationState } from "./conversation-state.js";
  * Returns the final response text.
  */
 export async function runSubagent(opts) {
-    const { llmClient, tools, systemPrompt, task, model, bus, signal, maxIterations = 20, } = opts;
+    const { llmClient, tools, systemPrompt, task, model, bus, signal, maxIterations = 20, dynamicContext, budgetTokens, onUsage, } = opts;
     const toolMap = new Map(tools.map(t => [t.name, t]));
     const apiTools = tools.map(t => ({
         type: "function",
@@ -18,11 +18,21 @@ export async function runSubagent(opts) {
     conversation.addUserMessage(task);
     let fullResponseText = "";
     let iterations = 0;
+    let tokensConsumed = 0;
+    let budgetExhausted = false;
     while (iterations++ < maxIterations) {
         if (signal?.aborted)
             break;
+        if (budgetTokens != null && tokensConsumed >= budgetTokens) {
+            budgetExhausted = true;
+            break;
+        }
         // Stream LLM response
-        const { text, toolCalls, assistantContent, assistantToolCalls } = await streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal);
+        const { text, toolCalls, assistantContent, assistantToolCalls, usage } = await streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal, dynamicContext);
+        if (usage) {
+            tokensConsumed += usage.total_tokens || 0;
+            onUsage?.(usage);
+        }
         fullResponseText += text;
         conversation.addAssistantMessage(assistantContent, assistantToolCalls);
         // No tool calls → done
@@ -34,7 +44,7 @@ export async function runSubagent(opts) {
                 break;
             const tool = toolMap.get(tc.name);
             if (!tool) {
-                conversation.addToolResult(tc.id, `Error: Unknown tool "${tc.name}"`);
+                conversation.addToolResult(tc.id, `Error: Unknown tool "${tc.name}"`, true);
                 continue;
             }
             let args;
@@ -42,7 +52,7 @@ export async function runSubagent(opts) {
                 args = JSON.parse(tc.argumentsJson);
             }
             catch {
-                conversation.addToolResult(tc.id, `Error: Invalid JSON arguments for ${tc.name}`);
+                conversation.addToolResult(tc.id, `Error: Invalid JSON arguments for ${tc.name}`, true);
                 continue;
             }
             // Emit tool events for TUI (if bus provided)
@@ -72,20 +82,29 @@ export async function runSubagent(opts) {
                 });
             }
             const content = result.isError ? `Error: ${result.content}` : result.content;
-            conversation.addToolResult(tc.id, content);
+            conversation.addToolResult(tc.id, content, !!result.isError);
         }
     }
+    if (budgetExhausted) {
+        const note = `\n\n[Subagent terminated: token budget (${budgetTokens}) exhausted after ${tokensConsumed} tokens. Returning partial progress.]`;
+        return fullResponseText + note;
+    }
     return fullResponseText;
 }
 /** Stream a single LLM response. */
-async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal) {
+async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal, dynamicContext) {
     let text = "";
     const pendingToolCalls = [];
+    let usage = null;
+    const messages = [
+        { role: "system", content: systemPrompt },
+    ];
+    if (dynamicContext) {
+        messages.push({ role: "user", content: `<context>\n${dynamicContext}\n</context>` });
+        messages.push({ role: "assistant", content: "Understood." });
+    }
     const stream = await llmClient.stream({
-        messages: [
-            { role: "system", content: systemPrompt },
-            ...conversation.getMessages(),
-        ],
+        messages: [...messages, ...conversation.getMessages()],
         tools: apiTools.length > 0 ? apiTools : undefined,
         model,
         signal,
@@ -93,6 +112,14 @@ async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model
     for await (const chunk of stream) {
         if (signal?.aborted)
             break;
+        if (chunk.usage) {
+            const u = chunk.usage;
+            usage = {
+                prompt_tokens: u.prompt_tokens ?? 0,
+                completion_tokens: u.completion_tokens ?? 0,
+                total_tokens: u.total_tokens ?? 0,
+            };
+        }
         const choice = chunk.choices[0];
         if (!choice)
             continue;
@@ -112,8 +139,23 @@ async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model
             }
         }
     }
+    // Normalize arguments JSON (same fix as agent-loop): strict providers
+    // reject empty "" on replay next turn even though OpenAI is lenient.
+    for (const tc of pendingToolCalls) {
+        const s = tc.argumentsJson.trim();
+        if (s === "") {
+            tc.argumentsJson = "{}";
+            continue;
+        }
+        try {
+            JSON.parse(s);
+        }
+        catch {
+            tc.argumentsJson = "{}";
+        }
+    }
     const assistantToolCalls = pendingToolCalls.length
         ? pendingToolCalls.map(tc => ({ id: tc.id, function: { name: tc.name, arguments: tc.argumentsJson } }))
         : undefined;
-    return { text, toolCalls: pendingToolCalls, assistantContent: text || null, assistantToolCalls };
+    return { text, toolCalls: pendingToolCalls, assistantContent: text || null, assistantToolCalls, usage };
 }

package/dist/agent/system-prompt.d.ts

@@ -1,4 +1,12 @@
 import type { ContextManager } from "../context-manager.js";
+import { type Skill } from "./skills.js";
+/**
+ * Format skills for inline display in prompt.
+ * Shows name, description, and file path so the model can decide immediately
+ * whether to load a skill — no extra round-trip needed.
+ */
+export declare function formatSkillsBlock(skills: Skill[]): string;
+export declare function loadGlobalAgentsMd(): string | null;
 /**
  * Static system prompt — identical across all queries, cacheable.
  * Contains only identity and behavioral instructions.
@@ -10,4 +18,29 @@ export declare const STATIC_SYSTEM_PROMPT: string;
  *
  * Runs through the "dynamic-context:build" handler so extensions can advise.
  */
-export declare function buildDynamicContext(contextManager: ContextManager, shellBudgetTokens?: number): string;
+export interface TokenStatus {
+    /** Estimated prompt tokens (API-grounded when available, else chars/4). */
+    promptTokens: number;
+    /** Model's context window in tokens. */
+    contextWindow: number;
+}
+/**
+ * CWD-scoped static context: project conventions (CLAUDE.md / AGENT.md)
+ * and discovered skills. Stable for a given cwd — callers should cache
+ * on cwd identity rather than rebuilding per LLM iteration.
+ */
+export declare function buildStaticByCwd(cwd: string): string;
+/**
+ * Per-iteration dynamic context: date, working directory, token usage.
+ * Rebuilt every LLM call. Extension advisors add more sections (budget,
+ * subagents, metacognitive signals, etc.) on top.
+ *
+ * Skills, AGENTS.md, and project conventions live in the system prompt
+ * (see `system-prompt:build` in agent-loop) so they enter the provider's
+ * prefix cache instead of being rebuilt and re-sent every turn.
+ *
+ * Shell context is likewise not injected here — it flows into the
+ * conversation as incremental <shell-events> messages (see
+ * AgentLoop.injectShellDelta) for the same reason.
+ */
+export declare function buildDynamicContext(contextManager: ContextManager, tokenStatus: TokenStatus): string;