@livx.cc/agentx 0.99.123 → 0.99.125

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { c as AgentOptions, H as Hooks, w as RunResult, j as Decider, b as Agent, p as PermissionPolicy, G as Gender, L as LineKind, d as ChannelMode, x as SecondChannelOptions, S as SecondChannel } from './secondChannel-DES_VIeN.js';
-export { A as ADVISE_LIMIT, a as AdvisorSetup, C as CC_WRITE_TOOLS, e as ChatFragment, f as ChatUsage, g as Classification, h as Classifier, i as CompactResult, D as DEFAULT_MUTATING, k as Decision, M as ModelRouter, l as ModelRouterOptions, P as PLANNER_BLOCKED, m as PLANNER_REFUSAL, n as PLAN_FIRST, o as PermissionOptions, q as PermissionRule, r as PreToolUseDecision, R as ReasoningEffort, s as RecordingHooks, t as RecordingLifecycle, u as RouteDecision, v as RouterState, T as Tier, y as ToolUse, z as ToolUseMeta, W as WRITE_TOOLS, B as advisorFor, E as advisorPrompt, F as ccModeOptions, I as claudeCodeDisallowedTools, J as composeHooks, K as delegatePrompt, N as delegateTools, O as delegateWorkerFor, Q as estimateTokens, U as jevAvailable, V as jevClassifier, X as makeAdvisor, Y as meterWorkers, Z as pickTier, _ as planMode, $ as plannerBlocks, a0 as reasoningToChatFragment } from './secondChannel-DES_VIeN.js';
+import { c as AgentOptions, H as Hooks, x as RunResult, k as Decider, b as Agent, q as PermissionPolicy, G as Gender, L as LineKind, d as ChannelMode, y as SecondChannelOptions, S as SecondChannel } from './secondChannel-GFT69ax4.js';
+export { A as ADVISE_LIMIT, a as AdvisorSetup, C as CC_WRITE_TOOLS, e as ChatFragment, f as ChatUsage, g as Classification, h as Classifier, i as CompactResult, j as ContextFileSpec, D as DEFAULT_MUTATING, l as Decision, M as ModelRouter, m as ModelRouterOptions, P as PLANNER_BLOCKED, n as PLANNER_REFUSAL, o as PLAN_FIRST, p as PermissionOptions, r as PermissionRule, s as PreToolUseDecision, R as ReasoningEffort, t as RecordingHooks, u as RecordingLifecycle, v as RouteDecision, w as RouterState, T as Tier, z as ToolUse, B as ToolUseMeta, W as WRITE_TOOLS, E as advisorFor, F as advisorPrompt, I as ccModeOptions, J as claudeCodeDisallowedTools, K as composeHooks, N as delegatePrompt, O as delegateTools, Q as delegateWorkerFor, U as estimateTokens, V as jevAvailable, X as jevClassifier, Y as loadContextFiles, Z as loadInstructions, _ as makeAdvisor, $ as meterWorkers, a0 as pickTier, a1 as planMode, a2 as plannerBlocks, a3 as reasoningToChatFragment } from './secondChannel-GFT69ax4.js';
 export { MODEL_ALIASES, ModelSwitch, ResolveModelSwitchOpts, latestClaude, modelShortLabel, resolveModelAlias, resolveModelSwitch } from './models.js';
 import { IFilesystem, FileMetadata } from '@livx.cc/wcli/core';
 export { CommandExecutor, FileMetadata, IFilesystem, IndexedDbFilesystem, MemFilesystem, registerHeadlessCommands } from '@livx.cc/wcli/core';
