@ethosagent/core 0.2.6 → 0.3.0

package/dist/index.js

@@ -1,10 +1,50 @@
 // src/agent-loop.ts
+import { createHash as createHash3, randomUUID } from "crypto";
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+import {
+  DOWNGRADE_REJECTION_MESSAGE,
+  INJECTION_DEFENSE_PRELUDE,
+  resolveDowngradedTools,
+  shortPatternCheck,
+  wrapUntrusted
+} from "@ethosagent/safety-injection";
+
+// ../storage-fs/src/default-deny.ts
 import { homedir } from "os";
-import { join } from "path";
+function defaultAlwaysDeny() {
+  const home = homedir();
+  return [
+    `${home}/.ssh`,
+    `${home}/.aws/credentials`,
+    `${home}/.aws/config`,
+    `${home}/.gnupg`,
+    `${home}/.netrc`,
+    `${home}/.bash_history`,
+    `${home}/.zsh_history`,
+    `${home}/.psql_history`,
+    `${home}/.mysql_history`,
+    `${home}/.npmrc`,
+    `${home}/Library/Keychains`,
+    "/etc/passwd",
+    "/etc/shadow",
+    "/etc/sudoers",
+    "/etc/sudoers.d",
+    "/root",
+    "/boot",
+    "/sys",
+    "/proc/sys"
+  ];
+}
+
+// ../storage-fs/src/fs-attachment-cache.ts
+import { createHash } from "crypto";
+import { join, resolve, sep } from "path";
 
 // ../storage-fs/src/fs-storage.ts
 import {
   appendFile,
+  chmod,
   mkdir,
   readdir,
   readFile,
@@ -14,6 +54,9 @@ import {
   writeFile
 } from "fs/promises";
 
+// ../storage-fs/src/in-memory-attachment-cache.ts
+import { createHash as createHash2 } from "crypto";
+
 // ../storage-fs/src/in-memory-storage.ts
 import { dirname } from "path";
 
@@ -26,11 +69,16 @@ var ScopedStorage = class {
     this.inner = inner;
     this.readPrefixes = scope.read.map(normalizePrefix);
     this.writePrefixes = scope.write.map(normalizePrefix);
+    this.denyPrefixes = (scope.alwaysDeny ?? []).map(normalizePrefix);
   }
   inner;
   readPrefixes;
   writePrefixes;
+  denyPrefixes;
   check(path, kind) {
+    if (isPathAllowed(path, this.denyPrefixes)) {
+      throw new BoundaryError(kind, path, this.denyPrefixes, "always-deny floor");
+    }
     const allowed = kind === "read" ? this.readPrefixes : this.writePrefixes;
     if (!isPathAllowed(path, allowed)) {
       throw new BoundaryError(kind, path, allowed);
@@ -40,6 +88,10 @@ var ScopedStorage = class {
     this.check(path, "read");
     return this.inner.read(path);
   }
+  async readBytes(path) {
+    this.check(path, "read");
+    return this.inner.readBytes(path);
+  }
   async exists(path) {
     this.check(path, "read");
     return this.inner.exists(path);
@@ -81,6 +133,10 @@ var ScopedStorage = class {
     this.check(to, "write");
     return this.inner.rename(from, to);
   }
+  async chmod(path, mode) {
+    this.check(path, "write");
+    return this.inner.chmod(path, mode);
+  }
 };
 function normalizePrefix(prefix) {
   return prefix;
@@ -96,10 +152,206 @@ function isPathAllowed(path, prefixes) {
   return false;
 }
 
+// ../storage-fs/src/secrets.ts
+import { dirname as dirname2, join as join2 } from "path";
+
+// src/attachment-annotation.ts
+function formatSize(bytes) {
+  if (bytes === void 0) return "";
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function escapeXmlAttr(s) {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function buildAttachmentAnnotation(attachments) {
+  if (attachments.length === 0) return "";
+  const lines = attachments.map((a) => {
+    const parts = [`ref="${escapeXmlAttr(a.ref)}"`, `mime="${escapeXmlAttr(a.mimeType)}"`];
+    if (a.sizeBytes !== void 0) parts.push(`size="${formatSize(a.sizeBytes)}"`);
+    if (a.filename) parts.push(`filename="${escapeXmlAttr(a.filename)}"`);
+    return `  <file ${parts.join(" ")} />`;
+  });
+  return `<attachments>
+${lines.join("\n")}
+</attachments>`;
+}
+
+// src/context-engines/token-estimator.ts
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+function messageContentChars(content) {
+  if (typeof content === "string") return content.length;
+  let total = 0;
+  for (const block of content) {
+    if (block.type === "text") total += block.text.length;
+    else if (block.type === "tool_use")
+      total += JSON.stringify(block.input).length + block.name.length;
+    else if (block.type === "tool_result") total += block.content.length;
+  }
+  return total;
+}
+function estimateMessageTokens(message) {
+  return Math.ceil(messageContentChars(message.content) / CHARS_PER_TOKEN);
+}
+function estimateMessagesTokens(input) {
+  if (typeof input === "string") return estimateTokens(input);
+  if (Array.isArray(input)) {
+    let total = 0;
+    for (const m of input) total += estimateMessageTokens(m);
+    return total;
+  }
+  return estimateMessageTokens(input);
+}
+
+// src/context-engines/drop-oldest.ts
+var DropOldestEngine = class {
+  name = "drop_oldest";
+  async compact(opts) {
+    const options = opts.personality.context_engine_options ?? {};
+    const preserveFront = Math.max(0, options.preserve_first_n_turns ?? 0);
+    const target = opts.targetTokens;
+    const head = opts.messages.slice(0, preserveFront);
+    const tail = opts.messages.slice(preserveFront);
+    let total = estimateMessagesTokens(opts.currentSystem) + estimateMessagesTokens(head) + estimateMessagesTokens(tail);
+    let dropped = 0;
+    while (total > target && tail.length > 0) {
+      const removed = tail.shift();
+      if (!removed) break;
+      total -= estimateMessagesTokens(removed);
+      dropped++;
+    }
+    return {
+      messages: [...head, ...tail],
+      notes: dropped === 0 ? "no compaction needed" : `dropped ${dropped} oldest message(s)`
+    };
+  }
+};
+
+// src/context-engines/reference-preserving.ts
+var REFERENCE_PATTERN = /[A-Za-z_][\w./-]*\.(?:ts|tsx|js|jsx|py|go|rs|java|md|yaml|yml|json)\b|\b[A-Z][A-Za-z0-9]+(?:\.[A-Za-z0-9_]+)+\b/;
+function messageText(content) {
+  if (typeof content === "string") return content;
+  return content.map((b) => {
+    if (b.type === "text") return b.text;
+    if (b.type === "tool_result") return b.content;
+    if (b.type === "tool_use") return `${b.name} ${JSON.stringify(b.input)}`;
+    return "";
+  }).join(" ");
+}
+function carriesReference(message) {
+  return REFERENCE_PATTERN.test(messageText(message.content));
+}
+var ReferencePreservingEngine = class {
+  name = "reference_preserving";
+  async compact(opts) {
+    const target = opts.targetTokens;
+    const systemTokens = estimateMessagesTokens(opts.currentSystem);
+    const tailKeep = Math.min(4, opts.messages.length);
+    const head = opts.messages.slice(0, opts.messages.length - tailKeep);
+    const tail = opts.messages.slice(opts.messages.length - tailKeep);
+    let total = systemTokens + estimateMessagesTokens([...head, ...tail]);
+    const kept = [];
+    let droppedProse = 0;
+    for (const m of head) {
+      if (total <= target) {
+        kept.push(m);
+        continue;
+      }
+      if (carriesReference(m)) {
+        kept.push(m);
+      } else {
+        total -= estimateMessageTokens(m);
+        droppedProse++;
+      }
+    }
+    while (total > target && kept.length > 0) {
+      const removed = kept.shift();
+      if (!removed) break;
+      total -= estimateMessageTokens(removed);
+    }
+    const note = droppedProse > 0 ? `dropped ${droppedProse} prose message(s); kept ${kept.length} reference-bearing` : "no prose messages to drop";
+    return { messages: [...kept, ...tail], notes: note };
+  }
+};
+
+// src/context-engines/semantic-summary.ts
+var SemanticSummaryEngine = class {
+  name = "semantic_summary";
+  summarize;
+  constructor(opts = {}) {
+    if (opts.summarize) this.summarize = opts.summarize;
+  }
+  async compact(opts) {
+    const options = opts.personality.context_engine_options ?? {};
+    const preserveFront = Math.max(0, options.preserve_first_n_turns ?? 1);
+    const summaryTarget = options.summary_target_tokens ?? 800;
+    const target = opts.targetTokens;
+    const front = opts.messages.slice(0, preserveFront);
+    const tailKeep = Math.min(6, Math.max(0, opts.messages.length - preserveFront));
+    const middle = opts.messages.slice(preserveFront, opts.messages.length - tailKeep);
+    const tail = opts.messages.slice(opts.messages.length - tailKeep);
+    if (middle.length === 0) {
+      return { messages: opts.messages, notes: "nothing to summarize" };
+    }
+    const middleTokens = estimateMessagesTokens(middle);
+    const totalNow = estimateMessagesTokens(opts.currentSystem) + estimateMessagesTokens([...front, ...tail]) + middleTokens;
+    if (totalNow <= target) {
+      return { messages: opts.messages, notes: "no compaction needed" };
+    }
+    let summaryText;
+    if (this.summarize) {
+      summaryText = await this.summarize(middle, summaryTarget);
+    } else {
+      summaryText = `[summary] ${middle.length} earlier message(s) elided to fit context budget.`;
+    }
+    const summaryMessage = {
+      role: "assistant",
+      content: [{ type: "text", text: summaryText }]
+    };
+    const cacheBreakpoints = [];
+    if (front.length > 0) cacheBreakpoints.push(front.length - 1);
+    cacheBreakpoints.push(front.length);
+    return {
+      messages: [...front, summaryMessage, ...tail],
+      notes: `summarized ${middle.length} message(s) \u2192 ${estimateMessageTokens(summaryMessage)} tokens`,
+      summaryText,
+      cacheBreakpoints
+    };
+  }
+};
+
+// src/context-engines/registry.ts
+var DefaultContextEngineRegistry = class {
+  engines = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.register(new DropOldestEngine());
+    this.register(
+      opts.summarize ? new SemanticSummaryEngine({ summarize: opts.summarize }) : new SemanticSummaryEngine()
+    );
+    this.register(new ReferencePreservingEngine());
+  }
+  register(engine) {
+    this.engines.set(engine.name, engine);
+  }
+  get(name) {
+    return this.engines.get(name);
+  }
+  names() {
+    return [...this.engines.keys()];
+  }
+};
+
 // src/defaults/in-memory-session.ts
 var InMemorySessionStore = class {
   sessions = /* @__PURE__ */ new Map();
   messages = /* @__PURE__ */ new Map();
+  compressions = /* @__PURE__ */ new Map();
+  turnState = /* @__PURE__ */ new Map();
   idCounter = 0;
   async createSession(data) {
     const session = {
@@ -129,6 +381,8 @@ var InMemorySessionStore = class {
   async deleteSession(id) {
     this.sessions.delete(id);
     this.messages.delete(id);
+    this.compressions.delete(id);
+    this.turnState.delete(id);
   }
   async listSessions(filter) {
     let results = [...this.sessions.values()];
@@ -193,6 +447,31 @@ var InMemorySessionStore = class {
     results.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
     return results.slice(0, options?.limit ?? 20);
   }
+  async recordCompression(event) {
+    const full = {
+      ...event,
+      id: `compression_${++this.idCounter}`,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    const list = this.compressions.get(event.sessionId) ?? [];
+    list.push(full);
+    this.compressions.set(event.sessionId, list);
+    return full;
+  }
+  async listCompressions(sessionId) {
+    return [...this.compressions.get(sessionId) ?? []];
+  }
+  async recordTurnStart(sessionId) {
+    const state = this.turnState.get(sessionId) ?? { turnCount: 0, lastCompactionTurn: 0 };
+    state.turnCount += 1;
+    this.turnState.set(sessionId, state);
+    return { turnNumber: state.turnCount, lastCompactionTurn: state.lastCompactionTurn };
+  }
+  async recordCompactionTurn(sessionId, turnNumber) {
+    const state = this.turnState.get(sessionId) ?? { turnCount: 0, lastCompactionTurn: 0 };
+    state.lastCompactionTurn = turnNumber;
+    this.turnState.set(sessionId, state);
+  }
   async pruneOldSessions(olderThan) {
     let count = 0;
     for (const [id, session] of this.sessions.entries()) {
@@ -213,7 +492,16 @@ var NoopMemoryProvider = class {
   async prefetch(_ctx) {
     return null;
   }
-  async sync(_ctx, _updates) {
+  async read(_key, _ctx) {
+    return null;
+  }
+  async search(_query, _ctx, _opts) {
+    return [];
+  }
+  async sync(_updates, _ctx) {
+  }
+  async list(_ctx, _opts) {
+    return [];
   }
 };
 
@@ -361,7 +649,345 @@ var DefaultHookRegistry = class {
   }
 };
 
+// src/scoped/scoped-attachments.ts
+var ScopedAttachmentsImpl = class {
+  attachments;
+  cache;
+  constructor(allAttachments, kinds, cache) {
+    this.cache = cache;
+    this.attachments = kinds === "*" ? allAttachments : allAttachments.filter((a) => kinds.includes(a.type));
+  }
+  list() {
+    return this.attachments;
+  }
+  async open(att) {
+    if (!this.attachments.some((a) => a.ref === att.ref)) {
+      throw new Error(`Attachment ref "${att.ref}" is not in the scoped list for this tool`);
+    }
+    if (att.url.startsWith("file://")) {
+      return { path: this.cache.resolveLocalPath(att.url) };
+    }
+    throw new Error(`Unsupported URL scheme in attachment: ${att.url}`);
+  }
+  async openByRef(ref) {
+    const att = this.attachments.find((a) => a.ref === ref);
+    if (!att) throw new Error(`No attachment with ref "${ref}"`);
+    return this.open(att);
+  }
+};
+
+// src/scoped/scoped-fetch.ts
+import { safeFetch } from "@ethosagent/safety-network";
+var ScopedFetchImpl = class {
+  constructor(allowedHosts, policy, testSeam = {}) {
+    this.allowedHosts = allowedHosts;
+    this.policy = policy;
+    this.testSeam = testSeam;
+  }
+  allowedHosts;
+  policy;
+  testSeam;
+  async fetch(url, init) {
+    const parsed = new URL(url);
+    if (!this.isHostAllowed(parsed.hostname)) {
+      throw new Error(`HOST_NOT_ALLOWED: ${parsed.hostname} is not in the declared allowedHosts`);
+    }
+    const { redirect: _redirect, ...rest } = init ?? {};
+    const result = await safeFetch(parsed.toString(), {
+      policy: this.policy,
+      init: rest,
+      fetchImpl: this.testSeam.fetchImpl,
+      resolveHost: this.testSeam.resolveHost
+    });
+    if (!result.ok) {
+      throw new Error(`HOST_NOT_ALLOWED: ${result.reason}`);
+    }
+    return result.response;
+  }
+  isHostAllowed(hostname) {
+    if (this.allowedHosts.has("*")) return true;
+    if (this.allowedHosts.has(hostname)) return true;
+    for (const pattern of this.allowedHosts) {
+      if (pattern.startsWith("*.")) {
+        const suffix = pattern.slice(1);
+        if (hostname.endsWith(suffix) && hostname.length > suffix.length) return true;
+      }
+    }
+    return false;
+  }
+};
+
+// src/scoped/scoped-fs.ts
+import { normalize, resolve as resolve2 } from "path";
+var ScopedFsImpl = class {
+  constructor(storage, readPaths, writePaths) {
+    this.storage = storage;
+    this.readPaths = readPaths;
+    this.writePaths = writePaths;
+    this.denyPaths = defaultAlwaysDeny().map((p) => normalize(resolve2(p)));
+  }
+  storage;
+  readPaths;
+  writePaths;
+  denyPaths;
+  async read(path) {
+    this.checkReach(path, this.readPaths, "read");
+    const content = await this.storage.read(path);
+    if (content === null) throw new Error(`File not found: ${path}`);
+    return content;
+  }
+  async readBytes(path) {
+    this.checkReach(path, this.readPaths, "read");
+    const bytes = await this.storage.readBytes(path);
+    if (bytes === null) throw new Error(`File not found: ${path}`);
+    return bytes;
+  }
+  async write(path, content) {
+    this.checkReach(path, this.writePaths, "write");
+    await this.storage.write(path, content);
+  }
+  async exists(path) {
+    this.checkReach(path, this.readPaths, "read");
+    return this.storage.exists(path);
+  }
+  async list(path) {
+    this.checkReach(path, this.readPaths, "read");
+    return this.storage.list(path);
+  }
+  async mtime(path) {
+    this.checkReach(path, this.readPaths, "read");
+    return this.storage.mtime(path);
+  }
+  async mkdir(dir) {
+    this.checkReach(dir, this.writePaths, "write");
+    await this.storage.mkdir(dir);
+  }
+  async listEntries(dir) {
+    this.checkReach(dir, this.readPaths, "read");
+    return this.storage.listEntries(dir);
+  }
+  checkReach(path, allowed, kind) {
+    const canonical = normalize(resolve2(path));
+    for (const deny of this.denyPaths) {
+      if (canonical === deny || canonical.startsWith(deny.endsWith("/") ? deny : `${deny}/`)) {
+        throw new Error(`PATH_NOT_REACHABLE: ${kind} of "${path}" hits the always-deny floor`);
+      }
+    }
+    for (const prefix of allowed) {
+      const canonicalPrefix = normalize(resolve2(prefix));
+      if (canonical === canonicalPrefix || canonical.startsWith(
+        canonicalPrefix.endsWith("/") ? canonicalPrefix : `${canonicalPrefix}/`
+      ))
+        return;
+    }
+    throw new Error(`PATH_NOT_REACHABLE: ${kind} not permitted for ${path}`);
+  }
+};
+
+// src/scoped/scoped-process.ts
+import { spawn as nodeSpawn } from "child_process";
+var ScopedProcessImpl = class {
+  constructor(allowedBinaries) {
+    this.allowedBinaries = allowedBinaries;
+  }
+  allowedBinaries;
+  async spawn(binary, args, opts) {
+    if (!this.allowedBinaries.has("*") && !this.allowedBinaries.has(binary)) {
+      throw new Error(`BINARY_NOT_ALLOWED: ${binary} is not in the declared allowedBinaries`);
+    }
+    return new Promise((resolve4, reject) => {
+      const child = nodeSpawn(binary, args, {
+        cwd: opts?.cwd,
+        env: opts?.env ? { ...process.env, ...opts.env } : process.env,
+        timeout: opts?.timeout,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const stdout = [];
+      const stderr = [];
+      child.stdout.on("data", (chunk) => stdout.push(chunk));
+      child.stderr.on("data", (chunk) => stderr.push(chunk));
+      child.on("error", reject);
+      child.on("close", (exitCode) => {
+        resolve4({
+          exitCode: exitCode ?? 1,
+          stdout: Buffer.concat(stdout).toString(),
+          stderr: Buffer.concat(stderr).toString()
+        });
+      });
+    });
+  }
+};
+
+// src/scoped/scoped-secrets.ts
+var ScopedSecretsImpl = class {
+  constructor(declaredRefs, backend) {
+    this.declaredRefs = declaredRefs;
+    this.backend = backend;
+  }
+  declaredRefs;
+  backend;
+  async get(ref) {
+    if (!this.declaredRefs.has(ref)) {
+      throw new Error(`SECRET_NOT_DECLARED: ${ref} is not in the tool's declared secrets`);
+    }
+    return this.backend(ref);
+  }
+};
+
+// src/capability-resolver.ts
+function resolveCapabilities(toolName, capabilities, scopeIds, backends) {
+  if (!capabilities) return {};
+  const result = {};
+  if (capabilities.network) {
+    const declaredHosts = capabilities.network.allowedHosts;
+    const policy = backends.personalityNetworkPolicy ?? {};
+    const personalityAllow = policy.allow;
+    let resolvedHosts;
+    if (declaredHosts.includes("*")) {
+      resolvedHosts = new Set(personalityAllow ?? []);
+    } else if (personalityAllow) {
+      resolvedHosts = new Set(
+        declaredHosts.filter(
+          (host) => personalityAllow.some((pattern) => {
+            if (pattern === host || pattern === "*") return true;
+            if (pattern.startsWith("*.")) {
+              const suffix = pattern.slice(1);
+              return host.endsWith(suffix) && host.length > suffix.length;
+            }
+            return false;
+          })
+        )
+      );
+    } else {
+      resolvedHosts = new Set(declaredHosts);
+    }
+    result.scopedFetch = new ScopedFetchImpl(resolvedHosts, policy);
+  }
+  if (capabilities.secrets && backends.secretsBackend) {
+    result.secretsResolver = new ScopedSecretsImpl(
+      new Set(capabilities.secrets),
+      backends.secretsBackend
+    );
+  }
+  if (capabilities.storage && backends.kvStoreFactory) {
+    const scope = capabilities.storage.scope;
+    let resolvedScopeId;
+    if (scope === "tool-private") {
+      resolvedScopeId = `tool:${toolName}`;
+    } else if (scope === "session") {
+      resolvedScopeId = `session:${scopeIds.sessionId}`;
+    } else {
+      resolvedScopeId = `personality:${scopeIds.personalityId ?? scopeIds.sessionId}`;
+    }
+    result.kvStore = backends.kvStoreFactory(toolName, resolvedScopeId);
+  }
+  if (capabilities.fs_reach && backends.storage) {
+    const readDecl = capabilities.fs_reach.read;
+    const writeDecl = capabilities.fs_reach.write;
+    const readPaths = readDecl === "from-personality" ? backends.personalityFsReach?.read ?? [] : readDecl ?? [];
+    const writePaths = writeDecl === "from-personality" ? backends.personalityFsReach?.write ?? [] : writeDecl ?? [];
+    result.scopedFs = new ScopedFsImpl(backends.storage, new Set(readPaths), new Set(writePaths));
+  }
+  if (capabilities.process) {
+    result.scopedProcess = new ScopedProcessImpl(new Set(capabilities.process.allowedBinaries));
+  }
+  if (capabilities.attachments && backends.attachmentCache && backends.inboundAttachments) {
+    result.attachments = new ScopedAttachmentsImpl(
+      backends.inboundAttachments,
+      capabilities.attachments.kinds,
+      backends.attachmentCache
+    );
+    const attachmentDirs = /* @__PURE__ */ new Set();
+    for (const att of backends.inboundAttachments) {
+      if (att.url.startsWith("file://")) {
+        const localPath = backends.attachmentCache.resolveLocalPath(att.url);
+        const dir = localPath.slice(0, localPath.lastIndexOf("/"));
+        if (dir) attachmentDirs.add(dir);
+      }
+    }
+    if (attachmentDirs.size > 0) {
+      if (result.scopedFs && backends.storage) {
+        const readDecl = capabilities.fs_reach?.read;
+        const readPaths = readDecl === "from-personality" ? backends.personalityFsReach?.read ?? [] : readDecl ?? [];
+        const writeDecl = capabilities.fs_reach?.write;
+        const writePaths = writeDecl === "from-personality" ? backends.personalityFsReach?.write ?? [] : writeDecl ?? [];
+        const mergedRead = /* @__PURE__ */ new Set([...readPaths, ...attachmentDirs]);
+        result.scopedFs = new ScopedFsImpl(backends.storage, mergedRead, new Set(writePaths));
+      } else if (!result.scopedFs && backends.storage) {
+        result.scopedFs = new ScopedFsImpl(backends.storage, attachmentDirs, /* @__PURE__ */ new Set());
+      }
+    }
+  }
+  return result;
+}
+
+// src/capability-validator.ts
+function hostMatchesPattern(host, pattern) {
+  if (pattern === host) return true;
+  if (pattern === "*") return true;
+  if (pattern.startsWith("*.")) {
+    const suffix = pattern.slice(1);
+    return host.endsWith(suffix) && host.length > suffix.length;
+  }
+  return false;
+}
+function validateRegistration(tool, personality) {
+  const caps = tool.capabilities;
+  if (!caps) return [];
+  const errors = [];
+  if (caps.network) {
+    const allowed = personality.safety?.network?.allow;
+    if (allowed && allowed.length > 0) {
+      for (const host of caps.network.allowedHosts) {
+        if (host === "*") continue;
+        const covered = allowed.some((pattern) => hostMatchesPattern(host, pattern));
+        if (!covered) {
+          errors.push({
+            tool: tool.name,
+            capability: "network",
+            message: `host "${host}" is not in personality network allow list`
+          });
+        }
+      }
+    }
+  }
+  if (caps.fs_reach) {
+    const personalityRead = personality.fs_reach?.read ?? [];
+    const personalityWrite = personality.fs_reach?.write ?? [];
+    if (caps.fs_reach.read && caps.fs_reach.read !== "from-personality") {
+      for (const toolPath of caps.fs_reach.read) {
+        const covered = personalityRead.some((p) => toolPath === p || toolPath.startsWith(`${p}/`));
+        if (!covered) {
+          errors.push({
+            tool: tool.name,
+            capability: "fs_reach.read",
+            message: `path "${toolPath}" is not covered by personality fs_reach.read`
+          });
+        }
+      }
+    }
+    if (caps.fs_reach.write && caps.fs_reach.write !== "from-personality") {
+      for (const toolPath of caps.fs_reach.write) {
+        const covered = personalityWrite.some(
+          (p) => toolPath === p || toolPath.startsWith(`${p}/`)
+        );
+        if (!covered) {
+          errors.push({
+            tool: tool.name,
+            capability: "fs_reach.write",
+            message: `path "${toolPath}" is not covered by personality fs_reach.write`
+          });
+        }
+      }
+    }
+  }
+  return errors;
+}
+
 // src/tool-registry.ts
+function needsBackends(caps) {
+  return !!(caps.network || caps.secrets || caps.storage || caps.fs_reach || caps.process || caps.attachments);
+}
 function mcpServerName(toolName) {
   if (!toolName.startsWith("mcp__")) return void 0;
   return toolName.split("__")[1];
@@ -380,9 +1006,30 @@ function passesFilter(entry, filterOpts) {
 }
 var DefaultToolRegistry = class {
   tools = /* @__PURE__ */ new Map();
+  backends;
+  constructor(backends) {
+    this.backends = backends;
+  }
   register(tool, opts) {
     this.tools.set(tool.name, { tool, pluginId: opts?.pluginId });
   }
+  /**
+   * Validate every tool reachable for this personality (per
+   * `toolNamesForPersonality`) against the personality's policy. Only
+   * the tools the personality could actually call are checked — a
+   * personality that doesn't list `web_search` in its toolset does not
+   * fail because `web_search` declared `api.exa.ai` that's missing from
+   * `network.allow`.
+   */
+  validateToolsForPersonality(personality) {
+    const reach = this.toolNamesForPersonality(personality);
+    const errors = [];
+    for (const entry of this.tools.values()) {
+      if (!reach.has(entry.tool.name)) continue;
+      errors.push(...validateRegistration(entry.tool, personality));
+    }
+    return errors;
+  }
   registerAll(tools) {
     for (const tool of tools) {
       this.register(tool);
@@ -406,7 +1053,7 @@ var DefaultToolRegistry = class {
     );
     const filtered = entries.filter((e) => {
       const isMcpOrPluginTool = e.tool.name.startsWith("mcp__") || e.pluginId !== void 0;
-      if (!isMcpOrPluginTool && !e.tool.alwaysInclude && allowedTools && allowedTools.length > 0 && !allowedTools.includes(e.tool.name))
+      if (!isMcpOrPluginTool && !e.tool.alwaysInclude && allowedTools && !allowedTools.includes(e.tool.name))
         return false;
       return passesFilter(e, filterOpts);
     });
@@ -431,7 +1078,7 @@ var DefaultToolRegistry = class {
       const isPlugin = entry.pluginId !== void 0;
       if (!isMcp && !isPlugin) {
         const toolset = personality.toolset;
-        if (!toolset || toolset.length === 0 || toolset.includes(name)) {
+        if (!toolset || toolset.includes(name)) {
           reach.add(name);
         }
       } else if (isMcp) {
@@ -452,7 +1099,7 @@ var DefaultToolRegistry = class {
   // Runs all tool calls in parallel. Results are returned in input order.
   // Budget is split evenly across parallel calls; each result is post-trimmed to budget.
   // allowedTools + filterOpts enforce tool access at execution time (belt-and-suspenders).
-  async executeParallel(calls, ctx, allowedTools, filterOpts) {
+  async executeParallel(calls, ctx, allowedTools, filterOpts, turnAttachments) {
     const perCallBudget = Math.floor(ctx.resultBudgetChars / Math.max(calls.length, 1));
     const results = await Promise.allSettled(
       calls.map(async (call) => {
@@ -469,7 +1116,7 @@ var DefaultToolRegistry = class {
           };
         }
         const isMcpOrPluginTool = call.name.startsWith("mcp__") || entry.pluginId !== void 0;
-        if (!isMcpOrPluginTool && allowedTools && allowedTools.length > 0 && !allowedTools.includes(call.name)) {
+        if (!isMcpOrPluginTool && allowedTools && !allowedTools.includes(call.name)) {
           return {
             toolCallId: call.toolCallId,
             name: call.name,
@@ -502,9 +1149,29 @@ var DefaultToolRegistry = class {
             }
           };
         }
+        if (needsBackends(entry.tool.capabilities) && !this.backends) {
+          return {
+            toolCallId: call.toolCallId,
+            name: call.name,
+            result: {
+              ok: false,
+              error: `Tool ${call.name} declares capabilities but no capability backends are configured`,
+              code: "not_available"
+            }
+          };
+        }
         const budget = Math.min(perCallBudget, entry.tool.maxResultChars ?? perCallBudget);
         const toolCtx = { ...ctx, resultBudgetChars: budget };
         try {
+          if (needsBackends(entry.tool.capabilities) && this.backends) {
+            const resolved = resolveCapabilities(
+              entry.tool.name,
+              entry.tool.capabilities,
+              { sessionId: ctx.sessionId, personalityId: ctx.personalityId },
+              { ...this.backends, inboundAttachments: turnAttachments }
+            );
+            Object.assign(toolCtx, resolved);
+          }
           const result = await entry.tool.execute(call.args, toolCtx);
           if (result.ok && result.value.length > budget) {
             return {
@@ -548,6 +1215,21 @@ var DefaultToolRegistry = class {
 };
 
 // src/agent-loop.ts
+var KNOWN_AGENT_EVENT_TYPES = [
+  "text_delta",
+  "thinking_delta",
+  "tool_start",
+  "tool_progress",
+  "tool_end",
+  "usage",
+  "error",
+  "done",
+  "context_meta",
+  "run_start"
+];
+function isKnownAgentEvent(event) {
+  return KNOWN_AGENT_EVENT_TYPES.includes(event.type);
+}
 var AgentLoop = class {
   llm;
   tools;
@@ -570,10 +1252,23 @@ var AgentLoop = class {
   maxIdenticalToolCalls;
   streamingTimeoutMs;
   modelRouting;
+  memoryProviders;
   storage;
   dataDir;
+  observability;
+  injectionClassifier;
+  watcher;
+  contextEngines;
+  /** Bridge for the `clarify` tool; undefined when no interactive surface is wired. */
+  clarifyBridge;
+  /** Optional request dump store for full LLM request/response recording. */
+  requestDumpStore;
+  /** Phase 3 — team id stamped onto ToolContext when loop runs inside a team. */
+  teamId;
   /** Per-session accumulated spend in USD. Keyed by sessionKey. Reset via resetSessionCost(). */
   sessionCosts = /* @__PURE__ */ new Map();
+  /** FW-28 — per-session mtime registry. Keyed by sessionKey → (absPath → record). */
+  sessionReadMtimes = /* @__PURE__ */ new Map();
   constructor(config) {
     this.llm = config.llm;
     this.tools = config.tools ?? new DefaultToolRegistry();
@@ -592,8 +1287,24 @@ var AgentLoop = class {
     this.maxIdenticalToolCalls = config.options?.maxIdenticalToolCalls ?? 5;
     this.streamingTimeoutMs = config.options?.streamingTimeoutMs ?? 12e4;
     this.modelRouting = config.modelRouting ?? {};
+    this.memoryProviders = config.memoryProviders ?? /* @__PURE__ */ new Map();
     if (config.storage) this.storage = config.storage;
     if (config.dataDir) this.dataDir = config.dataDir;
+    if (config.observability) this.observability = config.observability;
+    if (config.teamId) this.teamId = config.teamId;
+    if (config.injectionClassifier) this.injectionClassifier = config.injectionClassifier;
+    if (config.watcher) this.watcher = config.watcher;
+    if (config.clarifyBridge) this.clarifyBridge = config.clarifyBridge;
+    if (config.requestDumpStore) this.requestDumpStore = config.requestDumpStore;
+    this.contextEngines = config.contextEngines ?? new DefaultContextEngineRegistry();
+  }
+  /**
+   * Resolve a pending clarify request — called by an interactive surface when
+   * the user answers or cancels. No-op when no clarify bridge is wired or the
+   * request id is unknown (already resolved / timed out).
+   */
+  async respondToClarify(response) {
+    await this.clarifyBridge?.respond(response);
   }
   /** Returns all available tools for inventory display (e.g. TUI splash screen). */
   getAvailableTools() {
@@ -616,6 +1327,20 @@ var AgentLoop = class {
   resetSessionCost(sessionKey) {
     this.sessionCosts.delete(sessionKey);
   }
+  /**
+   * Resolve the effective model for an LLM call, respecting tier config.
+   * Returns the model string to pass as modelOverride, and the tier name used.
+   */
+  resolveModelWithTier(personality, tier) {
+    const personalityOverride = this.modelRouting[personality.id];
+    if (personalityOverride) return { model: personalityOverride, source: "personality" };
+    const modelConfig = personality.model;
+    if (modelConfig && typeof modelConfig === "object" && personality.provider === this.llm.name) {
+      const tierModel = modelConfig[tier] ?? modelConfig.default;
+      if (tierModel) return { model: tierModel, source: "personality" };
+    }
+    return { model: this.llm.model, source: "global" };
+  }
   async *run(text, opts = {}) {
     const abortSignal = opts.abortSignal ?? new AbortController().signal;
     const sessionKey = opts.sessionKey ?? `${this.platform}:default`;
@@ -638,8 +1363,16 @@ var AgentLoop = class {
     });
     const sessionId = ethosSession.id;
     const personality = (opts.personalityId ? this.personalities.get(opts.personalityId) : null) ?? this.personalities.getDefault();
+    const obsConfig = personality?.safety?.observability;
+    const traceId = this.observability?.startTurnTrace({
+      sessionId,
+      personalityId: personality?.id,
+      obsConfig
+    });
     const currentSpend = this.sessionCosts.get(sessionKey) ?? 0;
     if (personality.budgetCapUsd != null && currentSpend >= personality.budgetCapUsd) {
+      if (traceId) this.observability?.endTrace(traceId, "error");
+      this.observability?.flush();
       yield {
         type: "error",
         error: `Budget cap of $${personality.budgetCapUsd.toFixed(2)} exceeded for this session ($${currentSpend.toFixed(4)} spent). Use /budget reset to start a new budget window.`,
@@ -648,16 +1381,30 @@ var AgentLoop = class {
       yield { type: "done", text: "", turnCount: 0 };
       return;
     }
-    const personalityOverride = this.modelRouting[personality.id];
-    const effectiveModel = personalityOverride ?? this.llm.model;
+    const { turnNumber, lastCompactionTurn } = await this.session.recordTurnStart(sessionId);
+    const turnTierOverride = opts.tierOverride;
+    if (turnTierOverride) {
+      this.observability?.recordTierOverride({
+        traceId: traceId ?? "",
+        actor: "user",
+        tier: turnTierOverride,
+        personalityId: personality.id
+      });
+    }
+    const activeTier = turnTierOverride ?? "default";
+    let pendingTierEscalation;
+    const { model: effectiveModel, source: modelSource } = this.resolveModelWithTier(
+      personality,
+      activeTier
+    );
     const modelOverride = effectiveModel !== this.llm.model ? effectiveModel : void 0;
     yield {
       type: "run_start",
       provider: this.llm.name,
       model: effectiveModel,
-      source: personalityOverride ? "personality" : "global"
+      source: modelSource
     };
-    const allowedTools = personality.toolset?.length ? personality.toolset : void 0;
+    const allowedTools = personality.toolset ?? void 0;
     const allowedPlugins = personality.plugins ?? [];
     const filterOpts = {
       allowedMcpServers: personality.mcp_servers ?? [],
@@ -673,22 +1420,34 @@ var AgentLoop = class {
       },
       allowedPlugins
     );
+    const attachmentAnnotation = buildAttachmentAnnotation(opts.attachments ?? []);
+    const annotatedText = attachmentAnnotation ? `${attachmentAnnotation}
+${text}` : text;
     await this.session.appendMessage({
       sessionId,
       role: "user",
-      content: text
+      content: annotatedText
     });
     const allMessages = await this.session.getMessages(sessionId, { limit: this.historyLimit });
     const history = allMessages.filter((m) => m.role !== "system");
-    const memCtx = await this.memory.prefetch({
+    const activeMemory = personality.memory?.provider ? await this.memoryProviders.get(personality.memory.provider)?.(
+      personality.memory.options
+    ) ?? this.memory : this.memory;
+    const memScopeId = personality.memoryScope === "per-personality" ? `personality:${personality.id}` : "global";
+    const memCtx = {
+      scopeId: memScopeId,
       sessionId,
       sessionKey,
       platform: this.platform,
-      workingDir: this.workingDir,
-      personalityId: personality.id,
-      memoryScope: personality.memoryScope,
-      query: text
-    });
+      workingDir: this.workingDir
+    };
+    let memSnapshot = await activeMemory.prefetch(memCtx);
+    if (!memSnapshot && text.trim()) {
+      const hits = await activeMemory.search(text, memCtx, { limit: 5 });
+      if (hits.length > 0) {
+        memSnapshot = { entries: hits.map((h) => ({ key: h.key, content: h.content })) };
+      }
+    }
     const promptCtx = {
       sessionId,
       sessionKey,
@@ -701,6 +1460,10 @@ var AgentLoop = class {
       personalityId: personality.id
     };
     const systemParts = [];
+    const injectionDefenseEnabled = personality.safety?.injectionDefense?.enabled !== false;
+    if (injectionDefenseEnabled) {
+      systemParts.push(INJECTION_DEFENSE_PRELUDE);
+    }
     if (personality.ethosFile && this.storage) {
       const identity = await this.storage.read(personality.ethosFile);
       if (identity) systemParts.push(identity.trim());
@@ -721,10 +1484,34 @@ var AgentLoop = class {
     if (promptCtx.meta && Object.keys(promptCtx.meta).length > 0) {
       yield { type: "context_meta", data: promptCtx.meta };
     }
-    if (memCtx) {
-      systemParts.push(`## Memory
+    if (memSnapshot && memSnapshot.entries.length > 0) {
+      const blocks = [];
+      const orderHints = {
+        "USER.md": "About You",
+        "MEMORY.md": "Memory"
+      };
+      const sorted = [...memSnapshot.entries].sort((a, b) => {
+        const rank = (k) => k === "USER.md" ? 0 : k === "MEMORY.md" ? 1 : 2;
+        return rank(a.key) - rank(b.key);
+      });
+      for (const e of sorted) {
+        const heading = orderHints[e.key] ?? e.key;
+        blocks.push(`## ${heading}
+
+${e.content.trim()}`);
+      }
+      if (blocks.length > 0) {
+        let rendered = `## Memory
 
-${memCtx.content}`);
+${blocks.join("\n\n")}`;
+        const MEMORY_MAX_CHARS = 2e4;
+        if (rendered.length > MEMORY_MAX_CHARS) {
+          rendered = `[...truncated]
+
+${rendered.slice(-MEMORY_MAX_CHARS)}`;
+        }
+        systemParts.push(rendered);
+      }
     }
     const buildResult = await this.hooks.fireModifying(
       "before_prompt_build",
@@ -743,16 +1530,74 @@ ${memCtx.content}`);
       if (buildResult.appendSystem) systemParts.push(buildResult.appendSystem);
     }
     const systemPrompt = systemParts.join("\n\n").trim() || void 0;
-    const llmMessages = this.toLLMMessages(history);
+    let llmMessages = this.toLLMMessages(this.dedupHistory(history));
+    const compacted = await this.maybeCompact(llmMessages, systemPrompt ?? "", personality, {
+      sessionId,
+      sessionKey,
+      turnNumber,
+      lastCompactionTurn
+    });
+    llmMessages = compacted.messages;
+    const cacheBreakpoints = compacted.cacheBreakpoints;
+    if (compacted.notice) {
+      const n = compacted.notice;
+      const tok = n.summaryTokens > 0 ? `, ${n.summaryTokens} tok` : "";
+      yield {
+        type: "tool_progress",
+        toolName: "_compaction",
+        message: `compressed ${n.droppedCount} earlier message(s) (${n.engineName}${tok})`,
+        audience: "user"
+      };
+    }
     let fullText = "";
     let turnCount = 0;
     let totalToolCalls = 0;
+    let successfulToolCalls = 0;
     const toolNameCounts = /* @__PURE__ */ new Map();
+    const dgConfig = personality.safety?.injectionDefense?.postReadDowngrade;
+    const dgEnabled = injectionDefenseEnabled && dgConfig?.enabled !== false;
+    const dgTurns = dgConfig?.turns ?? 2;
+    const dgTools = resolveDowngradedTools(dgConfig?.tools);
+    let dgRemaining = 0;
+    this.watcher?.resetTurn();
+    let watcherHaltState = null;
+    const observe = (event) => {
+      if (!this.watcher) return;
+      const d = this.watcher.observe(event);
+      if (d.action !== "allow") watcherHaltState = d;
+    };
+    const getHalt = () => watcherHaltState;
     for (let iteration = 0; iteration < this.maxIterations; iteration++) {
       if (abortSignal.aborted) {
         yield { type: "error", error: "Aborted", code: "aborted" };
+        if (traceId) {
+          this.observability?.endTrace(traceId, "aborted");
+          this.observability?.flush();
+        }
         return;
       }
+      const halt = getHalt();
+      if (halt) {
+        if (halt.action === "terminate") {
+          yield {
+            type: "error",
+            error: `Watcher: ${halt.reason}`,
+            code: `watcher_${halt.rule}`
+          };
+          if (traceId) {
+            this.observability?.endTrace(traceId, "aborted");
+            this.observability?.flush();
+          }
+          return;
+        }
+        yield {
+          type: "tool_progress",
+          toolName: "_watcher",
+          message: `\u26A0 ${halt.rule}: ${halt.reason}`,
+          audience: "user"
+        };
+        break;
+      }
       if (totalToolCalls >= this.maxToolCallsPerTurn) {
         yield {
           type: "tool_progress",
@@ -774,12 +1619,17 @@ ${memCtx.content}`);
         };
         break;
       }
+      const toolDefs = this.tools.toDefinitions(allowedTools, filterOpts);
+      const requestId = randomUUID();
+      const includeContent = obsConfig?.storeLlmPayloads === "full";
       await this.hooks.fireVoid(
         "before_llm_call",
         {
           sessionId,
           model: this.llm.model,
-          turnNumber: turnCount
+          turnNumber: turnCount,
+          requestId,
+          ...includeContent ? { system: systemPrompt, tools: toolDefs, messages: llmMessages } : {}
         },
         allowedPlugins
       );
@@ -797,22 +1647,53 @@ ${memCtx.content}`);
         if (watchdogTimer) clearTimeout(watchdogTimer);
         watchdogTimer = void 0;
       };
+      let iterModelOverride = modelOverride;
+      if (pendingTierEscalation && typeof personality.model === "object") {
+        const tier = pendingTierEscalation;
+        pendingTierEscalation = void 0;
+        const { model: tierModel } = this.resolveModelWithTier(personality, tier);
+        iterModelOverride = tierModel !== this.llm.model ? tierModel : void 0;
+        this.observability?.recordTierEscalation({
+          traceId: traceId ?? "",
+          from: activeTier,
+          to: tier,
+          reason: "tool_escalation",
+          personalityId: personality.id
+        });
+      }
+      const llmSpanId = this.observability?.startSpan({
+        traceId: traceId ?? "",
+        kind: "llm_call",
+        name: iterModelOverride ?? this.llm.model ?? "unknown"
+      });
+      let llmInputTokens = 0;
+      let llmOutputTokens = 0;
+      let llmCacheReadTokens = 0;
+      let llmCacheCreationTokens = 0;
+      let llmEstimatedCostUsd = 0;
+      let llmRequestTokens;
+      let llmFinishReason;
+      const llmStartTs = Date.now();
       try {
         armWatchdog();
-        const stream = this.llm.complete(
-          llmMessages,
-          this.tools.toDefinitions(allowedTools, filterOpts),
-          {
-            system: systemPrompt,
-            cacheSystemPrompt: true,
-            abortSignal: combinedSignal,
-            ...modelOverride ? { modelOverride } : {}
-          }
-        );
+        const stream = this.llm.complete(llmMessages, toolDefs, {
+          system: systemPrompt,
+          cacheSystemPrompt: true,
+          abortSignal: combinedSignal,
+          ...iterModelOverride ? { modelOverride: iterModelOverride } : {},
+          ...cacheBreakpoints ? { cacheBreakpoints } : {}
+        });
         for await (const chunk of stream) {
           if (abortSignal.aborted) break;
           if (watchdogController.signal.aborted) break;
           armWatchdog();
+          if (chunk.type === "done") llmFinishReason = chunk.finishReason;
+          if (chunk.type === "usage") {
+            llmCacheReadTokens += chunk.usage.cacheReadTokens;
+            llmCacheCreationTokens += chunk.usage.cacheCreationTokens;
+            llmEstimatedCostUsd += chunk.usage.estimatedCostUsd;
+            if (chunk.usage.requestTokens) llmRequestTokens = chunk.usage.requestTokens;
+          }
           for (const event of this.handleChunk(chunk, pendingToolCalls, (t) => {
             chunkText += t;
             fullText += t;
@@ -822,12 +1703,25 @@ ${memCtx.content}`);
                 sessionKey,
                 (this.sessionCosts.get(sessionKey) ?? 0) + event.estimatedCostUsd
               );
+              llmInputTokens += event.inputTokens;
+              llmOutputTokens += event.outputTokens;
+              observe({
+                type: "usage",
+                inputTokens: event.inputTokens,
+                outputTokens: event.outputTokens
+              });
             }
             yield event;
           }
         }
         disarmWatchdog();
+        this.observability?.endSpan(llmSpanId ?? "", "ok", {
+          inputTokens: llmInputTokens,
+          outputTokens: llmOutputTokens
+        });
         if (watchdogController.signal.aborted && !abortSignal.aborted) {
+          this.observability?.endTrace(traceId ?? "", "error");
+          this.observability?.flush();
           yield {
             type: "error",
             error: `LLM stream stalled \u2014 no chunk for ${watchdogMs}ms`,
@@ -837,7 +1731,10 @@ ${memCtx.content}`);
         }
       } catch (err) {
         disarmWatchdog();
+        this.observability?.endSpan(llmSpanId ?? "", "error");
         if (watchdogController.signal.aborted && !abortSignal.aborted) {
+          this.observability?.endTrace(traceId ?? "", "error");
+          this.observability?.flush();
           yield {
             type: "error",
             error: `LLM stream stalled \u2014 no chunk for ${watchdogMs}ms`,
@@ -846,6 +1743,8 @@ ${memCtx.content}`);
           return;
         }
         const msg = err instanceof Error ? err.message : String(err);
+        this.observability?.endTrace(traceId ?? "", "error");
+        this.observability?.flush();
         yield { type: "error", error: msg, code: "llm_error" };
         return;
       }
@@ -867,15 +1766,50 @@ ${memCtx.content}`);
           }))
         }
       });
+      const llmDurationMs = Date.now() - llmStartTs;
       await this.hooks.fireVoid(
         "after_llm_call",
         {
           sessionId,
           text: chunkText,
-          usage: { inputTokens: 0, outputTokens: 0 }
+          usage: {
+            inputTokens: llmInputTokens,
+            outputTokens: llmOutputTokens,
+            ...llmCacheReadTokens ? { cacheReadTokens: llmCacheReadTokens } : {},
+            ...llmCacheCreationTokens ? { cacheCreationTokens: llmCacheCreationTokens } : {},
+            ...llmEstimatedCostUsd ? { estimatedCostUsd: llmEstimatedCostUsd } : {},
+            ...llmRequestTokens ? { requestTokens: llmRequestTokens } : {}
+          },
+          requestId,
+          finishReason: llmFinishReason,
+          durationMs: llmDurationMs,
+          ...includeContent ? { system: systemPrompt, tools: toolDefs, messages: llmMessages } : {}
         },
         allowedPlugins
       );
+      if (this.requestDumpStore) {
+        await this.requestDumpStore.append({
+          requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          sessionId,
+          personalityId: personality.id,
+          turnNumber: turnCount,
+          model: iterModelOverride ?? this.llm.model,
+          durationMs: llmDurationMs,
+          requestTokens: llmRequestTokens,
+          responseTokens: llmOutputTokens || void 0,
+          cacheReadTokens: llmCacheReadTokens || void 0,
+          cacheCreationTokens: llmCacheCreationTokens || void 0,
+          estimatedCostUsd: llmEstimatedCostUsd || void 0,
+          finishReason: llmFinishReason,
+          ...includeContent ? {
+            system: systemPrompt,
+            tools: toolDefs,
+            messages: llmMessages,
+            responseText: chunkText
+          } : {}
+        });
+      }
       if (completedToolCalls.length > 0) {
         const assistantContent = [];
         if (chunkText) assistantContent.push({ type: "text", text: chunkText });
@@ -894,6 +1828,11 @@ ${memCtx.content}`);
       }
       const progressBuffer = [];
       const scopedStorage = this.buildScopedStorage(personality);
+      let sessionMtimes = this.sessionReadMtimes.get(sessionKey);
+      if (!sessionMtimes) {
+        sessionMtimes = /* @__PURE__ */ new Map();
+        this.sessionReadMtimes.set(sessionKey, sessionMtimes);
+      }
       const toolCtxBase = {
         sessionId,
         sessionKey,
@@ -902,6 +1841,8 @@ ${memCtx.content}`);
         agentId: opts.agentId,
         personalityId: personality.id,
         memoryScope: personality.memoryScope,
+        memoryScopeId: memScopeId,
+        ...this.teamId !== void 0 && { teamId: this.teamId },
         currentTurn: turnCount,
         messageCount: allMessages.length + turnCount,
         abortSignal,
@@ -914,10 +1855,36 @@ ${memCtx.content}`);
           });
         },
         resultBudgetChars: this.resultBudgetChars,
-        ...scopedStorage ? { storage: scopedStorage } : {}
+        readMtimes: sessionMtimes,
+        ...scopedStorage ? { storage: scopedStorage } : {},
+        ...personality.safety?.network ? { networkPolicy: personality.safety.network } : {}
       };
       const prepped = [];
+      const spanIds = /* @__PURE__ */ new Map();
       for (const tc of completedToolCalls) {
+        if (dgEnabled && dgRemaining > 0 && dgTools.has(tc.toolName)) {
+          this.observability?.recordSafetyBlock({
+            traceId,
+            code: "tool_downgraded_post_untrusted_read",
+            cause: tc.toolName
+          });
+          observe({ type: "tool_end", toolName: tc.toolName, ok: false });
+          yield {
+            type: "tool_end",
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            ok: false,
+            durationMs: 0,
+            result: DOWNGRADE_REJECTION_MESSAGE
+          };
+          prepped.push({
+            toolCallId: tc.toolCallId,
+            name: tc.toolName,
+            args: tc.args,
+            rejected: DOWNGRADE_REJECTION_MESSAGE
+          });
+          continue;
+        }
         const beforeResult = await this.hooks.fireModifying(
           "before_tool_call",
           {
@@ -929,6 +1896,12 @@ ${memCtx.content}`);
           allowedPlugins
         );
         if (beforeResult.error) {
+          this.observability?.recordSafetyBlock({
+            traceId,
+            code: "tool_blocked",
+            cause: beforeResult.error
+          });
+          observe({ type: "tool_end", toolName: tc.toolName, ok: false });
           yield {
             type: "tool_end",
             toolCallId: tc.toolCallId,
@@ -946,6 +1919,15 @@ ${memCtx.content}`);
           continue;
         }
         const effectiveArgs = beforeResult.args ?? tc.args;
+        const spanId = this.observability?.startSpan({
+          traceId: traceId ?? "",
+          kind: "tool_call",
+          name: tc.toolName,
+          attrs: { args: JSON.stringify(effectiveArgs).slice(0, 4096) },
+          obsConfig
+        });
+        spanIds.set(tc.toolCallId, spanId ?? "");
+        observe({ type: "tool_start", toolName: tc.toolName, args: effectiveArgs });
         yield {
           type: "tool_start",
           toolCallId: tc.toolCallId,
@@ -954,20 +1936,45 @@ ${memCtx.content}`);
         };
         prepped.push({ toolCallId: tc.toolCallId, name: tc.toolName, args: effectiveArgs });
       }
+      const haltDuringBatch = getHalt();
+      if (haltDuringBatch) {
+        for (const p of prepped) {
+          if (p.rejected === void 0) {
+            p.rejected = `Watcher halted before execution: ${haltDuringBatch.reason}`;
+          }
+        }
+      }
       const execInputs = prepped.filter((p) => p.rejected === void 0).map((p) => ({ toolCallId: p.toolCallId, name: p.name, args: p.args }));
       const startedAt = Date.now();
-      const execResults = execInputs.length > 0 ? await this.tools.executeParallel(execInputs, toolCtxBase, allowedTools, filterOpts) : [];
+      const execResults = execInputs.length > 0 ? await this.tools.executeParallel(
+        execInputs,
+        toolCtxBase,
+        allowedTools,
+        filterOpts,
+        opts.attachments
+      ) : [];
       const execResultMap = new Map(execResults.map((r) => [r.toolCallId, r]));
+      if (typeof personality.model === "object" && personality.provider === this.llm.name) {
+        for (const r of execResults) {
+          if (r.name === "think_deeper" && r.result.ok) {
+            pendingTierEscalation = "deep";
+            break;
+          }
+        }
+      }
       for (const ev of progressBuffer) {
         yield { type: "tool_progress", ...ev };
       }
       progressBuffer.length = 0;
       const toolResultContent = [];
+      let untrustedReadThisIteration = false;
       for (const p of prepped) {
         const durationMs = Date.now() - startedAt;
         let result;
+        let llmContent;
         if (p.rejected !== void 0) {
           result = { ok: false, error: p.rejected, code: "execution_failed" };
+          llmContent = p.rejected;
         } else {
           const execResult = execResultMap.get(p.toolCallId);
           result = execResult?.result ?? {
@@ -975,6 +1982,15 @@ ${memCtx.content}`);
             error: "Tool result missing",
             code: "execution_failed"
           };
+          const sid = spanIds.get(p.toolCallId);
+          if (sid) {
+            this.observability?.endSpan(sid, result.ok ? "ok" : "error", {
+              result_size_bytes: result.ok ? result.value.length : void 0,
+              durationMs
+            });
+          }
+          observe({ type: "tool_end", toolName: p.name, ok: result.ok });
+          if (result.ok) successfulToolCalls++;
           yield {
             type: "tool_end",
             toolCallId: p.toolCallId,
@@ -983,6 +1999,18 @@ ${memCtx.content}`);
             durationMs,
             result: result.ok ? result.value : result.error
           };
+          if (result.ok && result.cost_usd) {
+            this.sessionCosts.set(
+              sessionKey,
+              (this.sessionCosts.get(sessionKey) ?? 0) + result.cost_usd
+            );
+            yield {
+              type: "usage",
+              inputTokens: 0,
+              outputTokens: 0,
+              estimatedCostUsd: result.cost_usd
+            };
+          }
           await this.hooks.fireVoid(
             "after_tool_call",
             {
@@ -993,29 +2021,97 @@ ${memCtx.content}`);
             },
             allowedPlugins
           );
+          const touchedPath = extractFilePath(p.args);
+          if (touchedPath !== void 0) {
+            await this.hooks.fireVoid(
+              "tool_end_with_path",
+              {
+                sessionId,
+                personalityId: personality.id,
+                toolName: p.name,
+                filePath: touchedPath,
+                workingDir: this.workingDir
+              },
+              allowedPlugins
+            );
+          }
+          llmContent = result.ok ? result.value : result.error;
+          if (injectionDefenseEnabled && result.ok) {
+            const tool = this.tools.get(p.name);
+            if (tool?.outputIsUntrusted) {
+              const verdict = await this.handleUntrustedResult(
+                p.name,
+                p.args,
+                result.value,
+                personality,
+                traceId
+              );
+              llmContent = verdict.wrappedContent;
+              if (verdict.containsInstructions) {
+                this.observability?.recordSafetyBlock({
+                  traceId,
+                  code: "injection_detected",
+                  cause: verdict.reason ?? "pattern-hit"
+                });
+                yield {
+                  type: "tool_progress",
+                  toolName: p.name,
+                  message: `\u26A0 external content may contain instructions${verdict.reason ? ` (${verdict.reason})` : ""}`,
+                  audience: "user"
+                };
+              }
+              untrustedReadThisIteration = true;
+            }
+          }
         }
         await this.session.appendMessage({
           sessionId,
           role: "tool_result",
-          content: result.ok ? result.value : result.error,
+          content: llmContent,
           toolCallId: p.toolCallId,
           toolName: p.name
         });
         toolResultContent.push({
           type: "tool_result",
           tool_use_id: p.toolCallId,
-          content: result.ok ? result.value : result.error,
+          content: llmContent,
           is_error: !result.ok
         });
       }
+      if (dgRemaining > 0) dgRemaining--;
+      if (dgEnabled && untrustedReadThisIteration) {
+        dgRemaining = dgTurns;
+      }
+      if (opts.steerSink) {
+        const steers = opts.steerSink.drain();
+        for (const steerText of steers) {
+          toolResultContent.push({ type: "text", text: `[USER STEER]: ${steerText}` });
+          await this.session.appendMessage({
+            sessionId,
+            role: "user_steer",
+            content: steerText
+          });
+        }
+      }
       llmMessages.push({ role: "user", content: toolResultContent });
     }
     await this.session.updateUsage(sessionId, { apiCallCount: turnCount });
     await this.hooks.fireVoid(
       "agent_done",
-      { sessionId, text: fullText, turnCount },
+      {
+        sessionId,
+        text: fullText,
+        turnCount,
+        personalityId: personality.id,
+        successfulToolCalls,
+        totalToolCalls,
+        toolNames: [...toolNameCounts.keys()],
+        initialPrompt: text
+      },
       allowedPlugins
     );
+    if (traceId) this.observability?.endTrace(traceId, "ok");
+    this.observability?.flush();
     yield { type: "done", text: fullText, turnCount };
   }
   *handleChunk(chunk, pendingToolCalls, onText) {
@@ -1062,6 +2158,53 @@ ${memCtx.content}`);
         break;
     }
   }
+  // Q1 — tool-result dedup. A coordinator that re-reads the same file across
+  // turns stores one tool_result per read; over a long session that is pure
+  // token waste. Before building the LLM-facing history, collapse exact-
+  // duplicate tool results — same tool, same args, same output — keeping the
+  // FIRST (oldest) copy intact and replacing later ones with a placeholder
+  // that points BACKWARD at it. Pointing backward preserves causality: the
+  // assistant turn that followed a later read can still see the content
+  // earlier in the transcript. The tool_result row stays attached to its
+  // tool_use (Anthropic contract); only the content string changes.
+  dedupHistory(history) {
+    const argsByToolCallId = /* @__PURE__ */ new Map();
+    for (const msg of history) {
+      if (msg.role === "assistant" && msg.toolCalls) {
+        for (const tc of msg.toolCalls) {
+          argsByToolCallId.set(tc.id, JSON.stringify(tc.input ?? null));
+        }
+      }
+    }
+    const occurrences = /* @__PURE__ */ new Map();
+    history.forEach((msg, idx) => {
+      if (msg.role !== "tool_result") return;
+      const toolName = msg.toolName ?? "";
+      const argsHash = msg.toolCallId ? argsByToolCallId.get(msg.toolCallId) ?? "" : "";
+      const fingerprint = createHash3("sha256").update(`${toolName}\0${argsHash}\0${msg.content.trim()}`).digest("hex");
+      const list = occurrences.get(fingerprint);
+      if (list) list.push(idx);
+      else occurrences.set(fingerprint, [idx]);
+    });
+    const replacement = /* @__PURE__ */ new Map();
+    for (const indices of occurrences.values()) {
+      if (indices.length < 2) continue;
+      const oldest = indices[0];
+      if (oldest === void 0) continue;
+      const oldestId = history[oldest]?.toolCallId ?? String(oldest);
+      for (const idx of indices.slice(1)) {
+        replacement.set(
+          idx,
+          `[deduped \u2014 identical to earlier result, see tool_use id ${oldestId}]`
+        );
+      }
+    }
+    if (replacement.size === 0) return history;
+    return history.map((msg, idx) => {
+      const placeholder = replacement.get(idx);
+      return placeholder !== void 0 ? { ...msg, content: placeholder } : msg;
+    });
+  }
   // Reconstruct LLM-ready messages from stored history.
   // Assistant messages with tool calls produce proper tool_use content blocks.
   // Consecutive tool_result rows are grouped into a single user message.
@@ -1095,6 +2238,7 @@ ${memCtx.content}`);
         } else {
           messages.push({ role: "user", content: [resultBlock] });
         }
+      } else if (msg.role === "user_steer") {
       }
     }
     return messages;
@@ -1110,21 +2254,637 @@ ${memCtx.content}`);
   //   read:  [<ethosHome>/personalities/<self>/, <ethosHome>/skills/, <cwd>]
   //   write: [<ethosHome>/personalities/<self>/, <cwd>]
   // ---------------------------------------------------------------------------
+  // ---------------------------------------------------------------------------
+  // Ch.3a + 3c — provenance wrap + injection classification
+  // ---------------------------------------------------------------------------
+  //
+  // Returns the wrapped content (always — wrap is the floor) plus whether
+  // any defense layer flagged the payload. Tier-1 is always evaluated;
+  // Tier-2 (LLM classifier) fires when Tier-1 hit, content is > 500 chars,
+  // or `injectionDefense.classifier.alwaysCallLLM` is true.
+  async handleUntrustedResult(toolName, args, rawValue, personality, traceId) {
+    const source = describeSource(toolName, args);
+    const wrapped = wrapUntrusted({
+      content: rawValue,
+      toolName,
+      ...source ? { source } : {}
+    });
+    const tier1 = shortPatternCheck(rawValue);
+    const tier1Hit = tier1.containsInstructions || wrapped.strippedTokens > 0;
+    const classifierConfig = personality.safety?.injectionDefense?.classifier;
+    const shouldCallLLM = this.injectionClassifier !== void 0 && (classifierConfig?.alwaysCallLLM === true || tier1Hit || rawValue.length > 500);
+    let verdict = null;
+    if (shouldCallLLM && this.injectionClassifier) {
+      try {
+        verdict = await this.injectionClassifier({ content: rawValue });
+      } catch (err) {
+        this.observability?.recordSafetyBlock({
+          traceId,
+          code: "injection_classifier_failed",
+          cause: err instanceof Error ? err.message : String(err)
+        });
+        verdict = null;
+      }
+    }
+    const containsInstructions = tier1Hit || (verdict?.containsInstructions ?? false);
+    const reason = tier1Hit ? wrapped.strippedTokens > 0 ? `stripped ${wrapped.strippedTokens} template token${wrapped.strippedTokens === 1 ? "" : "s"}` : tier1.hits[0]?.rule ?? "pattern-hit" : verdict?.reason;
+    return {
+      wrappedContent: wrapped.content,
+      containsInstructions,
+      ...reason ? { reason } : {}
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // E4 — pre-LLM compaction. Resolves the personality's context engine and
+  // calls into it when estimated context usage exceeds the pressure
+  // threshold (80% of the model's window). When the personality declares no
+  // engine, we still resolve to `drop_oldest` — but the engine is only
+  // *invoked* when there is real pressure, so static configs see no change.
+  // ---------------------------------------------------------------------------
+  async maybeCompact(messages, systemPrompt, personality, sessionMetadata) {
+    const window = this.llm.maxContextTokens || 2e5;
+    const target = Math.floor(window * 0.7);
+    const pressureGate = Math.floor(window * 0.8);
+    const current = estimateTokens(systemPrompt) + estimateMessagesTokens(messages);
+    if (current <= pressureGate) return { messages };
+    const cooldownTurns = 5;
+    const hardOverflowGate = Math.floor(window * 0.95);
+    const inCooldown = sessionMetadata.lastCompactionTurn > 0 && sessionMetadata.turnNumber - sessionMetadata.lastCompactionTurn < cooldownTurns;
+    if (inCooldown && current <= hardOverflowGate) {
+      return { messages };
+    }
+    const engineName = personality.context_engine ?? "drop_oldest";
+    const engine = this.contextEngines.get(engineName) ?? this.contextEngines.get("drop_oldest");
+    if (!engine) return { messages };
+    try {
+      const startedAt = Date.now();
+      const result = await engine.compact({
+        messages,
+        currentSystem: systemPrompt,
+        targetTokens: target,
+        personality,
+        sessionMetadata
+      });
+      const durationMs = Date.now() - startedAt;
+      this.observability?.recordCompaction({
+        code: "context_compacted",
+        cause: `${engine.name}: ${result.notes}`
+      });
+      const changed = result.messages.length !== messages.length || result.summaryText !== void 0;
+      const summaryTokens = result.summaryText ? estimateTokens(result.summaryText) : 0;
+      if (changed) {
+        try {
+          await this.session.recordCompression({
+            sessionId: sessionMetadata.sessionId,
+            engineName: engine.name,
+            originalCount: messages.length,
+            keptCount: result.messages.length,
+            ...result.summaryText !== void 0 ? { summaryText: result.summaryText } : {},
+            summaryTokens,
+            preTotalTokens: current,
+            postTotalTokens: estimateTokens(systemPrompt) + estimateMessagesTokens(result.messages),
+            durationMs
+          });
+          await this.session.updateUsage(sessionMetadata.sessionId, { compactionCount: 1 });
+          await this.session.recordCompactionTurn(
+            sessionMetadata.sessionId,
+            sessionMetadata.turnNumber
+          );
+        } catch (persistErr) {
+          this.observability?.recordCompaction({
+            severity: "warn",
+            code: "compaction_persist_failed",
+            cause: persistErr instanceof Error ? persistErr.message : String(persistErr)
+          });
+        }
+      }
+      return {
+        messages: result.messages,
+        ...changed && result.cacheBreakpoints ? { cacheBreakpoints: result.cacheBreakpoints } : {},
+        ...changed ? {
+          notice: {
+            engineName: engine.name,
+            droppedCount: messages.length - result.messages.length,
+            summaryTokens
+          }
+        } : {}
+      };
+    } catch (err) {
+      this.observability?.recordCompaction({
+        severity: "warn",
+        code: "context_engine_failed",
+        cause: err instanceof Error ? err.message : String(err)
+      });
+      return { messages };
+    }
+  }
   buildScopedStorage(personality) {
     if (!this.storage) return void 0;
-    const ethosHome = this.dataDir ?? join(homedir(), ".ethos");
+    const ethosHome = this.dataDir ?? join3(homedir2(), ".ethos");
     const cwd = this.workingDir;
     const self = personality.id;
-    const ownDir = `${join(ethosHome, "personalities", self)}/`;
+    const ownDir = `${join3(ethosHome, "personalities", self)}/`;
     const fsReach = personality.fs_reach;
-    const readPrefixes = fsReach?.read && fsReach.read.length > 0 ? fsReach.read.map((p) => substitute(p, { ethosHome, self, cwd })) : [ownDir, `${join(ethosHome, "skills")}/`, cwd];
+    const readPrefixes = fsReach?.read && fsReach.read.length > 0 ? fsReach.read.map((p) => substitute(p, { ethosHome, self, cwd })) : [ownDir, `${join3(ethosHome, "skills")}/`, cwd];
     const writePrefixes = fsReach?.write && fsReach.write.length > 0 ? fsReach.write.map((p) => substitute(p, { ethosHome, self, cwd })) : [ownDir, cwd];
-    return new ScopedStorage(this.storage, { read: readPrefixes, write: writePrefixes });
+    return new ScopedStorage(this.storage, {
+      read: readPrefixes,
+      write: writePrefixes,
+      alwaysDeny: defaultAlwaysDeny()
+    });
   }
 };
 function substitute(template, vars) {
   return template.replace(/\$\{ETHOS_HOME\}/g, vars.ethosHome).replace(/\$\{self\}/g, vars.self).replace(/\$\{CWD\}/g, vars.cwd);
 }
+function extractFilePath(args) {
+  if (!args || typeof args !== "object") return void 0;
+  const a = args;
+  if (typeof a.path === "string" && a.path.length > 0) return a.path;
+  if (typeof a.file_path === "string" && a.file_path.length > 0) return a.file_path;
+  if (typeof a.filePath === "string" && a.filePath.length > 0) return a.filePath;
+  if (typeof a.cwd === "string" && a.cwd.length > 0) return a.cwd;
+  return void 0;
+}
+function describeSource(toolName, args) {
+  if (!args || typeof args !== "object") return void 0;
+  const a = args;
+  if (typeof a.path === "string") return `${toolName === "read_file" ? "file:" : ""}${a.path}`;
+  if (typeof a.url === "string") return a.url;
+  if (typeof a.command === "string") return `cmd:${a.command}`;
+  if (typeof a.query === "string") return `query:${a.query}`;
+  return void 0;
+}
+
+// src/clarify/clarify-bridge.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var ClarifyBusyError = class extends Error {
+  code = "CLARIFY_BUSY";
+  constructor() {
+    super("Another clarify is already pending for this session");
+    this.name = "ClarifyBusyError";
+  }
+};
+var ClarifyTimedOutNoDefaultError = class extends Error {
+  code = "CLARIFY_TIMED_OUT_NO_DEFAULT";
+  constructor() {
+    super("Clarify timed out and no default was provided");
+    this.name = "ClarifyTimedOutNoDefaultError";
+  }
+};
+var ClarifyNoSurfaceError = class extends Error {
+  code = "CLARIFY_NO_SURFACE";
+  constructor() {
+    super("No interactive surface is available to present the clarify request");
+    this.name = "ClarifyNoSurfaceError";
+  }
+};
+var ClarifyBridge = class {
+  /**
+   * `store` is exposed read-only so a surface (e.g. TelegramClarifySurface)
+   * can patch `surfaceContext` after presenting the prompt and look up rows
+   * by id without proxying every call through the bridge.
+   */
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  pending = /* @__PURE__ */ new Map();
+  presenter;
+  resolvedListeners = /* @__PURE__ */ new Set();
+  /** A surface registers how it presents a pending clarify to the user. */
+  setPresenter(presenter) {
+    this.presenter = presenter;
+  }
+  /**
+   * Subscribe to clarify resolutions so a surface can tear down its prompt
+   * when the request is answered, times out, or is cancelled. Returns an
+   * unsubscribe function.
+   */
+  onResolved(listener) {
+    this.resolvedListeners.add(listener);
+    return () => this.resolvedListeners.delete(listener);
+  }
+  /** True iff a clarify is currently pending for the given session. */
+  hasPending(sessionId) {
+    for (const entry of this.pending.values()) {
+      if (entry.row.sessionId === sessionId) return true;
+    }
+    return false;
+  }
+  /** Pending rows still awaiting an answer — for SSE reconnect re-presentation. */
+  listPending(sessionId) {
+    const rows = [];
+    for (const entry of this.pending.values()) {
+      if (sessionId === void 0 || entry.row.sessionId === sessionId) rows.push(entry.row);
+    }
+    return rows;
+  }
+  /**
+   * Persisted pending rows from the store — for boot-time hydration (a surface
+   * that outlives a single process needs to find rows that survived a
+   * restart). `listPending()` only sees in-memory rows; this is the source of
+   * truth across restarts.
+   */
+  async listPersisted(filter) {
+    return this.store.list(filter);
+  }
+  /**
+   * Issue a clarify request. Resolves when the user answers, the timeout fires
+   * (with `default`), or the turn aborts (as cancelled). Rejects with
+   * `ClarifyBusyError` if one is already pending for the session, or with
+   * `ClarifyTimedOutNoDefaultError` on timeout when no `default` was given.
+   */
+  async request(input) {
+    if (!this.presenter) throw new ClarifyNoSurfaceError();
+    if (this.hasPending(input.sessionId)) throw new ClarifyBusyError();
+    const requestId = randomUUID2();
+    const createdAt = /* @__PURE__ */ new Date();
+    const deadline = new Date(createdAt.getTime() + input.timeoutMs);
+    const row = {
+      requestId,
+      sessionId: input.sessionId,
+      surfaceType: input.surfaceType,
+      surfaceContext: input.surfaceContext ?? {},
+      question: input.question,
+      ...input.options !== void 0 ? { options: input.options } : {},
+      ...input.default !== void 0 ? { default: input.default } : {},
+      answerableBy: input.answerableBy,
+      createdAt: createdAt.toISOString(),
+      defaultDeadlineAt: deadline.toISOString()
+    };
+    await this.store.add(row);
+    return new Promise((resolve4, reject) => {
+      const timer = setTimeout(() => {
+        void this.fireTimeout(requestId);
+      }, input.timeoutMs);
+      this.pending.set(requestId, { row, resolve: resolve4, reject, timer });
+      if (input.abortSignal) {
+        if (input.abortSignal.aborted) {
+          void this.respond({ requestId, answer: "", source: "cancel" });
+        } else {
+          input.abortSignal.addEventListener(
+            "abort",
+            () => void this.respond({ requestId, answer: "", source: "cancel" }),
+            { once: true }
+          );
+        }
+      }
+      Promise.resolve(this.presenter?.(row)).catch(() => {
+      });
+    });
+  }
+  /**
+   * Resolve a pending clarify. Called by a surface when the user answers or
+   * cancels, and internally on timeout. Unknown / already-resolved ids are
+   * swallowed (another surface or the timeout beat this one).
+   *
+   * Degraded-mode fallback: when no in-process entry exists but the row is
+   * still persisted (gateway crashed mid-clarify, then the user tapped the
+   * button after restart), still clear the row and notify listeners so the
+   * surface can edit its UI to the resolved state. The original `request()`
+   * promise is gone — the agent waiting on it died with the process — so
+   * the answer can't reach the LLM, but at least the visible prompt updates.
+   */
+  async respond(response) {
+    const entry = this.pending.get(response.requestId);
+    if (!entry) {
+      const persisted = await this.store.get(response.requestId);
+      if (!persisted) return;
+      await this.store.remove(response.requestId);
+      const notify = response.source === "timeout-no-default" ? null : response;
+      this.notifyResolved(persisted, notify);
+      return;
+    }
+    clearTimeout(entry.timer);
+    this.pending.delete(response.requestId);
+    await this.store.remove(response.requestId);
+    if (response.source === "timeout-no-default") {
+      entry.reject(new ClarifyTimedOutNoDefaultError());
+      this.notifyResolved(entry.row, null);
+      return;
+    }
+    entry.resolve(response);
+    this.notifyResolved(entry.row, response);
+  }
+  notifyResolved(row, response) {
+    for (const listener of this.resolvedListeners) {
+      try {
+        listener(row, response);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Restart recovery: fire timeout responses for any persisted rows that have
+   * already passed their deadline. Called on boot and on an interval by
+   * surfaces that outlive a single turn (web-api, gateway).
+   *
+   * Listeners are notified for swept rows so surfaces can edit their UI in
+   * place — a card whose prompt timed out while the process was down should
+   * still update to the "timed out" state instead of hanging on buttons.
+   */
+  async sweep(now = /* @__PURE__ */ new Date()) {
+    const expired = await this.store.expired(now);
+    for (const row of expired) {
+      if (this.pending.has(row.requestId)) continue;
+      await this.store.remove(row.requestId);
+      const source = row.default !== void 0 ? "timeout-default" : "timeout-no-default";
+      const notify = source === "timeout-default" ? { requestId: row.requestId, answer: row.default ?? "", source } : null;
+      this.notifyResolved(row, notify);
+    }
+  }
+  async fireTimeout(requestId) {
+    const entry = this.pending.get(requestId);
+    if (!entry) return;
+    const def = entry.row.default;
+    await this.respond({
+      requestId,
+      answer: def ?? "",
+      source: def !== void 0 ? "timeout-default" : "timeout-no-default"
+    });
+  }
+};
+
+// src/clarify/file-clarify-store.ts
+var FileClarifyStore = class {
+  /** `root` is the absolute `~/.ethos/clarify` directory (caller-resolved). */
+  constructor(storage, root) {
+    this.storage = storage;
+    this.root = root;
+    this.pendingPath = `${root}/pending.json`;
+  }
+  storage;
+  root;
+  pendingPath;
+  /** Serializes the read-modify-write cycle within this process. */
+  mutex = Promise.resolve();
+  async add(req) {
+    await this.mutate((rows) => {
+      const without = rows.filter((r) => r.requestId !== req.requestId);
+      without.push(req);
+      return without;
+    });
+  }
+  async get(requestId) {
+    const rows = await this.readAll();
+    return rows.find((r) => r.requestId === requestId) ?? null;
+  }
+  async list(filter) {
+    const rows = await this.readAll();
+    return rows.filter(
+      (r) => (filter?.surfaceType === void 0 || r.surfaceType === filter.surfaceType) && (filter?.sessionId === void 0 || r.sessionId === filter.sessionId)
+    );
+  }
+  async remove(requestId) {
+    await this.mutate((rows) => rows.filter((r) => r.requestId !== requestId));
+  }
+  async update(requestId, patch) {
+    await this.mutate((rows) => {
+      const idx = rows.findIndex((r) => r.requestId === requestId);
+      if (idx < 0) return rows;
+      const target = rows[idx];
+      if (!target) return rows;
+      const next = [...rows];
+      next[idx] = { ...target, ...patch, requestId: target.requestId };
+      return next;
+    });
+  }
+  async expired(now) {
+    const rows = await this.readAll();
+    const cutoff = now.getTime();
+    return rows.filter((r) => new Date(r.defaultDeadlineAt).getTime() <= cutoff);
+  }
+  // ---------------------------------------------------------------------------
+  async readAll() {
+    const raw = await this.storage.read(this.pendingPath);
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  /** Run a read-modify-write under the per-process mutex with an atomic write. */
+  async mutate(fn) {
+    const run = this.mutex.then(async () => {
+      const rows = await this.readAll();
+      const next = fn(rows);
+      await this.storage.mkdir(this.root);
+      await this.storage.writeAtomic(this.pendingPath, `${JSON.stringify(next, null, 2)}
+`);
+    });
+    this.mutex = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+};
+
+// src/defaults/in-memory-tool-context.ts
+var InMemoryKeyValueStore = class {
+  data = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.data.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== void 0 && Date.now() >= entry.expiresAt) {
+      this.data.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, opts) {
+    const expiresAt = opts?.ttlSeconds ? Date.now() + opts.ttlSeconds * 1e3 : void 0;
+    this.data.set(key, { value, expiresAt });
+  }
+  async delete(key) {
+    this.data.delete(key);
+  }
+  async list(prefix) {
+    return [...this.data.keys()].filter((k) => k.startsWith(prefix));
+  }
+};
+function makeTestToolContext(opts) {
+  const ctx = {
+    sessionId: opts?.sessionId ?? "test-session",
+    sessionKey: opts?.sessionKey ?? "cli:test",
+    platform: opts?.platform ?? "cli",
+    workingDir: opts?.workingDir ?? "/tmp",
+    personalityId: opts?.personalityId,
+    currentTurn: opts?.currentTurn ?? 1,
+    messageCount: opts?.messageCount ?? 1,
+    abortSignal: new AbortController().signal,
+    emit: () => {
+    },
+    resultBudgetChars: opts?.resultBudgetChars ?? 8e4
+  };
+  if (opts?.withStorage) {
+    ctx.kvStore = new InMemoryKeyValueStore();
+  }
+  return ctx;
+}
+
+// src/memory-policies.ts
+import { MemoryConflictError } from "@ethosagent/types";
+import { MemoryConflictError as MemoryConflictError2 } from "@ethosagent/types";
+var EagerPrefetchPolicy = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  inner;
+  prefetch(ctx) {
+    return this.inner.prefetch(ctx);
+  }
+  read(key, ctx) {
+    return this.inner.read(key, ctx);
+  }
+  search(query, ctx, opts) {
+    return this.inner.search(query, ctx, opts);
+  }
+  sync(updates, ctx) {
+    return this.inner.sync(updates, ctx);
+  }
+  list(ctx, opts) {
+    return this.inner.list(ctx, opts);
+  }
+};
+var LazyOnDemandPolicy = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  inner;
+  async prefetch(_ctx) {
+    return null;
+  }
+  read(key, ctx) {
+    return this.inner.read(key, ctx);
+  }
+  search(query, ctx, opts) {
+    return this.inner.search(query, ctx, opts);
+  }
+  sync(updates, ctx) {
+    return this.inner.sync(updates, ctx);
+  }
+  list(ctx, opts) {
+    return this.inner.list(ctx, opts);
+  }
+};
+var LastWriteWinsPolicy = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  inner;
+  /** scopeId:key → mtime at last read (ms). */
+  lastReadAt = /* @__PURE__ */ new Map();
+  // Snapshot entries from prefetch() are not added to the conflict tracker.
+  // Callers that rely on conflict detection must use read() before sync().
+  // In current wiring, LazyOnDemandPolicy suppresses prefetch() before it
+  // reaches this layer, so this is safe.
+  prefetch(ctx) {
+    return this.inner.prefetch(ctx);
+  }
+  /** Records the entry's mtime so sync() can detect concurrent modifications. */
+  async read(key, ctx) {
+    const entry = await this.inner.read(key, ctx);
+    if (entry?.metadata?.lastUpdatedAt !== void 0) {
+      this.lastReadAt.set(`${ctx.scopeId}:${key}`, entry.metadata.lastUpdatedAt);
+    }
+    return entry;
+  }
+  /**
+   * Records mtimes for entries returned by search so that a write based on
+   * search results also benefits from conflict detection.
+   *
+   * Only sets the mtime when no prior timestamp is recorded for the key.
+   * Overwriting an existing timestamp from a search result would allow a
+   * stale write to pass: caller reads at mtime 1, external writer bumps to
+   * mtime 2, caller searches and the result records mtime 2, caller syncs
+   * stale content — conflict check passes because currentAt === recordedAt.
+   * Preserving the oldest (first-read) mtime ensures that risk does not apply.
+   */
+  async search(query, ctx, opts) {
+    const results = await this.inner.search(query, ctx, opts);
+    for (const entry of results) {
+      const mapKey = `${ctx.scopeId}:${entry.key}`;
+      if (entry.metadata?.lastUpdatedAt !== void 0 && !this.lastReadAt.has(mapKey)) {
+        this.lastReadAt.set(mapKey, entry.metadata.lastUpdatedAt);
+      }
+    }
+    return results;
+  }
+  /**
+   * For each key that was previously read, check the current mtime against
+   * the recorded read-timestamp.  Rejects the entire call if any key has been
+   * modified by another writer since the caller last read it.
+   *
+   * After a successful write, updates `lastReadAt` baselines so that a second
+   * `sync()` call on the same key does not spuriously fail.  Keys that were
+   * deleted are removed from the tracker so they can be re-added later.
+   */
+  async sync(updates, ctx) {
+    const keysToCheck = /* @__PURE__ */ new Set();
+    for (const u of updates) {
+      const readAt = this.lastReadAt.get(`${ctx.scopeId}:${u.key}`);
+      if (readAt !== void 0) {
+        keysToCheck.add(u.key);
+      }
+    }
+    const fetchedMtimes = /* @__PURE__ */ new Map();
+    await Promise.all(
+      [...keysToCheck].map(async (key) => {
+        const current = await this.inner.read(key, ctx);
+        const currentMtime = current?.metadata?.lastUpdatedAt;
+        fetchedMtimes.set(key, currentMtime);
+        const readAt = this.lastReadAt.get(`${ctx.scopeId}:${key}`);
+        if (readAt !== void 0 && currentMtime !== void 0 && currentMtime > readAt) {
+          throw new MemoryConflictError({
+            key,
+            scopeId: ctx.scopeId,
+            recordedAt: readAt,
+            currentAt: currentMtime
+          });
+        }
+      })
+    );
+    await this.inner.sync(updates, ctx);
+    for (const u of updates) {
+      const mapKey = `${ctx.scopeId}:${u.key}`;
+      if (u.action === "delete") {
+        this.lastReadAt.delete(mapKey);
+      } else if (this.lastReadAt.has(mapKey)) {
+        const baseline = fetchedMtimes.get(u.key) ?? Date.now();
+        this.lastReadAt.set(mapKey, baseline);
+      }
+    }
+  }
+  list(ctx, opts) {
+    return this.inner.list(ctx, opts);
+  }
+};
+
+// src/path-boundary.ts
+import { resolve as resolve3, sep as sep2 } from "path";
+function assertWithinBase(base, target) {
+  const resolvedBase = resolve3(base);
+  const resolvedTarget = resolve3(target);
+  if (resolvedTarget === resolvedBase) return;
+  if (!resolvedTarget.startsWith(resolvedBase + sep2)) {
+    throw new BoundaryEscapeError(resolvedBase, resolvedTarget);
+  }
+}
+var BoundaryEscapeError = class extends Error {
+  code = "path-boundary-escape";
+  base;
+  resolved;
+  constructor(base, resolved) {
+    super(`Path "${resolved}" escapes boundary "${base}"`);
+    this.name = "BoundaryEscapeError";
+    this.base = base;
+    this.resolved = resolved;
+  }
+};
 
 // src/plugin-registry.ts
 var PluginRegistry = class {
@@ -1253,14 +3013,230 @@ var ChainedProvider = class {
     return this.entries.find((e) => e.cooldownUntil <= now);
   }
 };
+
+// src/providers/llm-registry.ts
+var DefaultLLMProviderRegistry = class {
+  factories = /* @__PURE__ */ new Map();
+  register(name, factory) {
+    if (this.factories.has(name)) {
+      throw new Error(`LLM provider "${name}" is already registered`);
+    }
+    this.factories.set(name, factory);
+  }
+  get(name) {
+    return this.factories.get(name);
+  }
+  list() {
+    return [...this.factories.keys()];
+  }
+};
+
+// src/providers/memory-registry.ts
+var DefaultMemoryProviderRegistry = class {
+  factories = /* @__PURE__ */ new Map();
+  register(name, factory) {
+    if (this.factories.has(name)) {
+      throw new Error(`Memory provider "${name}" is already registered`);
+    }
+    this.factories.set(name, factory);
+  }
+  get(name) {
+    return this.factories.get(name);
+  }
+  list() {
+    return [...this.factories.keys()];
+  }
+};
+
+// src/request-dump-store.ts
+var InMemoryRequestDumpStore = class {
+  records = [];
+  maxRecords;
+  constructor(opts) {
+    this.maxRecords = opts?.maxRecords ?? 1e3;
+  }
+  async append(record) {
+    this.records.push(record);
+    if (this.records.length > this.maxRecords) {
+      this.records = this.records.slice(-this.maxRecords);
+    }
+  }
+  async recent(opts) {
+    let results = [...this.records].reverse();
+    if (opts.sessionId) results = results.filter((r) => r.sessionId === opts.sessionId);
+    if (opts.since) {
+      const sinceTs = opts.since.getTime();
+      results = results.filter((r) => new Date(r.timestamp).getTime() >= sinceTs);
+    }
+    results = results.slice(0, opts.limit);
+    if (!opts.includeContent) {
+      results = results.map((r) => {
+        const { system, tools, messages, responseText, ...meta } = r;
+        return meta;
+      });
+    }
+    return results;
+  }
+  async close() {
+  }
+  getAll() {
+    return this.records;
+  }
+};
+
+// src/sanitize-output.ts
+var ESC = "\x1B";
+var BEL = "\x07";
+var ANSI_RE = new RegExp(
+  `${ESC}\\[[?!>]?[0-9;]*[A-Za-z~]|${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)|${ESC}\\([A-B0-2]|${ESC}[DME78HNO=>cfn]`,
+  "g"
+);
+function stripAnsiEscapes(input) {
+  return input.replace(ANSI_RE, "");
+}
+
+// src/url-validator.ts
+import { isIP } from "net";
+var IPV4_RE = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+function ip4ToInt(ip) {
+  return ip.split(".").reduce((acc, octet) => acc << 8 | Number.parseInt(octet, 10), 0) >>> 0;
+}
+var PRIVATE_RANGES_V4 = [
+  { start: ip4ToInt("0.0.0.0"), end: ip4ToInt("0.255.255.255") },
+  { start: ip4ToInt("10.0.0.0"), end: ip4ToInt("10.255.255.255") },
+  { start: ip4ToInt("100.64.0.0"), end: ip4ToInt("100.127.255.255") },
+  { start: ip4ToInt("127.0.0.0"), end: ip4ToInt("127.255.255.255") },
+  { start: ip4ToInt("169.254.0.0"), end: ip4ToInt("169.254.255.255") },
+  { start: ip4ToInt("172.16.0.0"), end: ip4ToInt("172.31.255.255") },
+  { start: ip4ToInt("192.168.0.0"), end: ip4ToInt("192.168.255.255") },
+  { start: ip4ToInt("224.0.0.0"), end: ip4ToInt("239.255.255.255") },
+  { start: ip4ToInt("240.0.0.0"), end: ip4ToInt("255.255.255.255") }
+];
+function isValidIpv4(s) {
+  const m = s.match(IPV4_RE);
+  return m?.slice(1).every((octet) => Number(octet) <= 255) ?? false;
+}
+function isPrivateIpv4(ip) {
+  if (!isValidIpv4(ip)) return false;
+  const n = ip4ToInt(ip);
+  return PRIVATE_RANGES_V4.some(({ start, end }) => n >= start && n <= end);
+}
+function isPrivateIpv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === "::1" || lower === "::") return true;
+  if (lower.startsWith("fe80:") || lower.startsWith("fc") || lower.startsWith("fd")) return true;
+  if (lower.startsWith("ff")) return true;
+  const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return isPrivateIpv4(mapped[1]);
+  return false;
+}
+function isPrivateIp(ip) {
+  return isPrivateIpv4(ip) || ip.includes(":") && isPrivateIpv6(ip);
+}
+function isLoopbackIp(ip) {
+  if (ip.startsWith("127.")) return true;
+  if (ip === "::1") return true;
+  const mapped = ip.toLowerCase().match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped?.[1].startsWith("127.")) return true;
+  return false;
+}
+var CLOUD_METADATA_HOSTS = /* @__PURE__ */ new Set([
+  "169.254.169.254",
+  "metadata.google.internal",
+  "metadata",
+  "metadata.azure.com",
+  "metadata.aws.amazon.com",
+  "fd00:ec2::254",
+  "100.100.100.200",
+  "169.254.0.23"
+]);
+var SsrfError = class extends Error {
+  constructor(url, reason) {
+    super(`SSRF blocked: ${reason} (${url})`);
+    this.name = "SsrfError";
+  }
+};
+function validateUrl(urlStr, opts) {
+  let url;
+  try {
+    url = new URL(urlStr);
+  } catch {
+    throw new SsrfError(urlStr, "invalid URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new SsrfError(urlStr, `scheme "${url.protocol.replace(":", "")}" not allowed`);
+  }
+  if (url.username || url.password) {
+    throw new SsrfError(urlStr, "URLs with embedded credentials are not allowed");
+  }
+  const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (opts?.trustedHosts?.includes(hostname)) {
+    return url;
+  }
+  if (CLOUD_METADATA_HOSTS.has(hostname)) {
+    throw new SsrfError(urlStr, `cloud-metadata host "${hostname}" is always denied`);
+  }
+  if (isIP(hostname)) {
+    if (opts?.allowLocalhost && isLoopbackIp(hostname)) {
+      return url;
+    }
+    if (isPrivateIp(hostname)) {
+      throw new SsrfError(urlStr, "private/internal IP address");
+    }
+  } else {
+    if (!opts?.allowLocalhost) {
+      if (hostname === "localhost" || hostname.endsWith(".local")) {
+        throw new SsrfError(urlStr, "localhost not allowed");
+      }
+    }
+    if (hostname.endsWith(".internal")) {
+      throw new SsrfError(urlStr, "internal hostname not allowed");
+    }
+  }
+  return url;
+}
 export {
   AgentLoop,
+  BoundaryEscapeError,
   ChainedProvider,
+  ClarifyBridge,
+  ClarifyBusyError,
+  ClarifyNoSurfaceError,
+  ClarifyTimedOutNoDefaultError,
+  DefaultContextEngineRegistry,
   DefaultHookRegistry,
+  DefaultLLMProviderRegistry,
+  DefaultMemoryProviderRegistry,
   DefaultPersonalityRegistry,
   DefaultToolRegistry,
+  DropOldestEngine,
+  EagerPrefetchPolicy,
+  FileClarifyStore,
+  InMemoryRequestDumpStore,
   InMemorySessionStore,
+  KNOWN_AGENT_EVENT_TYPES,
+  LastWriteWinsPolicy,
+  LazyOnDemandPolicy,
+  MemoryConflictError2 as MemoryConflictError,
   NoopMemoryProvider,
-  PluginRegistry
+  PluginRegistry,
+  ReferencePreservingEngine,
+  ScopedFetchImpl,
+  ScopedFsImpl,
+  ScopedProcessImpl,
+  ScopedSecretsImpl,
+  SemanticSummaryEngine,
+  SsrfError,
+  assertWithinBase,
+  buildAttachmentAnnotation,
+  estimateMessageTokens,
+  estimateMessagesTokens,
+  estimateTokens,
+  isKnownAgentEvent,
+  makeTestToolContext,
+  resolveCapabilities,
+  stripAnsiEscapes,
+  validateRegistration,
+  validateUrl
 };
 //# sourceMappingURL=index.js.map