@wrongstack/core 0.155.0 → 0.236.0

package/dist/types/index.js

@@ -77,7 +77,13 @@ var ERROR_CODES = {
   FS_MKDIR_FAILED: "FS_MKDIR_FAILED",
   FS_DELETE_FAILED: "FS_DELETE_FAILED",
   FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY",
   // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
   UNKNOWN: "UNKNOWN"
 };
 var WrongStackError = class extends Error {
@@ -192,6 +198,20 @@ var SessionError = class extends WrongStackError {
     this.sessionId = opts.sessionId;
   }
 };
+var SddError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "sdd",
+      severity: opts.code === ERROR_CODES.SDD_PARSE_FAILED ? "warning" : "error",
+      recoverable: opts.code === ERROR_CODES.SDD_NOT_READY,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "SddError";
+  }
+};
 var FsError = class extends WrongStackError {
   path;
   constructor(opts) {
@@ -229,6 +249,9 @@ function isAgentError(err) {
 function isFsError(err) {
   return err instanceof FsError;
 }
+function isSddError(err) {
+  return err instanceof SddError;
+}
 
 // src/types/provider.ts
 var ProviderError = class extends WrongStackError {
@@ -419,7 +442,7 @@ async function renameWithRetry(from, to) {
       if (!code || !TRANSIENT_RENAME_CODES.has(code) || i === delays.length) {
         throw err;
       }
-      await new Promise((resolve3) => setTimeout(resolve3, delays[i]));
+      await new Promise((resolve4) => setTimeout(resolve4, delays[i]));
     }
   }
   throw lastErr;
@@ -489,6 +512,26 @@ var KEY_BYTES = 32;
 var IV_BYTES = 12;
 var TAG_BYTES = 16;
 var ALGO = "aes-256-gcm";
+var KEY_FILE_MODE = 384;
+function checkKeyFilePermissions(keyFile) {
+  if (process.platform === "win32") return;
+  try {
+    const stat2 = fs2.statSync(keyFile);
+    const actualMode = stat2.mode & 511;
+    if (actualMode !== KEY_FILE_MODE) {
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "vault.key_file_wrong_permissions",
+        message: `Key file ${keyFile} has mode ${actualMode.toString(8)} \u2014 expected ${KEY_FILE_MODE.toString(8)}. Run: chmod ${KEY_FILE_MODE.toString(8)} ${keyFile}`,
+        keyFile,
+        expectedMode: KEY_FILE_MODE,
+        actualMode,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+    }
+  } catch {
+  }
+}
 var DefaultSecretVault = class {
   keyFile;
   key;
@@ -512,14 +555,26 @@ var DefaultSecretVault = class {
     const rest = value.slice(ENCRYPTED_PREFIX.length);
     const parts = rest.split(":");
     if (parts.length !== 3) {
-      throw new Error("SecretVault: malformed encrypted value");
+      throw new ConfigError({
+        message: "SecretVault: malformed encrypted value",
+        code: ERROR_CODES.CONFIG_PARSE_FAILED,
+        context: { field: "encrypted_value" }
+      });
     }
     const [ivB64, tagB64, ctB64] = parts;
     const iv = Buffer.from(ivB64, "base64");
     const tag = Buffer.from(tagB64, "base64");
     const ct = Buffer.from(ctB64, "base64");
-    if (iv.length !== IV_BYTES) throw new Error("SecretVault: bad IV length");
-    if (tag.length !== TAG_BYTES) throw new Error("SecretVault: bad tag length");
+    if (iv.length !== IV_BYTES) throw new ConfigError({
+      message: "SecretVault: bad IV length",
+      code: ERROR_CODES.CONFIG_PARSE_FAILED,
+      context: { expected: IV_BYTES, actual: iv.length }
+    });
+    if (tag.length !== TAG_BYTES) throw new ConfigError({
+      message: "SecretVault: bad tag length",
+      code: ERROR_CODES.CONFIG_PARSE_FAILED,
+      context: { expected: TAG_BYTES, actual: tag.length }
+    });
     const key = this.loadOrCreateKey();
     const decipher = createDecipheriv(ALGO, key, iv);
     decipher.setAuthTag(tag);
@@ -531,11 +586,14 @@ var DefaultSecretVault = class {
     try {
       const buf = fs2.readFileSync(this.keyFile);
       if (buf.length !== KEY_BYTES) {
-        throw new Error(
-          `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`
-        );
+        throw new ConfigError({
+          message: `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { keyFile: this.keyFile, expectedBytes: KEY_BYTES, actualBytes: buf.length }
+        });
       }
       this.key = buf;
+      checkKeyFilePermissions(this.keyFile);
       return this.key;
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
@@ -548,11 +606,14 @@ var DefaultSecretVault = class {
       if (err.code !== "EEXIST") throw err;
       const buf = fs2.readFileSync(this.keyFile);
       if (buf.length !== KEY_BYTES) {
-        throw new Error(
-          `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`
-        );
+        throw new ConfigError({
+          message: `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { keyFile: this.keyFile, expectedBytes: KEY_BYTES, actualBytes: buf.length }
+        });
       }
       this.key = buf;
+      checkKeyFilePermissions(this.keyFile);
       return this.key;
     }
     this.key = key;
@@ -613,7 +674,7 @@ async function rewriteConfigEncrypted(configPath, vault, patch) {
   await atomicWrite(configPath, JSON.stringify(encrypted, null, 2), { mode: 384 });
   await restrictFilePermissions(configPath);
 }
-async function migratePlaintextSecrets(configPath, vault) {
+async function migratePlaintextSecrets(configPath, vault, logger) {
   let raw;
   try {
     raw = await fs.readFile(configPath, "utf8");
@@ -630,11 +691,14 @@ async function migratePlaintextSecrets(configPath, vault) {
   const migrated = walkCount(parsed, vault, counter);
   if (counter.n === 0) return { migrated: 0, file: configPath };
   await atomicWrite(configPath, JSON.stringify(migrated, null, 2), { mode: 384 });
-  await restrictFilePermissions(configPath);
+  await restrictFilePermissions(
+    configPath,
+    logger ? { warn: (msg) => logger.warn(msg) } : void 0
+  );
   return { migrated: counter.n, file: configPath };
 }
 async function restrictFilePermissions(filePath, opts) {
-  const warn = ((msg) => console.warn(msg));
+  const warn = opts?.warn ?? ((msg) => console.warn(msg));
   if (process.platform === "win32") {
     try {
       const { execFile } = await import('child_process');
@@ -751,18 +815,24 @@ var COLORS = {
   trace: color.dim
 };
 var LOG_LEVELS = /* @__PURE__ */ new Set(["error", "warn", "info", "debug", "trace"]);
+var LOG_FORMATS = /* @__PURE__ */ new Set(["pretty", "json"]);
 var DefaultLogger = class _DefaultLogger {
+  /** How many file writes between rotation size checks (statSync is not free). */
+  static ROTATE_CHECK_EVERY = 100;
   level;
   file;
   bindings;
-  pretty;
+  format;
   stderr;
+  maxFileBytes;
+  writesSinceRotateCheck = 0;
   constructor(opts = {}) {
     this.level = opts.level ?? parseLogLevel(process.env.WRONGSTACK_LOG_LEVEL);
     this.file = opts.file;
     this.bindings = opts.bindings ?? {};
-    this.pretty = opts.pretty ?? true;
+    this.format = opts.format ?? parseLogFormat(process.env.WRONGSTACK_LOG_FORMAT);
     this.stderr = opts.stderr !== false;
+    this.maxFileBytes = opts.maxFileBytes ?? 10 * 1024 * 1024;
     if (this.file) {
       try {
         fs2.mkdirSync(path4.dirname(this.file), { recursive: true });
@@ -789,11 +859,30 @@ var DefaultLogger = class _DefaultLogger {
     return new _DefaultLogger({
       level: this.level,
       file: this.file,
-      pretty: this.pretty,
+      format: this.format,
       stderr: this.stderr,
+      maxFileBytes: this.maxFileBytes,
       bindings: { ...this.bindings, ...bindings }
     });
   }
+  /**
+   * Size-based rotation: when the file outgrows `maxFileBytes`, rename it to
+   * `<file>.1` (dropping the previous `.1`) so the live file restarts empty.
+   * Checked on the first write and every ROTATE_CHECK_EVERY writes after.
+   * Best-effort: a rename can fail on Windows while another process holds
+   * the file — the next check retries. Multiple processes appending to the
+   * same log all run this check; whoever crosses the threshold first wins.
+   */
+  maybeRotate(file) {
+    if (this.writesSinceRotateCheck++ % _DefaultLogger.ROTATE_CHECK_EVERY !== 0) return;
+    try {
+      const st = fs2.statSync(file);
+      if (st.size < this.maxFileBytes) return;
+      fs2.rmSync(`${file}.1`, { force: true });
+      fs2.renameSync(file, `${file}.1`);
+    } catch {
+    }
+  }
   log(level, msg, ctx) {
     const r = LEVEL_RANK[level];
     const allowed = LEVEL_RANK[this.level];
@@ -805,13 +894,17 @@ var DefaultLogger = class _DefaultLogger {
     }
     if (this.file) {
       try {
+        this.maybeRotate(this.file);
         fs2.appendFileSync(this.file, `${JSON.stringify(entry)}
 `);
       } catch {
       }
     }
     if (!this.stderr) return;
-    if (r <= LEVEL_RANK.warn || this.level === "debug" || this.level === "trace") {
+    if (this.format === "json") {
+      writeErr(`${JSON.stringify(entry)}
+`);
+    } else {
       const head = `${color.dim(ts)} ${COLORS[level](level.toUpperCase().padEnd(5))} ${msg}`;
       if (ctx !== void 0) {
         writeErr(`${head} ${formatCtx(ctx)}
@@ -826,6 +919,9 @@ var DefaultLogger = class _DefaultLogger {
 function parseLogLevel(raw) {
   return raw && LOG_LEVELS.has(raw) ? raw : "info";
 }
+function parseLogFormat(raw) {
+  return raw && LOG_FORMATS.has(raw) ? raw : "pretty";
+}
 function formatCtx(ctx) {
   if (ctx instanceof Error) return color.dim(ctx.message);
   if (typeof ctx === "string") return color.dim(ctx);
@@ -835,6 +931,22 @@ function formatCtx(ctx) {
     return color.dim(String(ctx));
   }
 }
+var noOpLogger = {
+  // 'error' is the quietest level the Logger contract offers; the methods
+  // discard everything regardless, this only matters to level checks.
+  level: "error",
+  error: () => {
+  },
+  warn: () => {
+  },
+  info: () => {
+  },
+  debug: () => {
+  },
+  trace: () => {
+  },
+  child: () => noOpLogger
+};
 
 // src/infrastructure/token-counter.ts
 var PRICE_CACHE_MAX_SIZE = 100;
@@ -975,7 +1087,9 @@ var MEMORY_TYPE_LABELS = {
 // src/utils/expect-defined.ts
 function expectDefined(value, label) {
   if (value === null || value === void 0) {
-    throw new Error("Expected value to be defined");
+    const err = new Error("Expected value to be defined");
+    err.name = "ExpectDefinedError";
+    throw err;
   }
   return value;
 }
@@ -1023,22 +1137,31 @@ function estimateToolResultTokens(content) {
 function estimateTextTokens(text) {
   return RoughTokenEstimate(text);
 }
+function computeMessageTokens(msg) {
+  if (typeof msg.content === "string") return estimateTextTokens(msg.content);
+  let total = 0;
+  for (const b of msg.content) {
+    if (b.type === "text") total += estimateTextTokens(b.text);
+    else if (b.type === "tool_use") total += estimateToolInputTokens(b.input);
+    else if (b.type === "tool_result") total += estimateToolResultTokens(b.content);
+    else total += RoughTokenEstimate(JSON.stringify(b));
+  }
+  return total;
+}
 function estimateMessageTokens(messages) {
   let total = 0;
   for (const m of messages) {
-    if (typeof m.content === "string") {
-      total += estimateTextTokens(m.content);
-    } else {
-      for (const b of m.content) {
-        if (b.type === "text") total += estimateTextTokens(b.text);
-        else if (b.type === "tool_use") total += estimateToolInputTokens(b.input);
-        else if (b.type === "tool_result") total += estimateToolResultTokens(b.content);
-      }
+    if (typeof m._estTokens === "number" && m._estTokens > 0) {
+      total += m._estTokens;
+      continue;
     }
+    total += computeMessageTokens(m);
   }
   return total;
 }
 function estimateToolDefTokens(tool) {
+  const cached = tool._estDefTokens;
+  if (typeof cached === "number" && cached > 0) return cached;
   return RoughTokenEstimate(tool.name) + RoughTokenEstimate(tool.description ?? "") + RoughTokenEstimate(JSON.stringify(tool.inputSchema));
 }
 function estimateRequestTokens(messages, systemPrompt, tools, calibrationKey = CALIBRATION_GLOBAL_KEY) {
@@ -1048,6 +1171,11 @@ function estimateRequestTokens(messages, systemPrompt, tools, calibrationKey = C
   } else if (Array.isArray(messages)) {
     for (const m of messages) {
       if (typeof m === "object" && m !== null && "content" in m) {
+        const cached = m._estTokens;
+        if (typeof cached === "number" && cached > 0) {
+          messagesTokens += cached;
+          continue;
+        }
         const content = m.content;
         if (typeof content === "string") {
           messagesTokens += RoughTokenEstimate(content);
@@ -1213,6 +1341,18 @@ function findPreserveStart(messages, preserveK) {
 }
 function eliseOldToolResults(messages, opts) {
   const preserveStart = findPreserveStart(messages, opts.preserveK);
+  let hasOversized = false;
+  for (let i = 0; i < preserveStart && !hasOversized; i++) {
+    const msg = messages[i];
+    if (!msg || !Array.isArray(msg.content)) continue;
+    for (const b of msg.content) {
+      if (b.type === "tool_result" && estimateToolResultTokens(b.content) >= opts.eliseThreshold) {
+        hasOversized = true;
+        break;
+      }
+    }
+  }
+  if (!hasOversized) return { messages, saved: 0, changed: false };
   let saved = 0;
   let changed = false;
   const next = new Array(messages.length);
@@ -2393,6 +2533,77 @@ Remember: your job is to make the user a better developer, not just to complete
     tags: ["teaching", "mentor", "learning"],
     toolPreferences: ["read", "edit", "explain"],
     suggestedSkills: ["prompt-engineering", "skill-creator", "node-modern", "typescript-strict"]
+  },
+  {
+    id: "research-web",
+    name: "Research Web",
+    description: "Current-data research \u2014 search web, verify, inject findings into context",
+    prompt: `## Research Web Mode
+
+You are in research mode. Your role: find, verify, and incorporate
+current web data. Your training data is stale \u2014 every factual claim
+about version numbers, API surfaces, package status, or ecosystem
+changes must be verified against live sources.
+
+### When to research
+- The user asks "is this still the case?", "what's current?", "latest version?"
+- You're about to claim a version number, deprecation, or API change
+- You're comparing tools, packages, or approaches released in the last 12 months
+- You realize your knowledge may be >6 months old on a fast-moving topic
+
+### Research methodology
+1. **Search first, fetch selectively.** Use web_search with 5-8 results for
+   broad queries. Then web_fetch the 1-2 most authoritative results for detail.
+   Don't fetch every result \u2014 you'll burn tokens on noise.
+2. **Cross-reference.** One source is a data point. Two sources that agree
+   is a signal. Three is confirmation. Flag single-source claims as tentative.
+3. **Cite sources.** Every factual claim from web data must include where it
+   came from: domain name, and date if visible on the page.
+4. **Know when to stop.** 2-3 searches + 1-2 fetches is usually sufficient.
+   If you're on your 5th search without a clear answer, pause and tell the user
+   what you've found and what's still unclear \u2014 let them decide to dig deeper.
+5. **Inject findings for reuse.** After gathering current data, use
+   context_manager with add_note to inject a structured "Research Findings"
+   block into the conversation. Future turns see this and don't re-search.
+
+### Self-injection pattern
+When you discover current data mid-research, inject it so subsequent turns
+benefit without re-searching:
+
+web_search("Next.js middleware breaking changes 2025")
+  \u2192 Surfaced: Next.js 15.2 changed middleware runtime from edge to node
+web_fetch("https://nextjs.org/docs/messages/middleware-upgrade-guide")
+  \u2192 Confirmed: middleware now runs on Node.js runtime by default
+context_manager: add_note(
+  "## Research: Next.js middleware
+   - Next.js 15.2: middleware defaults to Node.js runtime (was edge)
+   - Breaking: edge-only APIs (crypto.subtle, WebSocket) no longer available
+   - Migration: use node:* equivalents or set runtime: 'edge' explicitly
+   - Source: nextjs.org/docs/messages/middleware-upgrade-guide"
+)
+
+The add_note persists in conversation \u2014 you won't re-search on the next turn.
+
+### Anti-patterns
+- Don't research things already in the conversation context (including
+  earlier add_note blocks you injected)
+- Don't treat a single web search result as ground truth \u2014 cross-reference
+- Don't inject raw JSON or search result dumps via add_note \u2014 summarize
+- Don't research while the user is waiting for a quick code edit \u2014 toggle
+  research-web mode only during analysis/discussion phases
+- Don't research-loop: 5+ searches on one topic \u2192 stop and ask the user
+
+### Exiting research mode
+When the user no longer needs current-data research, suggest switching back
+to the previous mode. You stay in research mode until explicitly told to
+switch \u2014 but don't force web searches on every turn. The methodology rules
+above already gate when to actually search.
+
+When you're done with research: suggest the user run \`/mode default\` or
+their previous mode.`,
+    tags: ["research", "web", "current-data", "up-to-date"],
+    toolPreferences: ["web_search", "web_fetch", "search", "fetch", "context_manager"],
+    suggestedSkills: ["research-web", "tech-stack", "node-modern", "security-scanner", "react-modern"]
   }
 ];
 
@@ -2563,28 +2774,40 @@ var InMemoryAgentBridge = class {
     return () => this.subscriptions.delete(handler);
   }
   async request(msg, timeoutMs) {
-    if (this.stopped) throw new Error("Bridge is stopped");
+    if (this.stopped) throw new AgentError({
+      message: "Bridge is stopped",
+      code: ERROR_CODES.AGENT_ABORTED
+    });
     const timeout = timeoutMs ?? this.timeoutMs;
     const correlationId = msg.id;
     if (this.inflightGuards.has(correlationId)) {
-      throw new Error(
-        `Bridge request id "${correlationId}" collides with an in-flight request \u2014 caller is reusing message ids`
-      );
+      throw new AgentError({
+        message: `Bridge request id "${correlationId}" collides with an in-flight request \u2014 caller is reusing message ids`,
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        context: { correlationId }
+      });
     }
     this.inflightGuards.add(correlationId);
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const timer = setTimeout(() => {
         this.inflightGuards.delete(correlationId);
         this.pendingRequests.delete(correlationId);
-        reject(new Error(`Request ${correlationId} timed out after ${timeout}ms`));
+        reject(new AgentError({
+          message: `Request ${correlationId} timed out after ${timeout}ms`,
+          code: ERROR_CODES.AGENT_RUN_FAILED,
+          context: { correlationId, timeoutMs: timeout }
+        }));
       }, timeout);
       if (!this.inflightGuards.has(correlationId)) {
         clearTimeout(timer);
-        reject(new Error("Bridge stopped"));
+        reject(new AgentError({
+          message: "Bridge stopped",
+          code: ERROR_CODES.AGENT_ABORTED
+        }));
         return;
       }
       this.pendingRequests.set(correlationId, {
-        resolve: resolve3,
+        resolve: resolve4,
         reject,
         timer
       });
@@ -2601,7 +2824,10 @@ var InMemoryAgentBridge = class {
     this.stopped = true;
     for (const [, p] of this.pendingRequests) {
       clearTimeout(p.timer);
-      p.reject(new Error("Bridge stopped"));
+      p.reject(new AgentError({
+        message: "Bridge stopped",
+        code: ERROR_CODES.AGENT_ABORTED
+      }));
     }
     this.pendingRequests.clear();
     this.inflightGuards.clear();
@@ -2780,11 +3006,11 @@ function validateAgainstSchema(value, schema) {
   walk2(value, schema, "", errors);
   return { ok: errors.length === 0, errors };
 }
-function walk2(value, schema, path6, errors) {
+function walk2(value, schema, path7, errors) {
   if (schema.enum !== void 0) {
     if (!schema.enum.some((e) => deepEqual(e, value))) {
       errors.push({
-        path: path6 || "<root>",
+        path: path7 || "<root>",
         message: `expected one of ${JSON.stringify(schema.enum)}, got ${JSON.stringify(value)}`
       });
       return;
@@ -2793,7 +3019,7 @@ function walk2(value, schema, path6, errors) {
   if (typeof schema.type === "string") {
     if (!checkType(value, schema.type)) {
       errors.push({
-        path: path6 || "<root>",
+        path: path7 || "<root>",
         message: `expected ${schema.type}, got ${describeType(value)}`
       });
       return;
@@ -2803,19 +3029,19 @@ function walk2(value, schema, path6, errors) {
     const obj = value;
     for (const req of schema.required ?? []) {
       if (!(req in obj)) {
-        errors.push({ path: joinPath(path6, req), message: "required property missing" });
+        errors.push({ path: joinPath(path7, req), message: "required property missing" });
       }
     }
     if (schema.properties) {
       for (const [key, subSchema] of Object.entries(schema.properties)) {
         if (key in obj) {
-          walk2(obj[key], subSchema, joinPath(path6, key), errors);
+          walk2(obj[key], subSchema, joinPath(path7, key), errors);
         }
       }
     }
   }
   if (schema.type === "array" && Array.isArray(value) && schema.items) {
-    value.forEach((item, i) => walk2(item, schema.items, `${path6}[${i}]`, errors));
+    value.forEach((item, i) => walk2(item, schema.items, `${path7}[${i}]`, errors));
   }
 }
 function checkType(value, type) {
@@ -2913,7 +3139,7 @@ function createToolOutputSerializer(opts = {}) {
 }
 
 // src/execution/tool-executor.ts
-var ToolExecutor = class {
+var ToolExecutor = class _ToolExecutor {
   constructor(registry, opts) {
     this.registry = registry;
     this.opts = opts;
@@ -2925,6 +3151,10 @@ var ToolExecutor = class {
   }
   registry;
   opts;
+  /** Minimum gap between coalesced `partial_output` tool.progress emits. */
+  static PROGRESS_EMIT_INTERVAL_MS = 100;
+  /** Max chars of accumulated stream text carried per coalesced emit. */
+  static PROGRESS_TAIL_CHARS = 16384;
   serializer;
   iterationTimeoutMs;
   maxToolTimeoutMs;
@@ -2970,9 +3200,6 @@ Please call the tool again with arguments that match its inputSchema. You can us
         return { result, tool, durationMs: Date.now() - start };
       }
       const toolDangerousCaps = getDangerousCapabilities(tool);
-      if (toolDangerousCaps.length > 0) {
-        if (this.opts.events) ;
-      }
       if (hasMalformedArguments(use.input)) {
         const result = this.malformedInputResult(use, extractMalformedRaw(use.input));
         budget = this.decrementBudget(result, budget);
@@ -3210,17 +3437,48 @@ ${post.additionalContext}` };
       throw new Error(`Tool "${tool.name}" does not support streaming execution`);
     }
     const stream = tool.executeStream(input, ctx, { signal });
-    for await (const ev of stream) {
-      if (ev.type === "final") {
-        finalOutput = ev.output;
-        sawFinal = true;
-        break;
-      }
+    const iter = stream[Symbol.asyncIterator]();
+    let progressTail = "";
+    let lastProgressEmitAt = 0;
+    const emitProgress = (ev) => {
       this.opts.events?.emit("tool.progress", {
         name: tool.name,
         id: toolUseId ?? "<unknown>",
         event: ev
       });
+    };
+    const flushProgressTail = (force) => {
+      if (progressTail.length === 0) return;
+      const now = Date.now();
+      if (!force && now - lastProgressEmitAt < _ToolExecutor.PROGRESS_EMIT_INTERVAL_MS) return;
+      const text = progressTail;
+      progressTail = "";
+      lastProgressEmitAt = now;
+      emitProgress({ type: "partial_output", text });
+    };
+    try {
+      while (true) {
+        const { done, value: ev } = await iter.next();
+        if (done) break;
+        if (ev.type === "final") {
+          finalOutput = ev.output;
+          sawFinal = true;
+          break;
+        }
+        if (ev.type === "partial_output" && typeof ev.text === "string") {
+          progressTail += ev.text;
+          if (progressTail.length > _ToolExecutor.PROGRESS_TAIL_CHARS) {
+            progressTail = progressTail.slice(-_ToolExecutor.PROGRESS_TAIL_CHARS);
+          }
+          flushProgressTail(false);
+          continue;
+        }
+        flushProgressTail(true);
+        emitProgress(ev);
+      }
+      flushProgressTail(true);
+    } finally {
+      await iter.return?.(void 0);
     }
     if (!sawFinal) {
       throw new Error(`tool "${tool.name}" executeStream completed without a 'final' event`);
@@ -3329,6 +3587,253 @@ function extractMalformedRaw(input) {
   }
 }
 
+// src/core/conversation-state.ts
+var ConversationState = class {
+  ctx;
+  listeners = /* @__PURE__ */ new Set();
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  get messages() {
+    return this.ctx.messages;
+  }
+  get todos() {
+    return this.ctx.todos;
+  }
+  get meta() {
+    return this.ctx.meta;
+  }
+  /**
+   * Cheap immutable snapshot. Useful for tests and for compaction passes
+   * that need a stable view across an async boundary.
+   *
+   * Uses shallow-freeze instead of deep-freeze: only the wrapper object
+   * and the three content arrays are frozen. Individual message/todo
+   * objects are NOT recursively frozen — they are reconstructed via
+   * spread copies and are immutable by convention. This cuts the freeze
+   * count from O(n·m·d) (n=messages, m=content blocks, d=depth) to O(1).
+   */
+  snapshot() {
+    const snap = {
+      messages: [...this.ctx.messages],
+      todos: [...this.ctx.todos],
+      meta: { ...this.ctx.meta }
+    };
+    Object.freeze(snap.messages);
+    Object.freeze(snap.todos);
+    Object.freeze(snap.meta);
+    return Object.freeze(snap);
+  }
+  appendMessage(message) {
+    if (message._estTokens === void 0) {
+      message._estTokens = computeMessageTokens(message);
+    }
+    this.ctx.messages.splice(this.ctx.messages.length, 0, message);
+    this.emit({ kind: "message_appended", message });
+  }
+  replaceMessages(messages) {
+    for (const m of messages) {
+      if (m._estTokens === void 0) {
+        m._estTokens = computeMessageTokens(m);
+      }
+    }
+    const arr = this.ctx.messages;
+    if (messages.length < arr.length) {
+      arr.length = messages.length;
+    }
+    for (let i = 0; i < messages.length; i++) {
+      arr[i] = messages[i];
+    }
+    if (messages.some(
+      (m) => Array.isArray(m.content) && m.content.some((b) => b.type === "tool_use" || b.type === "tool_result")
+    )) {
+      this.ctx.toolAdjacencyDirty = true;
+    }
+    this.emit({ kind: "messages_replaced", messages: [...messages] });
+  }
+  replaceTodos(todos) {
+    const allDone = todos.length > 0 && todos.every((t) => t.status === "completed");
+    const effective = allDone ? [] : todos;
+    this.ctx.todos.length = 0;
+    this.ctx.todos.splice(0, 0, ...effective);
+    this.emit({ kind: "todos_replaced", todos: [...effective] });
+  }
+  setMeta(key, value) {
+    this.ctx.meta[key] = value;
+    this.emit({ kind: "meta_set", key, value });
+  }
+  deleteMeta(key) {
+    if (!(key in this.ctx.meta)) return;
+    delete this.ctx.meta[key];
+    this.emit({ kind: "meta_deleted", key });
+  }
+  clearMeta() {
+    const keys = Object.keys(this.ctx.meta);
+    if (keys.length === 0) return;
+    for (const key of keys) delete this.ctx.meta[key];
+    this.emit({ kind: "meta_cleared" });
+  }
+  /**
+   * Subscribe to mutations that go through this wrapper. Direct mutations of
+   * the compatibility arrays are intentionally not observed.
+   */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit(change) {
+    for (const h of this.listeners) {
+      try {
+        h(change, this);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/core/context.ts
+var Context = class {
+  messages = [];
+  todos = [];
+  readFiles = /* @__PURE__ */ new Set();
+  fileMtimes = /* @__PURE__ */ new Map();
+  systemPrompt;
+  provider;
+  session;
+  signal;
+  tokenCounter;
+  cwd;
+  projectRoot;
+  /** Mutable working directory — starts as `cwd`. Change via `setWorkingDir()`. */
+  workingDir;
+  model;
+  tools = [];
+  meta = {};
+  /** Agent id performing this run (e.g. 'leader', 'executor'). */
+  agentId;
+  /** Human-readable agent name. */
+  agentName;
+  /** Callbacks fired when `setWorkingDir()` changes the working directory. */
+  _onWorkingDirChanged = [];
+  /**
+   * Set to true when the conversation gains new tool_use or tool_result
+   * blocks — the only time repairToolUseAdjacency() can find new issues.
+   * buildAndRunRequestPipeline() checks this flag to skip an O(n) scan
+   * on iterations where no tool content was added (pure text responses).
+   */
+  toolAdjacencyDirty = false;
+  constructor(init) {
+    this.systemPrompt = init.systemPrompt;
+    this.provider = init.provider;
+    this.session = init.session;
+    this.signal = init.signal;
+    this.tokenCounter = init.tokenCounter;
+    this.cwd = init.cwd;
+    this.projectRoot = init.projectRoot;
+    this.workingDir = init.workingDir ?? init.cwd;
+    this.model = init.model;
+    this.tools = init.tools ?? [];
+    this.agentId = init.agentId ?? "unknown";
+    this.agentName = init.agentName ?? "Unknown Agent";
+  }
+  /**
+   * Observable wrapper over the mutable conversation state. Lazy so
+   * subsystems that don't subscribe pay nothing. Mutations made directly
+   * on `ctx.messages` / `ctx.todos` are still visible through this
+   * wrapper's read API (it holds a reference, not a copy) but only
+   * mutations that go through `state.appendMessage()` etc. fire
+   * `onChange`. New code should prefer the wrapper API.
+   */
+  _state = null;
+  get state() {
+    if (!this._state) this._state = new ConversationState(this);
+    return this._state;
+  }
+  /**
+   * Register a teardown hook tied to the current run's abort signal.
+   * Hooks registered before a run starts are stored and fired when the
+   * next run ends; there is no immediate fire when no run is active.
+   *
+   * **Scope:** these hooks fire on the **whole agent run's** abort, not on
+   * an individual tool call. For per-tool teardown of resources owned by
+   * the tool author (child processes, handles), prefer `Tool.cleanup` —
+   * see its JSDoc for the full rule.
+   */
+  abortHooks = /* @__PURE__ */ new Set();
+  registerAbortHook(fn) {
+    this.abortHooks.add(fn);
+    return () => this.abortHooks.delete(fn);
+  }
+  async drainAbortHooks() {
+    const snapshot = [...this.abortHooks].reverse();
+    this.abortHooks.clear();
+    for (const fn of snapshot) {
+      try {
+        await fn();
+      } catch {
+      }
+    }
+  }
+  recordRead(absPath, mtimeMs) {
+    this.readFiles.add(absPath);
+    this.fileMtimes.set(absPath, mtimeMs);
+  }
+  /** Clear accumulated file-read metadata after compaction or at boundaries
+   *  where stale read history could cause tools to skip legitimate re-reads.
+   *  The agent re-populates this naturally on the next file access. */
+  clearFileTracking() {
+    this.readFiles.clear();
+    this.fileMtimes.clear();
+  }
+  hasRead(absPath) {
+    return this.readFiles.has(absPath);
+  }
+  lastReadMtime(absPath) {
+    return this.fileMtimes.get(absPath);
+  }
+  /**
+   * Change the working directory for path resolution. Resolves relative paths
+   * against `projectRoot` and validates the result is within the project root.
+   * Fires all registered `onWorkingDirChanged` callbacks.
+   * Returns the resolved absolute path.
+   */
+  setWorkingDir(dir) {
+    const resolved = path4.isAbsolute(dir) ? path4.resolve(dir) : path4.resolve(this.projectRoot, dir);
+    const root = path4.resolve(this.projectRoot);
+    const rel = path4.relative(root, resolved);
+    if (rel.startsWith("..") || path4.isAbsolute(rel)) {
+      throw new Error(
+        `Working directory "${resolved}" is outside project root "${root}"`
+      );
+    }
+    const old = this.workingDir;
+    this.workingDir = resolved;
+    for (const cb of this._onWorkingDirChanged) {
+      try {
+        cb(resolved, old);
+      } catch {
+      }
+    }
+    return resolved;
+  }
+  /**
+   * Register a callback that fires when the working directory changes.
+   * Returns an unsubscribe function. Callbacks are fired synchronously
+   * inside `setWorkingDir()` — errors in callbacks are swallowed so one
+   * bad listener doesn't prevent others from executing.
+   */
+  onWorkingDirChanged(cb) {
+    this._onWorkingDirChanged.push(cb);
+    return () => {
+      const idx = this._onWorkingDirChanged.indexOf(cb);
+      if (idx >= 0) this._onWorkingDirChanged.splice(idx, 1);
+    };
+  }
+  usage() {
+    return this.tokenCounter.total();
+  }
+};
+
 // src/utils/regex-guard.ts
 var MAX_PATTERN_LEN = 512;
 var DANGEROUS_PATTERNS = [
@@ -3641,6 +4146,6 @@ function renderPlainText(meta, events) {
   return lines.join("\n");
 }
 
-export { AgentError, CONTEXT_WINDOW_MODES, ConfigError, DEFAULT_AUTONOMY_CONFIG, DEFAULT_CONTEXT_CONFIG, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEFAULT_MODES, DEFAULT_RECOVERY_STRATEGIES, DEFAULT_SESSION_LOGGING_CONFIG, DEFAULT_SESSION_PRUNE_DAYS, DEFAULT_SPEC_TEMPLATE, DEFAULT_TOOLS_CONFIG, DefaultErrorHandler, DefaultLogger, DefaultModelsRegistry, DefaultPathResolver, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultTokenCounter, ERROR_CODES, FsError, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, MEMORY_TYPE_LABELS, PluginError, ProviderError, SessionError, StreamHangError, ToolError, ToolExecutor, WrongStackError, asBlocks, asText, buildRecoveryStrategies, classifyFamily, computeTaskProgress, createMessage, decryptConfigSecrets, encryptConfigSecrets, findCriticalPath, formatContextWindowModeList, getContextWindowMode, isAgentError, isConfigError, isContextWindowModeId, isFsError, isImageBlock, isPluginError, isSecretField, isSessionError, isTextBlock, isThinkingBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, listContextWindowModes, migratePlaintextSecrets, resolveContextWindowPolicy, rewriteConfigEncrypted, toWrongStackError, topologicalSort };
+export { AgentError, CONTEXT_WINDOW_MODES, ConfigError, Context, DEFAULT_AUTONOMY_CONFIG, DEFAULT_CONTEXT_CONFIG, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEFAULT_MODES, DEFAULT_RECOVERY_STRATEGIES, DEFAULT_SESSION_LOGGING_CONFIG, DEFAULT_SESSION_PRUNE_DAYS, DEFAULT_SPEC_TEMPLATE, DEFAULT_TOOLS_CONFIG, DefaultErrorHandler, DefaultLogger, DefaultModelsRegistry, DefaultPathResolver, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultTokenCounter, ERROR_CODES, FsError, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, MEMORY_TYPE_LABELS, PluginError, ProviderError, SddError, SessionError, StreamHangError, ToolError, ToolExecutor, WrongStackError, asBlocks, asText, buildRecoveryStrategies, classifyFamily, computeTaskProgress, createMessage, decryptConfigSecrets, encryptConfigSecrets, findCriticalPath, formatContextWindowModeList, getContextWindowMode, isAgentError, isConfigError, isContextWindowModeId, isFsError, isImageBlock, isPluginError, isSddError, isSecretField, isSessionError, isTextBlock, isThinkingBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, listContextWindowModes, migratePlaintextSecrets, noOpLogger, resolveContextWindowPolicy, rewriteConfigEncrypted, toWrongStackError, topologicalSort };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map