@@ -175,6 +175,8 @@ declare class JailOptions {
     deny: string[];
     /** Globs readable but not writable/deletable (the pinned constitution). */
     readonly: string[];
+    /** Appended to readonly-violation errors (e.g. "edit it via the kb tool instead"). */
+    readonlyHint?: string;
     /** If set, only paths matching these globs are accessible at all. */
     confineTo?: string[];
     /** Audit hook fired on every blocked operation (drives the circuit breaker). */
@@ -753,8 +755,12 @@ declare function expandCommand(fs: IFilesystem, cmd: CommandInfo, args: string):
 /** Scan `dir`(s) for `<dir>/<name>.md` command templates (first dir wins on duplicate names). */
 declare function scanCommands(fs: IFilesystem, dir: string | string[]): Promise<CommandInfo[]>;
 declare function loadCommands(fs: IFilesystem, dir: string | string[], opts?: {
+    /** @deprecated no-op — the catalog is full + task-independent (stable prompt prefix). */
     relevanceHint?: string;
+    /** @deprecated no-op — use `budgetBytes`. */
     max?: number;
+    /** Catalog byte budget (default 6000); over it descriptions trim, names never drop. */
+    budgetBytes?: number;
     sibling?: SiblingResolver;
 }): Promise<{
     commands: CommandInfo[];
@@ -779,8 +785,12 @@ interface SkillInfo {
 /** Scan `dir`(s) for `<dir>/<id>/SKILL.md` entries (first dir wins on duplicate ids). */
 declare function scanSkills(fs: IFilesystem, dir: string | string[]): Promise<SkillInfo[]>;
 declare function loadSkills(fs: IFilesystem, dir: string | string[], opts?: {
+    /** @deprecated no-op — the catalog is full + task-independent (stable prompt prefix). */
     relevanceHint?: string;
+    /** @deprecated no-op — use `budgetBytes`. */
     max?: number;
+    /** Catalog byte budget (default 6000); over it descriptions trim, names never drop. */
+    budgetBytes?: number;
     sibling?: SiblingResolver;
 }): Promise<{
     skills: SkillInfo[];
@@ -827,8 +837,12 @@ declare const VOICE_MEMORY_PROMPT: string;
  * memory mechanism therefore works in node, a browser tab, or on edge.
  */
 interface LoadMemoryOpts {
+    /** @deprecated no-op — the index is full + task-independent (stable prompt prefix). */
     relevanceHint?: string;
+    /** @deprecated no-op — use `budgetBytes`. */
     max?: number;
+    /** Index byte budget (default 6000); over it hooks trim, slugs never drop. */
+    budgetBytes?: number;
     /** Max Remember calls per session (default 25). Prevents runaway memory writes. */
     maxWritesPerSession?: number;
     /** Called after each successful memory write (auditing, UI indicators). */
@@ -901,14 +915,30 @@ interface ReflectOptions {
 }
 declare function reflectOnRun(o: ReflectOptions): Promise<string | null>;
 
+/** One catalog row: a loadable thing (skill, command, memory) the model can pull by name. */
+interface CatalogEntry {
+    name: string;
+    description?: string;
+    path?: string;
+}
+interface CatalogOptions {
+    /** Heading line (e.g. `## Skills …`). */
+    title: string;
+    /** Closing line (how to load an entry). */
+    footer?: string;
+    /** Max UTF-8 bytes for the whole block (default 6000). Names are never dropped, so a huge set may exceed it. */
+    budgetBytes?: number;
+    /** Prefix shown before each name (e.g. `/` for commands). */
+    namePrefix?: string;
+}
+declare const DEFAULT_CATALOG_BUDGET = 6000;
 /**
- * Walk the VFS directory tree from `/` down, collecting instruction files
- * (AGENT.md, AGENTS.md, CLAUDE.md, .claude/<name>) at each level.
- * Merges all found files general-first → specific-last (mirrors Claude Code's
- * hierarchical CLAUDE.md discovery). First matching filename per directory wins
- * (no duplicates from the same level). Edge-portable: works over any IFilesystem.
+ * Render a full, stable catalog: every entry as `- **name** — desc (\`path\`)`.
+ * Over `budgetBytes`, descriptions are trimmed evenly (one shared max length), then — if even
+ * empty descriptions don't fit — names only. Never drops a name; output depends only on the
+ * entries (no task hint), so the prompt prefix stays byte-identical across turns/tasks.
  */
-declare function loadInstructions(fs: IFilesystem, names?: string[]): Promise<string>;
+declare function formatCatalog(entries: CatalogEntry[], opts: CatalogOptions): string;
 
 type OverlapVerdict = 'keep' | 'cut';
 
@@ -1852,4 +1882,4 @@ declare function exitWorktree(): {
     reason?: string;
 } | null;
 
-export { Agent, type AgentDef, AgentOptions, AgentTool, type AskOptions, type Attempt, BodDbFilesystem, type CallMetric, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, DEFAULT_MAX_DEPTH, DEFAULT_SKIP_DIRS, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, type FileScanOptions, type FillKind, type GateDrop, type GateTurn, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, type LoadMemoryOpts, MEMORY_PROMPT, type MainEvent, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, PROGRESS_TEMPLATES, PermissionPolicy, Progress, ProgressOptions, type ReflectOptions, RunResult, SCRATCH_DIR, type ScheduledJob, type ScheduledJobSnapshot, Scheduler, type SchedulerOptions, Scratch, type ScratchOptions, ScriptedHostBridge, type SiblingResolver, type SkillInfo, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, type Trigger, type TriggerCron, type TriggerInterval, type TriggerOneOff, TurnGate, TurnGateOptions, UserQuestion, VOICE_MEMORY_PROMPT, VOICE_SYSTEM_PROMPT, VoiceCall, VoiceCallOptions, type WebFetchOptions, type WebSearchOptions, type WorkerTier, type WorktreeInfo, type WorktreeSession, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, cleanupWorktree, compileSynthesizedTool, cronMatches, decodeDdgUrl, diskAgentOptions, endsMidPhrase, enterWorktree, exitWorktree, expandCommand, expandEntry, expandTemplate, findGitRoot, forComponent, forgetFact, fullAgentOptions, getOrCreateWorktree, getWorktreeSession, globTool, grepTool, htmlToText, idfWeights, isClosing, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeAskTool, makeGlobTool, makeGrepTool, makeScheduleTools, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchAnthropicTool, makeWebSearchTool, mkdirp, multiEditTool, nextCronAfter, parseCron, parseDdgHtml, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, rollbackTool, sandboxAgentOptions, scanCommands, scanSkills, slugify, tokenize, toolCall, topByRelevance, validateToolCode, validateWorktreeSlug, webFetchTool, webSearchAnthropicTool, webSearchTool, worktreeBranchName, writeFact, writeTool };
+export { Agent, type AgentDef, AgentOptions, AgentTool, type AskOptions, type Attempt, BodDbFilesystem, type CallMetric, type CatalogEntry, type CatalogOptions, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_CATALOG_BUDGET, DEFAULT_DENY, DEFAULT_MAX_DEPTH, DEFAULT_SKIP_DIRS, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, type FileScanOptions, type FillKind, type GateDrop, type GateTurn, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, type LoadMemoryOpts, MEMORY_PROMPT, type MainEvent, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, PROGRESS_TEMPLATES, PermissionPolicy, Progress, ProgressOptions, type ReflectOptions, RunResult, SCRATCH_DIR, type ScheduledJob, type ScheduledJobSnapshot, Scheduler, type SchedulerOptions, Scratch, type ScratchOptions, ScriptedHostBridge, type SiblingResolver, type SkillInfo, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, type Trigger, type TriggerCron, type TriggerInterval, type TriggerOneOff, TurnGate, TurnGateOptions, UserQuestion, VOICE_MEMORY_PROMPT, VOICE_SYSTEM_PROMPT, VoiceCall, VoiceCallOptions, type WebFetchOptions, type WebSearchOptions, type WorkerTier, type WorktreeInfo, type WorktreeSession, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, cleanupWorktree, compileSynthesizedTool, cronMatches, decodeDdgUrl, diskAgentOptions, endsMidPhrase, enterWorktree, exitWorktree, expandCommand, expandEntry, expandTemplate, findGitRoot, forComponent, forgetFact, formatCatalog, fullAgentOptions, getOrCreateWorktree, getWorktreeSession, globTool, grepTool, htmlToText, idfWeights, isClosing, lessonCapture, loadAgents, loadCommands, loadMemory, loadSkills, makeAskTool, makeGlobTool, makeGrepTool, makeScheduleTools, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchAnthropicTool, makeWebSearchTool, mkdirp, multiEditTool, nextCronAfter, parseCron, parseDdgHtml, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, rollbackTool, sandboxAgentOptions, scanCommands, scanSkills, slugify, tokenize, toolCall, topByRelevance, validateToolCode, validateWorktreeSlug, webFetchTool, webSearchAnthropicTool, webSearchTool, worktreeBranchName, writeFact, writeTool };

package/dist/index.js

@@ -120,13 +120,13 @@ function elideImageParts(content, hit, stub) {
 }
 function mintImageRef(path, mime) {
   const token = randomBytes(16).toString("hex");
-  let bytes = 0;
+  let bytes2 = 0;
   try {
-    bytes = Math.ceil(statSync2(path).size * 4 / 3);
+    bytes2 = Math.ceil(statSync2(path).size * 4 / 3);
   } catch (e) {
     log3.warn(`image ref stat failed, weighing as 0: ${path}`, e);
   }
-  refRegistry.set(token, { mime, path, bytes });
+  refRegistry.set(token, { mime, path, bytes: bytes2 });
   while (refRegistry.size > REF_REGISTRY_MAX) refRegistry.delete(refRegistry.keys().next().value);
   return `${IMAGE_REF_SCHEME}${mime};${token};${path}`;
 }
@@ -1634,14 +1634,14 @@ var init_tools = __esm({
             if (!await ctx.fs.exists(path)) return `Error: File not found: ${path}`;
             return imageRefResult(real, IMG_MIME[ext]);
           }
-          const bytes = await fs.readFileBytes(path);
-          const b64 = Buffer.from(bytes).toString("base64");
+          const bytes2 = await fs.readFileBytes(path);
+          const b64 = Buffer.from(bytes2).toString("base64");
           return JSON.stringify({ dataUrl: `data:${IMG_MIME[ext]};base64,${b64}`, image: path });
         }
         const raw = await ctx.fs.readFile(path);
         if (isBinary(raw)) {
-          const bytes = await byteSize(ctx.fs, path, raw);
-          return `[binary file: ${path} \u2014 ${bytes} bytes, not shown as text. Read renders png/jpg/jpeg/gif/webp images directly; otherwise attach it as @${path}.]`;
+          const bytes2 = await byteSize(ctx.fs, path, raw);
+          return `[binary file: ${path} \u2014 ${bytes2} bytes, not shown as text. Read renders png/jpg/jpeg/gif/webp images directly; otherwise attach it as @${path}.]`;
         }
         ctx.readState.set(ctx.fs.resolvePath(path), raw);
         if (raw === "") return `[empty file: ${path} \u2014 0 bytes]`;
@@ -1972,8 +1972,8 @@ var init_tools_jobs = __esm({
         return [...this.jobs.values()].map((j) => this.info(j));
       }
       info(j) {
-        const { id, kind, label, status, startedAt, lastActivityAt, endedAt, reason, bytes, holds, result } = j;
-        return { id, kind, label, status, startedAt, lastActivityAt, endedAt, reason, bytes, holds, result };
+        const { id, kind, label, status, startedAt, lastActivityAt, endedAt, reason, bytes: bytes2, holds, result } = j;
+        return { id, kind, label, status, startedAt, lastActivityAt, endedAt, reason, bytes: bytes2, holds, result };
       }
       /** Wait (bounded) for a job to settle. Resolves the job's info either way; null for an unknown id. */
       async wait(id, timeoutMs) {
@@ -2407,7 +2407,8 @@ var init_JailedFilesystem = __esm({
       violate(op, abs, rule) {
         this.note(op, abs, rule);
         if (rule === "deny" || rule === "confine") throw new Error(`File not found: ${abs}`);
-        throw new Error(`Blocked by filesystem jail (${rule}): ${abs}`);
+        const hint = rule === "readonly" && this.options.readonlyHint ? ` \u2014 ${this.options.readonlyHint}` : "";
+        throw new Error(`Blocked by filesystem jail (${rule}): ${abs}${hint}`);
       }
       /** Fire the audit hook without throwing (for boolean probes that must still return false). */
       note(op, abs, rule) {
@@ -2532,6 +2533,8 @@ var init_JailedFilesystem = __esm({
       deny = [...DEFAULT_DENY];
       /** Globs readable but not writable/deletable (the pinned constitution). */
       readonly = [];
+      /** Appended to readonly-violation errors (e.g. "edit it via the kb tool instead"). */
+      readonlyHint;
       /** If set, only paths matching these globs are accessible at all. */
       confineTo;
       /** Audit hook fired on every blocked operation (drives the circuit breaker). */
@@ -3287,69 +3290,39 @@ ${prompt} [y/N] `);
   }
 };
 
-// src/relevance.ts
-var STOP = /* @__PURE__ */ new Set([
-  "the",
-  "and",
-  "for",
-  "with",
-  "that",
-  "this",
-  "from",
-  "into",
-  "your",
-  "you",
-  "are",
-  "was",
-  "will",
-  "use",
-  "using",
-  "run",
-  "add",
-  "fix",
-  "make",
-  "file",
-  "files",
-  "code",
-  "please",
-  "need",
-  "want",
-  "should",
-  "all"
-]);
-function tokenize(s) {
-  const out = /* @__PURE__ */ new Set();
-  for (const w of String(s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? []) {
-    if (w.length >= 3 && !STOP.has(w)) out.add(w);
-  }
-  return out;
-}
-function idfWeights(corpus) {
-  const N = corpus.length;
-  if (N === 0) return /* @__PURE__ */ new Map();
-  const df = /* @__PURE__ */ new Map();
-  for (const doc of corpus) for (const t of tokenize(doc)) df.set(t, (df.get(t) ?? 0) + 1);
-  const idf = /* @__PURE__ */ new Map();
-  for (const [t, n] of df) idf.set(t, Math.log((N + 1) / (n + 1)) + 1);
-  return idf;
-}
-function relevanceScore(text, queryTokens, idf) {
-  if (queryTokens.size === 0) return 0;
-  const t = tokenize(text);
-  let score = 0;
-  for (const q of queryTokens) if (t.has(q)) score += idf?.get(q) ?? 1;
-  return score;
-}
-function topByRelevance(items, query, text, k, corpus) {
-  if (!Number.isInteger(k) || k < 1) return { kept: items, rest: [] };
-  if (items.length <= k || !query.trim()) return { kept: items, rest: [] };
-  const q = tokenize(query);
-  if (q.size === 0) return { kept: items.slice(0, k), rest: items.slice(k) };
-  const idf = corpus?.length ? idfWeights(corpus) : void 0;
-  const scored = items.map((x, i) => ({ i, s: relevanceScore(text(x), q, idf) }));
-  scored.sort((a, b) => b.s - a.s || a.i - b.i);
-  const keep = new Set(scored.slice(0, k).map((e) => e.i));
-  return { kept: items.filter((_, i) => keep.has(i)), rest: items.filter((_, i) => !keep.has(i)) };
+// src/catalog.ts
+var DEFAULT_CATALOG_BUDGET = 6e3;
+var enc = new TextEncoder();
+var bytes = (s) => enc.encode(s).length;
+function clip(s, n) {
+  const cps = [...s];
+  if (cps.length <= n) return s;
+  return n <= 1 ? "\u2026" : cps.slice(0, n - 1).join("").trimEnd() + "\u2026";
+}
+function formatCatalog(entries, opts) {
+  const budget = opts.budgetBytes ?? DEFAULT_CATALOG_BUDGET;
+  const pre = opts.namePrefix ?? "";
+  const wrap = (body) => [opts.title, body, opts.footer].filter((x) => x !== void 0 && x !== "").join("\n");
+  const render = (max) => wrap(entries.map((e) => {
+    const d = (e.description ?? "").replace(/\s+/g, " ").trim();
+    const desc = d && max > 0 ? ` \u2014 ${clip(d, max)}` : "";
+    return `- **${pre}${e.name}**${desc}${e.path ? ` (\`${e.path}\`)` : ""}`;
+  }).join("\n"));
+  const longest = Math.max(0, ...entries.map((e) => [...e.description ?? ""].length));
+  const full = render(longest);
+  if (bytes(full) <= budget) return full;
+  if (bytes(render(0)) <= budget) {
+    let lo = 0, hi = longest;
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (bytes(render(mid)) <= budget) lo = mid;
+      else hi = mid - 1;
+    }
+    return render(lo);
+  }
+  const names = wrap(entries.map((e) => `- **${pre}${e.name}**`).join("\n"));
+  if (bytes(names) <= budget) return names;
+  return wrap(`- ${entries.map((e) => pre + e.name).join(", ")}`);
 }
 
 // src/frontmatter.ts
@@ -3371,7 +3344,6 @@ function grabField(block, key) {
 }
 
 // src/commands.ts
-var MAX_CATALOG = 25;
 function parseFrontmatter(md) {
   const { block, body } = splitFrontmatter(md);
   return { description: grabField(block, "description"), body };
@@ -3428,9 +3400,12 @@ async function scanCommands(fs, dir) {
 async function loadCommands(fs, dir, opts = {}) {
   const commands = await scanCommands(fs, dir);
   if (commands.length === 0) return { commands, catalog: "" };
-  const { kept, rest } = topByRelevance(commands, opts.relevanceHint ?? "", (c) => `${c.name} ${c.description}`, opts.max ?? MAX_CATALOG);
-  const catalog = "## Slash commands (reusable prompt templates)\n" + kept.map((c) => `- **/${c.name}** \u2014 ${c.description} (\`${c.path}\`)`).join("\n") + (rest.length ? `
-- (${rest.length} more, names only \u2014 call \`SlashCommand\` to run): ${rest.map((c) => c.name).join(", ")}` : "") + "\nTo run one, call the `SlashCommand` tool with its name (and optional `args`); it returns the expanded template to act on.";
+  const catalog = formatCatalog(commands, {
+    title: "## Slash commands (reusable prompt templates)",
+    footer: "To run one, call the `SlashCommand` tool with its name (and optional `args`); it returns the expanded template to act on.",
+    namePrefix: "/",
+    budgetBytes: opts.budgetBytes
+  });
   const tool = {
     name: "SlashCommand",
     description: "Run a slash command (or skill) by name \u2014 returns its expanded prompt template/instructions (with your `args` substituted/appended). Resolves both the command and skill namespaces. Use when a task matches a listed command or skill.",
@@ -3458,7 +3433,6 @@ async function loadCommands(fs, dir, opts = {}) {
 }
 
 // src/skills.ts
-var MAX_CATALOG2 = 25;
 function parseFrontmatter2(md) {
   const { block } = splitFrontmatter(md);
   const b = block || md.slice(0, 600);
@@ -3484,9 +3458,11 @@ async function scanSkills(fs, dir) {
 async function loadSkills(fs, dir, opts = {}) {
   const skills = await scanSkills(fs, dir);
   if (skills.length === 0) return { skills, catalog: "" };
-  const { kept, rest } = topByRelevance(skills, opts.relevanceHint ?? "", (s) => `${s.name} ${s.description}`, opts.max ?? MAX_CATALOG2);
-  const catalog = "## Skills (load one before acting on a matching task)\n" + kept.map((s) => `- **${s.name}** \u2014 ${s.description} (\`${s.path}\`)`).join("\n") + (rest.length ? `
-- (${rest.length} more, names only \u2014 call \`Skill\` to load): ${rest.map((s) => s.name).join(", ")}` : "") + "\nWhen a task matches a skill, call the `Skill` tool with its name to load its full instructions.";
+  const catalog = formatCatalog(skills, {
+    title: "## Skills (load one before acting on a matching task)",
+    footer: "When a task matches a skill, call the `Skill` tool with its name to load its full instructions.",
+    budgetBytes: opts.budgetBytes
+  });
   const tool = {
     name: "Skill",
     description: "Load a skill (or slash command) by name \u2014 returns its full instructions (SKILL.md / expanded template), with any `args` substituted/appended. Resolves both the skill and command namespaces. Use when a task matches a listed skill or command.",
@@ -3511,7 +3487,73 @@ async function loadSkills(fs, dir, opts = {}) {
 
 // src/memory.ts
 init_tools_structured();
-var MAX_INDEX = 25;
+
+// src/relevance.ts
+var STOP = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "into",
+  "your",
+  "you",
+  "are",
+  "was",
+  "will",
+  "use",
+  "using",
+  "run",
+  "add",
+  "fix",
+  "make",
+  "file",
+  "files",
+  "code",
+  "please",
+  "need",
+  "want",
+  "should",
+  "all"
+]);
+function tokenize(s) {
+  const out = /* @__PURE__ */ new Set();
+  for (const w of String(s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? []) {
+    if (w.length >= 3 && !STOP.has(w)) out.add(w);
+  }
+  return out;
+}
+function idfWeights(corpus) {
+  const N = corpus.length;
+  if (N === 0) return /* @__PURE__ */ new Map();
+  const df = /* @__PURE__ */ new Map();
+  for (const doc of corpus) for (const t of tokenize(doc)) df.set(t, (df.get(t) ?? 0) + 1);
+  const idf = /* @__PURE__ */ new Map();
+  for (const [t, n] of df) idf.set(t, Math.log((N + 1) / (n + 1)) + 1);
+  return idf;
+}
+function relevanceScore(text, queryTokens, idf) {
+  if (queryTokens.size === 0) return 0;
+  const t = tokenize(text);
+  let score = 0;
+  for (const q of queryTokens) if (t.has(q)) score += idf?.get(q) ?? 1;
+  return score;
+}
+function topByRelevance(items, query, text, k, corpus) {
+  if (!Number.isInteger(k) || k < 1) return { kept: items, rest: [] };
+  if (items.length <= k || !query.trim()) return { kept: items, rest: [] };
+  const q = tokenize(query);
+  if (q.size === 0) return { kept: items.slice(0, k), rest: items.slice(k) };
+  const idf = corpus?.length ? idfWeights(corpus) : void 0;
+  const scored = items.map((x, i) => ({ i, s: relevanceScore(text(x), q, idf) }));
+  scored.sort((a, b) => b.s - a.s || a.i - b.i);
+  const keep = new Set(scored.slice(0, k).map((e) => e.i));
+  return { kept: items.filter((_, i) => keep.has(i)), rest: items.filter((_, i) => !keep.has(i)) };
+}
+
+// src/memory.ts
 var MAX_INDEX_LINES = 200;
 var MAX_INDEX_BYTES = 25e3;
 var MEMORY_PROMPT = '## Memory guidelines\n**When to Remember:** user corrections ("no, do X instead"), preferences ("I prefer Y"), project constraints, recurring gotchas, role/context ("I\'m a data scientist"), workflow patterns confirmed by the user. Capture the WHY, not just the what.\n**When NOT to Remember:** task-specific scratch, transient state, things derivable from code/git, conversation filler, anything already in instruction files. If removing the memory wouldn\'t change future behavior, don\'t save it.\n**Types** (pass to Remember \u2014 this determines where the memory is stored):\n- `user` \u2014 role, preferences, knowledge level, collaboration style (GLOBAL \u2014 follows you across projects)\n- `feedback` \u2014 corrections, what to avoid/repeat, with WHY (GLOBAL)\n- `project` \u2014 ongoing work, goals, constraints, deadlines (LOCAL to this project; convert relative dates to absolute)\n- `reference` \u2014 pointers to external resources, URLs, vendor docs (LOCAL to this project)\n**Before acting on a recalled memory:** verify it\'s still true \u2014 a memory naming a file/function/flag is a claim from when it was written. Grep/read to confirm before recommending. Stale memory \u2192 update via Remember (same slug overwrites).\n**Forget:** when the user asks to remove/delete/forget a memory, call `Forget` with its slug \u2014 it deletes the fact and its index line. Never "remove" by re-Remembering a note that says it was removed: that keeps the memory.\n**Dedup:** before writing, check if a similar memory exists (Recall or MemorySearch). Update the existing one rather than creating duplicates.\nCall `Recall` with a slug (or multiple slugs/a pattern) to load full bodies when relevant.\nCall `MemorySearch` with a query to find memories by content when you don\'t know the slug.\nCall `Remember` to persist a durable fact for future sessions.';
@@ -3546,10 +3588,18 @@ async function loadMemory(fs, dir, opts = {}) {
     }
   }
   if (!hasContent) return { index: MEMORY_PROMPT, tools };
-  const { kept, rest } = topByRelevance(allPointers, opts.relevanceHint ?? "", (l) => l, opts.max ?? MAX_INDEX);
-  const restSlugs = rest.map((l) => l.match(/\]\(([^)]+)\.md\)/)?.[1] ?? l.match(/\[([^\]]+)\]/)?.[1] ?? "").filter(Boolean);
-  const index = MEMORY_PROMPT + "\n\n## Memory index (persistent context \u2014 recalled across sessions)\n" + (header ? header + "\n" : "") + kept.join("\n") + (restSlugs.length ? `
-- (${restSlugs.length} more learnings, slugs only \u2014 call \`Recall\` if relevant): ${restSlugs.join(", ")}` : "");
+  const entries = allPointers.map((l) => {
+    const m = l.match(/\]\(([^)]+)\.md\)/);
+    const slug2 = m?.[1] ?? l;
+    const title = m ? l.slice(l.indexOf("[") + 1, m.index).trim() : "";
+    const hook = m ? l.slice(m.index + m[0].length).replace(/^\s*(?:[—:-]\s*)?/, "").trim() : "";
+    return { name: slug2, description: title && title !== slug2 ? hook ? `${title} \u2014 ${hook}` : title : hook };
+  });
+  const index = MEMORY_PROMPT + "\n\n" + formatCatalog(entries, {
+    title: "## Memory index (persistent context \u2014 recalled across sessions)" + (header ? "\n" + header : ""),
+    footer: "Call `Recall` with a slug to load its full fact.",
+    budgetBytes: opts.budgetBytes
+  });
   return { index, tools };
 }
 var TERM_STOPWORDS = new Set(`the and for but not you your yours our ours his her hers its their they them this that these those
@@ -3823,6 +3873,25 @@ ${sections.join("\n\n---\n\n")}`;
   }
   return "";
 }
+async function loadContextFiles(fs, specs = []) {
+  const sections = [];
+  for (const { path, maxChars, label } of specs) {
+    if (!await fs.exists(path)) continue;
+    let md = (await fs.readFile(path)).trim();
+    if (!md) continue;
+    if (maxChars !== void 0) {
+      const cps = [...md], n = Math.max(0, maxChars);
+      if (cps.length > n) md = `${cps.slice(0, n).join("").trimEnd()}
+\u2026 (truncated \u2014 full file: ${path})`;
+    }
+    sections.push(`<!-- ${path} -->
+${label ? `### ${label}
+` : ""}${md}`);
+  }
+  return sections.length ? `## Context files
+
+${sections.join("\n\n---\n\n")}` : "";
+}
 
 // src/subagent.ts
 init_tools();
@@ -4862,6 +4931,8 @@ var AgentOptions = class {
    *  Walks the VFS tree and merges all found files (general → specific, like Claude Code).
    *  `true` (default) = auto-discover standard names. `string[]` = custom names. `false` = skip. */
   instructionFiles = true;
+  /** Extra files injected right after the instructions (missing → skipped; over `maxChars` → head + pointer to the full file). */
+  contextFiles;
   /** Host interaction channel (human-in-the-loop). If set: adds the `AskUserQuestion` tool. */
   host;
   /** Add the `AskUserQuestion` tool when a host is present (default true). Set false for an agent that
@@ -5190,7 +5261,7 @@ var Agent = class _Agent {
    * across turns (and the frozen prompt pairs well with prompt caching). Does NOT touch
    * the transcript; `run`/`send` own that.
    */
-  async prepare(taskHint) {
+  async prepare() {
     if (this.prepared) return this.systemPromptCache;
     const o = this.options;
     const fs = o.fs;
@@ -5208,8 +5279,12 @@ var Agent = class _Agent {
       const ins = await loadInstructions(fs, names);
       if (ins) systemPrompt += "\n\n" + ins;
     }
+    if (o.contextFiles?.length) {
+      const ctxFiles = await loadContextFiles(fs, o.contextFiles);
+      if (ctxFiles) systemPrompt += "\n\n" + ctxFiles;
+    }
     if (o.memoryDir) {
-      const { index, tools: memTools } = await loadMemory(fs, o.memoryDir, { relevanceHint: taskHint, userDir: o.memoryUserDir });
+      const { index, tools: memTools } = await loadMemory(fs, o.memoryDir, { userDir: o.memoryUserDir });
       if (index) systemPrompt += "\n\n" + index;
       tools = [...tools, ...memTools];
     }
@@ -5219,7 +5294,7 @@ var Agent = class _Agent {
         const c = (await scanCommands(fs, commandsDir)).find((x) => x.name === name);
         return c ? { path: c.path, stripFrontmatter: true } : void 0;
       } : void 0;
-      const { catalog, tool } = await loadSkills(fs, skillsDir, { relevanceHint: taskHint, sibling });
+      const { catalog, tool } = await loadSkills(fs, skillsDir, { sibling });
       if (catalog) systemPrompt += "\n\n" + catalog;
       if (tool) tools = [...tools, tool];
     }
@@ -5228,7 +5303,7 @@ var Agent = class _Agent {
         const s = (await scanSkills(fs, skillsDir)).find((x) => x.name === name);
         return s ? { path: s.path, stripFrontmatter: false } : void 0;
       } : void 0;
-      const { catalog, tool } = await loadCommands(fs, commandsDir, { relevanceHint: taskHint, sibling });
+      const { catalog, tool } = await loadCommands(fs, commandsDir, { sibling });
       if (catalog) systemPrompt += "\n\n" + catalog;
       if (tool) tools = [...tools, tool];
     }
@@ -5287,7 +5362,7 @@ var Agent = class _Agent {
     this.invokedTools.clear();
     this.fabricatedClaims.clear();
     this.lastTask = contentText(task);
-    const systemPrompt = await this.prepare(contentText(task));
+    const systemPrompt = await this.prepare();
     const startCtx = await this.fireSessionStart();
     const userContent = await this.applyPromptSubmit(task);
     this.transcript = [
@@ -5323,7 +5398,7 @@ var Agent = class _Agent {
   async send(task) {
     await this.ensureFs();
     this.lastTask = contentText(task);
-    const systemPrompt = await this.prepare(contentText(task));
+    const systemPrompt = await this.prepare();
     const startCtx = await this.fireSessionStart();
     const userContent = await this.applyPromptSubmit(task);
     const sys = systemPrompt + (startCtx ? "\n\n" + startCtx : "");
@@ -6147,9 +6222,9 @@ function capOversizedBodies(messages, target, keepRecentImages = 1) {
   return out;
 }
 function elideBody(x, cap) {
-  const note = (bytes, imgs2) => `
+  const note = (bytes2, imgs2) => `
 
-[${bytes} bytes elided by /compact${x.role === "tool" ? " \u2014 re-run the tool to view" : ""}${imgs2 ? `; ${imgs2} image part(s) KEPT in full \u2014 they still cost context` : ""}]`;
+[${bytes2} bytes elided by /compact${x.role === "tool" ? " \u2014 re-run the tool to view" : ""}${imgs2 ? `; ${imgs2} image part(s) KEPT in full \u2014 they still cost context` : ""}]`;
   if (!Array.isArray(x.content)) {
     const text = contentText(x.content);
     if (text.length <= cap) return x;
@@ -12085,11 +12160,11 @@ Another agent just implemented the above. Independently check the CURRENT state
         const list = id ? [this.tasks.get(String(id))].filter(Boolean) : [...this.tasks.values()];
         if (!list.length) return id ? `No task '${id}'.` : "No background tasks.";
         const cap = id ? 1500 : 300;
-        const clip = (x) => x.length > cap ? `${x.slice(0, cap)}\u2026 (truncated)` : x;
+        const clip2 = (x) => x.length > cap ? `${x.slice(0, cap)}\u2026 (truncated)` : x;
         return list.map((t) => {
           const head = `${t.id} (${t.label}): ${t.status}`;
           const body = (t.status === "done" ? t.spokenText?.trim() || t.result?.trim() : t.status === "error" ? t.result?.trim() : "") ?? "";
-          return body ? `${head}. ${t.status === "error" ? "Error" : "Result"}: ${clip(body)}` : head;
+          return body ? `${head}. ${t.status === "error" ? "Error" : "Result"}: ${clip2(body)}` : head;
         }).join("\n");
       }
     };
@@ -13990,6 +14065,7 @@ export {
   CartesiaTTSOptions,
   CommandExecutor2 as CommandExecutor,
   ConsoleHostBridge,
+  DEFAULT_CATALOG_BUDGET,
   DEFAULT_DENY,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MUTATING,
@@ -14080,6 +14156,7 @@ export {
   findGitRoot,
   forComponent,
   forgetFact,
+  formatCatalog,
   formatJobNotice,
   fullAgentOptions,
   getOrCreateWorktree,
@@ -14098,6 +14175,7 @@ export {
   lessonCapture,
   loadAgents,
   loadCommands,
+  loadContextFiles,
   loadInstructions,
   loadMemory,
   loadSkills,