@ap3x/agent-core 0.1.0

package/dist/index.js

@@ -0,0 +1,4153 @@
+// src/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function getOrThrow(result) {
+  if (result.ok) return result.value;
+  throw result.error;
+}
+function getOrUndefined(result) {
+  return result.ok ? result.value : void 0;
+}
+function toError(value) {
+  if (value instanceof Error) return value;
+  if (typeof value === "string") return new Error(value);
+  try {
+    return new Error(JSON.stringify(value));
+  } catch {
+    return new Error(String(value));
+  }
+}
+
+// src/errors.ts
+var Ap3xError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var FileError = class extends Ap3xError {
+  path;
+  constructor(code, message, path, cause) {
+    super(code, message, cause);
+    this.path = path;
+  }
+};
+var ExecutionError = class extends Ap3xError {
+};
+var SessionError = class extends Ap3xError {
+};
+var CompactionError = class extends Ap3xError {
+};
+var AgentHarnessError = class extends Ap3xError {
+};
+
+// src/uuid.ts
+var lastMillis = -1;
+var counter = 0;
+var RAND = new Uint8Array(16);
+function randomBytes(out) {
+  globalThis.crypto.getRandomValues(out);
+}
+var HEX = Array.from({ length: 256 }, (_, byte) => byte.toString(16).padStart(2, "0"));
+function format(bytes) {
+  let hex = "";
+  for (let i = 0; i < 16; i++) hex += HEX[bytes[i]];
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function uuidv7() {
+  randomBytes(RAND);
+  let now = Date.now();
+  if (now > lastMillis) {
+    lastMillis = now;
+    counter = (RAND[6] << 18 | RAND[7] << 10 | RAND[8] << 2 | RAND[9] >> 6) & 67108863;
+  } else {
+    counter = counter + 1 & 67108863;
+    if (counter === 0) {
+      lastMillis += 1;
+      now = lastMillis;
+    }
+  }
+  const millis = lastMillis;
+  const bytes = new Uint8Array(16);
+  bytes[0] = Math.floor(millis / 1099511627776) & 255;
+  bytes[1] = Math.floor(millis / 4294967296) & 255;
+  bytes[2] = millis >>> 24 & 255;
+  bytes[3] = millis >>> 16 & 255;
+  bytes[4] = millis >>> 8 & 255;
+  bytes[5] = millis & 255;
+  bytes[6] = 112 | counter >>> 22 & 15;
+  bytes[7] = counter >>> 14 & 255;
+  bytes[8] = 128 | counter >>> 8 & 63;
+  bytes[9] = counter & 255;
+  bytes[10] = RAND[10];
+  bytes[11] = RAND[11];
+  bytes[12] = RAND[12];
+  bytes[13] = RAND[13];
+  bytes[14] = RAND[14];
+  bytes[15] = RAND[15];
+  return format(bytes);
+}
+function shortId(existing, length = 8) {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const candidate = uuidv7().replace(/-/g, "").slice(-length);
+    if (!existing || !existing.has(candidate)) return candidate;
+  }
+  return uuidv7();
+}
+
+// src/concurrency.ts
+import { cpus, availableParallelism as nodeAvailableParallelism } from "os";
+function availableParallelism() {
+  if (typeof nodeAvailableParallelism === "function") return nodeAvailableParallelism();
+  return cpus().length || 1;
+}
+function createLimiter(concurrency) {
+  const limit = Math.max(1, Math.floor(concurrency));
+  let active = 0;
+  const queue = [];
+  const next = () => {
+    if (active >= limit) return;
+    const task = queue.shift();
+    if (task) {
+      active += 1;
+      task();
+    }
+  };
+  return function run(fn) {
+    return new Promise((resolve2, reject) => {
+      const start = () => {
+        fn().then(resolve2, reject).finally(() => {
+          active -= 1;
+          next();
+        });
+      };
+      queue.push(start);
+      next();
+    });
+  };
+}
+function mapLimit(items, concurrency, fn) {
+  const limit = createLimiter(concurrency);
+  return Promise.all(items.map((item, index) => limit(() => fn(item, index))));
+}
+
+// src/tools.ts
+import {
+  validateToolArguments
+} from "@ap3x/ai";
+function defineTool(spec) {
+  return spec;
+}
+function textResult(text, isError) {
+  return { content: [{ type: "text", text }], isError };
+}
+function toToolResultMessage(toolCall, result) {
+  return {
+    role: "toolResult",
+    toolCallId: toolCall.id,
+    toolName: toolCall.name,
+    content: result.content,
+    details: result.details,
+    isError: result.isError ?? false,
+    timestamp: Date.now()
+  };
+}
+async function prepareToolCall(toolCall, tools, hooks, signal, refs) {
+  if (signal?.aborted) {
+    return { kind: "immediate", result: textResult("Operation aborted", true) };
+  }
+  const tool = tools.find((candidate) => candidate.name === toolCall.name);
+  if (!tool) {
+    return { kind: "immediate", result: textResult(`Tool ${toolCall.name} not found`, true) };
+  }
+  let raw = toolCall.arguments;
+  if (tool.prepareArguments) {
+    const reshaped = tool.prepareArguments(raw);
+    if (reshaped !== raw) raw = reshaped;
+  }
+  let args;
+  try {
+    args = validateToolArguments(tool, { ...toolCall, arguments: raw });
+  } catch (error) {
+    return { kind: "immediate", result: textResult(toError(error).message, true) };
+  }
+  if (hooks?.beforeToolCall) {
+    const context = refs.assistantMessage && refs.agentContext ? {
+      assistantMessage: refs.assistantMessage,
+      toolCall,
+      args,
+      agentContext: refs.agentContext,
+      signal
+    } : void 0;
+    const gate = await hooks.beforeToolCall(tool.name, args, toolCall.id, context);
+    if (gate?.block) {
+      return {
+        kind: "immediate",
+        result: textResult(gate.reason ?? "Tool execution was blocked", true)
+      };
+    }
+    if (gate?.updatedArgs) {
+      try {
+        args = validateToolArguments(tool, { ...toolCall, arguments: gate.updatedArgs });
+      } catch (error) {
+        return {
+          kind: "immediate",
+          result: textResult(
+            `hook-updated arguments failed validation: ${toError(error).message}`,
+            true
+          )
+        };
+      }
+    }
+  }
+  if (signal?.aborted) {
+    return { kind: "immediate", result: textResult("Operation aborted", true) };
+  }
+  return { kind: "ready", tool, args };
+}
+async function executePreparedToolCall(toolCall, prepared, signal, emitUpdate) {
+  let acceptingUpdates = true;
+  try {
+    const result = await prepared.tool.execute(toolCall.id, prepared.args, signal, (update) => {
+      if (acceptingUpdates) emitUpdate(update);
+    });
+    acceptingUpdates = false;
+    return result;
+  } catch (error) {
+    acceptingUpdates = false;
+    return textResult(toError(error).message, true);
+  }
+}
+async function finalizeExecutedToolCall(toolCall, result, hooks, refs) {
+  if (!hooks?.afterToolCall) return result;
+  try {
+    const context = refs.assistantMessage && refs.agentContext ? {
+      assistantMessage: refs.assistantMessage,
+      toolCall,
+      args: refs.args ?? toolCall.arguments,
+      result,
+      isError: result.isError ?? false,
+      agentContext: refs.agentContext,
+      signal: refs.signal
+    } : void 0;
+    const patch = await hooks.afterToolCall(toolCall.name, result, toolCall.id, context);
+    if (!patch) return result;
+    return {
+      content: patch.content ?? result.content,
+      details: "details" in patch ? patch.details : result.details,
+      terminate: patch.terminate ?? result.terminate,
+      isError: patch.isError ?? result.isError
+    };
+  } catch (error) {
+    return textResult(toError(error).message, true);
+  }
+}
+function shouldTerminateBatch(results) {
+  return results.length > 0 && results.every((result) => result.terminate === true);
+}
+function parallelToolCallLimit() {
+  return Math.max(4, availableParallelism());
+}
+async function runOneToolCall(toolCall, options) {
+  const { tools, hooks, signal, emit, assistantMessage, context } = options;
+  const refs = { assistantMessage, agentContext: context };
+  await emit({
+    type: "tool_execution_start",
+    toolCallId: toolCall.id,
+    toolName: toolCall.name,
+    args: toolCall.arguments
+  });
+  const prepared = await prepareToolCall(toolCall, tools, hooks, signal, refs);
+  if (prepared.kind === "immediate") {
+    return finalizeExecutedToolCall(toolCall, prepared.result, hooks, { ...refs, signal });
+  }
+  const executed = await executePreparedToolCall(toolCall, prepared, signal, (update) => {
+    void emit({
+      type: "tool_execution_update",
+      toolCallId: toolCall.id,
+      toolName: toolCall.name,
+      update
+    });
+  });
+  return finalizeExecutedToolCall(toolCall, executed, hooks, {
+    ...refs,
+    args: prepared.args,
+    signal
+  });
+}
+async function executeToolCalls(options) {
+  const { toolCalls, signal, mode, emit } = options;
+  const sequential = mode === "sequential" || toolCalls.some((toolCall) => {
+    const tool = options.tools.find((candidate) => candidate.name === toolCall.name);
+    return tool?.executionMode === "sequential";
+  });
+  const results = [];
+  const messages = [];
+  if (sequential) {
+    for (const toolCall of toolCalls) {
+      if (signal?.aborted) break;
+      const result = await runOneToolCall(toolCall, options);
+      const message = toToolResultMessage(toolCall, result);
+      results.push(result);
+      messages.push(message);
+      await emit({
+        type: "tool_execution_end",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        result: message,
+        isError: message.isError
+      });
+    }
+    return { messages, terminate: shouldTerminateBatch(results) };
+  }
+  const settled = await mapLimit(
+    toolCalls,
+    parallelToolCallLimit(),
+    (toolCall) => runOneToolCall(toolCall, options)
+  );
+  for (let i = 0; i < toolCalls.length; i++) {
+    const toolCall = toolCalls[i];
+    const result = settled[i];
+    const message = toToolResultMessage(toolCall, result);
+    results.push(result);
+    messages.push(message);
+    await emit({
+      type: "tool_execution_end",
+      toolCallId: toolCall.id,
+      toolName: toolCall.name,
+      result: message,
+      isError: message.isError
+    });
+  }
+  return { messages, terminate: shouldTerminateBatch(results) };
+}
+
+// src/agent-loop.ts
+import {
+  streamSimple
+} from "@ap3x/ai";
+
+// src/compaction.ts
+import { completeSimple } from "@ap3x/ai";
+var DEFAULT_COMPACTION_SETTINGS = {
+  enabled: true,
+  reserveTokens: 16384,
+  keepRecentTokens: 2e4
+};
+var RESERVE_FRACTION = 0.15;
+var KEEP_RECENT_FRACTION = 0.25;
+function resolveCompactionSettings(settings, contextWindow) {
+  if (contextWindow <= 0) return settings;
+  return {
+    enabled: settings.enabled,
+    reserveTokens: Math.min(settings.reserveTokens, Math.floor(RESERVE_FRACTION * contextWindow)),
+    keepRecentTokens: Math.min(
+      settings.keepRecentTokens,
+      Math.floor(KEEP_RECENT_FRACTION * contextWindow)
+    )
+  };
+}
+function resolveAutoCompact(autoCompact) {
+  return autoCompact === false ? { ...DEFAULT_COMPACTION_SETTINGS, enabled: false } : DEFAULT_COMPACTION_SETTINGS;
+}
+var SUMMARIZATION_SYSTEM_PROMPT = "You are compacting a conversation to free up context. Produce a concise but complete summary under these markdown headings: Goal, Constraints, Progress, Decisions, Next Steps, Critical Context. Preserve every fact, file path, and decision a future turn would need. Omit pleasantries and redundant detail.";
+var CHARS_PER_TOKEN = 4;
+var IMAGE_TOKEN_ESTIMATE = 1200;
+var NO_ANCHOR_INFLATION = 1.25;
+function textLength(content) {
+  let total = 0;
+  for (const block of content) {
+    if (block.type === "text") total += block.text.length;
+    else total += IMAGE_TOKEN_ESTIMATE * CHARS_PER_TOKEN;
+  }
+  return total;
+}
+function estimateMessageTokens(message) {
+  if (message.role === "user") {
+    if (typeof message.content === "string") {
+      return Math.ceil(message.content.length / CHARS_PER_TOKEN);
+    }
+    return Math.ceil(textLength(message.content) / CHARS_PER_TOKEN);
+  }
+  if (message.role === "toolResult") {
+    return Math.ceil(textLength(message.content) / CHARS_PER_TOKEN);
+  }
+  if (message.role === "assistant") {
+    let chars = 0;
+    for (const block of message.content) {
+      if (block.type === "text") chars += block.text.length;
+      else if (block.type === "thinking") chars += block.thinking.length;
+      else chars += JSON.stringify(block.arguments).length + block.name.length;
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+  }
+  return 0;
+}
+function estimateContextTokens(messages, anchorFromIndex = 0) {
+  let anchorIndex = -1;
+  let anchorTokens = 0;
+  for (let i = messages.length - 1; i >= anchorFromIndex; i--) {
+    const message = messages[i];
+    if (message?.role === "assistant" && message.stopReason !== "error" && message.stopReason !== "aborted" && message.usage.totalTokens > 0) {
+      anchorIndex = i;
+      anchorTokens = message.usage.totalTokens;
+      break;
+    }
+  }
+  if (anchorIndex === -1) {
+    const sum = messages.reduce((total, message) => total + estimateMessageTokens(message), 0);
+    return Math.ceil(sum * NO_ANCHOR_INFLATION);
+  }
+  let trailing = 0;
+  for (let i = anchorIndex + 1; i < messages.length; i++) {
+    trailing += estimateMessageTokens(messages[i]);
+  }
+  return anchorTokens + trailing;
+}
+function shouldCompact(contextTokens, contextWindow, settings = DEFAULT_COMPACTION_SETTINGS) {
+  if (!settings.enabled) return false;
+  return contextTokens > contextWindow - settings.reserveTokens;
+}
+var SOFT_FRACTION = 0.6;
+var HARD_FRACTION = 0.85;
+function compactionTier(usage, contextWindow, settings) {
+  if (!settings.enabled || contextWindow <= 0) return "none";
+  const hardLine = Math.min(HARD_FRACTION * contextWindow, contextWindow - settings.reserveTokens);
+  const softLine = Math.min(SOFT_FRACTION * contextWindow, hardLine);
+  const floor = settings.keepRecentTokens + Math.floor(0.8 * settings.reserveTokens);
+  const hardTriggered = usage > HARD_FRACTION * contextWindow || shouldCompact(usage, contextWindow, settings);
+  if (hardTriggered) return floor < hardLine ? "hard" : "none";
+  if (usage > softLine) return floor < softLine ? "soft" : "none";
+  return "none";
+}
+function findCutPoint(messages, keepRecentTokens) {
+  if (messages.length === 0) return { cutIndex: 0, keptTokens: 0 };
+  let accumulated = 0;
+  let cutIndex = messages.length;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    accumulated += estimateMessageTokens(messages[i]);
+    cutIndex = i;
+    if (accumulated >= keepRecentTokens) break;
+  }
+  while (cutIndex < messages.length && messages[cutIndex]?.role === "toolResult") {
+    cutIndex++;
+  }
+  let keptTokens = 0;
+  for (let i = cutIndex; i < messages.length; i++) {
+    keptTokens += estimateMessageTokens(messages[i]);
+  }
+  return { cutIndex, keptTokens };
+}
+function serializeConversation(messages) {
+  return messages.map((message) => {
+    if (message.role === "user") {
+      const text = typeof message.content === "string" ? message.content : message.content.map((b) => b.type === "text" ? b.text : "[image]").join("\n");
+      return `User: ${text}`;
+    }
+    if (message.role === "toolResult") {
+      const text = message.content.map((b) => b.type === "text" ? b.text : "[image]").join("\n");
+      return `Tool(${message.toolName}): ${text}`;
+    }
+    if (message.role === "assistant") {
+      const text = message.content.map((b) => {
+        if (b.type === "text") return b.text;
+        if (b.type === "thinking") return `[thinking] ${b.thinking}`;
+        return `[tool call ${b.name}(${JSON.stringify(b.arguments)})]`;
+      }).join("\n");
+      return `Assistant: ${text}`;
+    }
+    return `[${message.role}]`;
+  }).join("\n\n");
+}
+function createFileOps() {
+  return { read: /* @__PURE__ */ new Set(), written: /* @__PURE__ */ new Set(), edited: /* @__PURE__ */ new Set() };
+}
+function extractFileOpsFromMessage(message, fileOps) {
+  if (message.role !== "assistant") return;
+  for (const block of message.content) {
+    if (block.type !== "toolCall") continue;
+    const path = typeof block.arguments.path === "string" ? block.arguments.path : void 0;
+    if (!path) continue;
+    if (block.name === "read") fileOps.read.add(path);
+    else if (block.name === "write") fileOps.written.add(path);
+    else if (block.name === "edit") fileOps.edited.add(path);
+  }
+}
+function computeFileLists(fileOps) {
+  const modified = /* @__PURE__ */ new Set([...fileOps.edited, ...fileOps.written]);
+  const readFiles = [...fileOps.read].filter((file) => !modified.has(file)).sort();
+  const modifiedFiles = [...modified].sort();
+  return { readFiles, modifiedFiles };
+}
+function formatFileOperations(readFiles, modifiedFiles) {
+  const sections = [];
+  if (readFiles.length > 0) sections.push(`<read-files>
+${readFiles.join("\n")}
+</read-files>`);
+  if (modifiedFiles.length > 0) {
+    sections.push(`<modified-files>
+${modifiedFiles.join("\n")}
+</modified-files>`);
+  }
+  return sections.length === 0 ? "" : `
+
+${sections.join("\n\n")}`;
+}
+function prepareCompaction(messages, settings = DEFAULT_COMPACTION_SETTINGS) {
+  const { cutIndex } = findCutPoint(messages, settings.keepRecentTokens);
+  const tokensBefore = estimateContextTokens(messages);
+  let turnStartIndex = -1;
+  if (cutIndex < messages.length && messages[cutIndex]?.role === "assistant") {
+    for (let i = cutIndex - 1; i >= 0; i--) {
+      if (messages[i]?.role === "user") {
+        turnStartIndex = i;
+        break;
+      }
+    }
+  }
+  const isSplitTurn = turnStartIndex >= 0;
+  const historyEnd = isSplitTurn ? turnStartIndex : cutIndex;
+  return {
+    historyMessages: messages.slice(0, historyEnd),
+    turnPrefixMessages: isSplitTurn ? messages.slice(turnStartIndex, cutIndex) : [],
+    keptMessages: messages.slice(cutIndex),
+    isSplitTurn,
+    tokensBefore
+  };
+}
+var UPDATE_SUMMARIZATION_PROMPT = "Update the existing summary (in <previous-summary>) with information from the new messages below. Preserve every fact, file path, and decision already recorded; move finished work forward and refresh Next Steps. Keep the same markdown headings.";
+var TURN_PREFIX_SUMMARIZATION_PROMPT = "The messages below are the PREFIX of a turn whose recent work is retained verbatim. Summarize only what the retained suffix needs: the original request, early progress, and context required to understand the kept work. Be concise.";
+function summaryMaxTokens(model, reserveTokens, fraction) {
+  const modelCap = model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY;
+  return Math.min(Math.floor(fraction * reserveTokens), modelCap);
+}
+function completionOptions(model, maxTokens, thinkingLevel, signal) {
+  if (model.reasoning && thinkingLevel && thinkingLevel !== "off") {
+    return { maxTokens, signal, reasoning: thinkingLevel };
+  }
+  return { maxTokens, signal };
+}
+function finalizeSummary(response, abortMessage) {
+  if (response.stopReason === "aborted") {
+    return err(new CompactionError("aborted", abortMessage));
+  }
+  if (response.stopReason === "error") {
+    return err(
+      new CompactionError("summarization_failed", response.errorMessage ?? "Summarization failed")
+    );
+  }
+  const summary = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+  return ok(summary);
+}
+async function generateSummary(history, model, settings, complete, options) {
+  const maxTokens = summaryMaxTokens(model, settings.reserveTokens, 0.8);
+  const instructions = options?.customInstructions ? `${SUMMARIZATION_SYSTEM_PROMPT}
+
+Additional instructions: ${options.customInstructions}` : SUMMARIZATION_SYSTEM_PROMPT;
+  const conversationText = serializeConversation(history);
+  const userText = options?.previousSummary ? `${UPDATE_SUMMARIZATION_PROMPT}
+
+<previous-summary>
+${options.previousSummary}
+</previous-summary>
+
+New messages to incorporate:
+
+${conversationText}` : `Summarize this conversation:
+
+${conversationText}`;
+  let response;
+  try {
+    response = await complete(
+      model,
+      {
+        systemPrompt: instructions,
+        messages: [{ role: "user", content: userText, timestamp: Date.now() }]
+      },
+      completionOptions(model, maxTokens, options?.thinkingLevel, options?.signal)
+    );
+  } catch (error) {
+    return err(new CompactionError("summarization_failed", toError(error).message, error));
+  }
+  return finalizeSummary(response, "Compaction was aborted");
+}
+async function generateTurnPrefixSummary(messages, model, settings, complete, options) {
+  const maxTokens = summaryMaxTokens(model, settings.reserveTokens, 0.5);
+  const userText = `${TURN_PREFIX_SUMMARIZATION_PROMPT}
+
+${serializeConversation(messages)}`;
+  let response;
+  try {
+    response = await complete(
+      model,
+      {
+        systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+        messages: [{ role: "user", content: userText, timestamp: Date.now() }]
+      },
+      completionOptions(model, maxTokens, options?.thinkingLevel, options?.signal)
+    );
+  } catch (error) {
+    return err(new CompactionError("summarization_failed", toError(error).message, error));
+  }
+  return finalizeSummary(response, "Turn prefix summarization was aborted");
+}
+async function compact(messages, model, options) {
+  const settings = options?.settings ?? DEFAULT_COMPACTION_SETTINGS;
+  if (messages.length === 0) {
+    return err(new CompactionError("compaction", "Nothing to compact"));
+  }
+  const complete = options?.complete ?? completeSimple;
+  const { historyMessages, turnPrefixMessages, keptMessages, isSplitTurn, tokensBefore } = prepareCompaction(messages, settings);
+  if (historyMessages.length === 0 && turnPrefixMessages.length === 0) {
+    return ok({ summary: "", keptMessages, tokensBefore, readFiles: [], modifiedFiles: [] });
+  }
+  const fileOps = createFileOps();
+  for (const message of historyMessages) extractFileOpsFromMessage(message, fileOps);
+  for (const message of turnPrefixMessages) extractFileOpsFromMessage(message, fileOps);
+  let summary;
+  if (isSplitTurn && turnPrefixMessages.length > 0) {
+    const historyResult = historyMessages.length > 0 ? await generateSummary(historyMessages, model, settings, complete, options) : ok("No prior history.");
+    if (!historyResult.ok) return err(historyResult.error);
+    const prefixResult = await generateTurnPrefixSummary(
+      turnPrefixMessages,
+      model,
+      settings,
+      complete,
+      options
+    );
+    if (!prefixResult.ok) return err(prefixResult.error);
+    summary = `${historyResult.value}
+
+---
+
+**Turn Context (split turn):**
+
+${prefixResult.value}`;
+  } else {
+    const summaryResult = await generateSummary(
+      historyMessages,
+      model,
+      settings,
+      complete,
+      options
+    );
+    if (!summaryResult.ok) return err(summaryResult.error);
+    summary = summaryResult.value;
+  }
+  const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+  summary += formatFileOperations(readFiles, modifiedFiles);
+  return ok({ summary, keptMessages, tokensBefore, readFiles, modifiedFiles });
+}
+
+// src/logger.ts
+var RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+function parseLevel(raw) {
+  if (raw === void 0) return void 0;
+  const normalized = raw.trim().toLowerCase();
+  return normalized in RANK ? normalized : void 0;
+}
+var activeLevel = parseLevel(process.env.AP3X_LOG_LEVEL) ?? "silent";
+function setLogLevel(level) {
+  activeLevel = level;
+}
+function getLogLevel() {
+  return activeLevel;
+}
+function enabled(level) {
+  return RANK[activeLevel] >= RANK[level];
+}
+var logger = {
+  debug(message, ...args) {
+    if (enabled("debug")) console.debug(message, ...args);
+  },
+  info(message, ...args) {
+    if (enabled("info")) console.info(message, ...args);
+  },
+  warn(message, ...args) {
+    if (enabled("warn")) console.warn(message, ...args);
+  },
+  error(message, ...args) {
+    if (enabled("error")) console.error(message, ...args);
+  }
+};
+
+// src/agent-loop.ts
+var DEFAULT_MAX_LOOPS = 1e3;
+function emptyUsage() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+  };
+}
+function failureMessage(model, message) {
+  return {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: emptyUsage(),
+    stopReason: "error",
+    errorMessage: message,
+    timestamp: Date.now()
+  };
+}
+function toolCallsOf(message) {
+  return message.content.filter((block) => block.type === "toolCall");
+}
+function configForTurn(config, turn, messages) {
+  if (!config.selectModel) return config;
+  const model = config.selectModel({ turn, messages });
+  return model ? { ...config, model } : config;
+}
+async function streamAssistantResponse(context, config, emit, signal, streamFn) {
+  const transformed = config.hooks?.transformContext ? await config.hooks.transformContext(context.messages, signal) : context.messages;
+  const messages = config.hooks?.convertToLlm ? await config.hooks.convertToLlm(transformed) : (
+    // Without a convertToLlm hook the (already transformed) transcript passes
+    // straight through. `AgentMessage` may be wider than `Message` once a host
+    // augments CustomAgentMessages, but a host that does so is expected to map
+    // its custom types down via convertToLlm; absent that, the transcript is
+    // standard `Message`s, so this cast is a no-op on the runtime value.
+    transformed
+  );
+  const llmContext = {
+    systemPrompt: config.systemPrompt ?? context.systemPrompt,
+    messages,
+    tools: config.tools?.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters
+    }))
+  };
+  const resolvedApiKey = config.hooks?.getApiKey ? await config.hooks.getApiKey(config.model.provider) : void 0;
+  const options = {
+    ...config.streamOptions,
+    ...resolvedApiKey ? { apiKey: resolvedApiKey } : {},
+    signal,
+    ...config.reasoning ? { reasoning: config.reasoning } : {}
+  };
+  let started = false;
+  try {
+    const eventStream = streamFn(config.model, llmContext, options);
+    for await (const providerEvent of eventStream) {
+      if (providerEvent.type === "start") {
+        started = true;
+        await emit({ type: "message_start", message: providerEvent.partial });
+        continue;
+      }
+      if (providerEvent.type === "done" || providerEvent.type === "error") {
+        break;
+      }
+      if ("partial" in providerEvent) {
+        await emit({
+          type: "message_update",
+          message: providerEvent.partial,
+          assistantMessageEvent: providerEvent
+        });
+      }
+    }
+    const final = await eventStream.result();
+    if (!started) await emit({ type: "message_start", message: final });
+    await emit({ type: "message_end", message: final });
+    return final;
+  } catch (error) {
+    const message = failureMessage(
+      config.model,
+      error instanceof Error ? error.message : String(error)
+    );
+    if (!started) await emit({ type: "message_start", message });
+    await emit({ type: "message_end", message });
+    return message;
+  }
+}
+async function runAgentLoop(prompts, context, config, emit, signal) {
+  const streamFn = config.streamFn ?? streamSimple;
+  const maxLoops = config.maxLoops ?? DEFAULT_MAX_LOOPS;
+  const newMessages = [];
+  const working = {
+    systemPrompt: config.systemPrompt ?? context.systemPrompt,
+    messages: [...context.messages],
+    tools: context.tools
+  };
+  await emit({ type: "agent_start" });
+  const drainSteering = async () => {
+    if (signal?.aborted || !config.hooks?.getSteeringMessages) return [];
+    return await config.hooks.getSteeringMessages() ?? [];
+  };
+  const drainFollowUp = async () => {
+    if (signal?.aborted || !config.hooks?.getFollowUpMessages) return [];
+    return await config.hooks.getFollowUpMessages() ?? [];
+  };
+  const compactionDeferred = async () => {
+    if (!config.hooks?.beforeCompaction) return false;
+    try {
+      return (await config.hooks.beforeCompaction())?.defer === true;
+    } catch {
+      return false;
+    }
+  };
+  let turns = 0;
+  let hasMoreToolCalls = true;
+  let pending = [...prompts];
+  const contextWindow = config.model.contextWindow;
+  const settings = resolveCompactionSettings(
+    config.compaction ?? DEFAULT_COMPACTION_SETTINGS,
+    contextWindow
+  );
+  const compactionOn = settings.enabled && contextWindow > 0;
+  let shadow = null;
+  let anchorFloor = 0;
+  let lastSummary = config.previousSummary;
+  let sawToolContinuation = false;
+  const launchShadow = () => {
+    const snapshotLen = working.messages.length;
+    const snapshot = working.messages.slice(0, snapshotLen);
+    const abort = new AbortController();
+    const onAbort = () => abort.abort();
+    let detached = false;
+    const cleanup = () => {
+      if (detached) return;
+      detached = true;
+      if (signal) signal.removeEventListener("abort", onAbort);
+    };
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+    const s = { snapshotLen, abort, cleanup, promise: void 0 };
+    s.promise = compact(snapshot, config.model, {
+      settings,
+      signal: abort.signal,
+      ...lastSummary !== void 0 ? { previousSummary: lastSummary } : {},
+      ...config.compactionComplete ? { complete: config.compactionComplete } : {}
+    }).then((r) => {
+      s.settled = r;
+      cleanup();
+      return r;
+    }).catch((e) => {
+      const r = err(
+        new CompactionError("compaction", toError(e).message, e)
+      );
+      s.settled = r;
+      cleanup();
+      return r;
+    });
+    logger.debug(`compaction: launched shadow (snapshotLen=${snapshotLen})`);
+    return s;
+  };
+  const applyShadow = async (s) => {
+    const r = s.settled;
+    if (!r) return false;
+    if (!r.ok) {
+      logger.warn(`compaction: failed, keeping context (${r.error.message})`);
+      return false;
+    }
+    const cr = r.value;
+    if (cr.summary === "" || cr.keptMessages.length >= s.snapshotLen) return false;
+    const summaryMsg = {
+      // Mirrors buildSessionContext so in-memory swap and resume read identically.
+      role: "user",
+      content: `[Earlier conversation summarized]
+${cr.summary}`,
+      timestamp: Date.now()
+    };
+    const rebased = [
+      summaryMsg,
+      ...cr.keptMessages,
+      ...working.messages.slice(s.snapshotLen)
+      // the arrival tail — messages appended during the in-flight compaction
+    ];
+    const sum = (ms) => ms.reduce((n, m) => n + estimateMessageTokens(m), 0);
+    const before = sum(working.messages);
+    const after = sum(rebased);
+    if (after >= before) {
+      logger.debug("compaction: not smaller, rolled back");
+      return false;
+    }
+    if (rebased.at(-1) !== working.messages.at(-1)) {
+      logger.debug("compaction: tail identity check failed, rolled back");
+      return false;
+    }
+    working.messages = rebased;
+    anchorFloor = rebased.length;
+    lastSummary = cr.summary;
+    await emit({
+      type: "compaction",
+      summary: cr.summary,
+      tokensBefore: cr.tokensBefore,
+      retainedAtSwap: rebased.length - 1,
+      // excludes summaryMsg
+      newMessagesAtSwap: newMessages.length
+    });
+    logger.info(`compaction: swapped ${before}->${after} tokens (kept ${cr.keptMessages.length})`);
+    return true;
+  };
+  while (hasMoreToolCalls || pending.length > 0) {
+    if (turns >= maxLoops) break;
+    await emit({ type: "turn_start" });
+    const steering = await drainSteering();
+    if (steering.length > 0) pending.push(...steering);
+    for (const prompt of pending) {
+      await emit({ type: "message_start", message: prompt });
+      working.messages.push(prompt);
+      newMessages.push(prompt);
+      await emit({ type: "message_end", message: prompt });
+    }
+    pending = [];
+    if (compactionOn) {
+      let handled = false;
+      if (shadow?.settled) {
+        await applyShadow(shadow);
+        shadow = null;
+        handled = true;
+      }
+      if (!handled) {
+        const usage = estimateContextTokens(working.messages, anchorFloor);
+        const tier = compactionTier(usage, contextWindow, settings);
+        if (tier === "hard") {
+          if (!shadow && !await compactionDeferred()) shadow = launchShadow();
+          if (shadow) {
+            await shadow.promise;
+            await applyShadow(shadow);
+            shadow = null;
+          }
+        } else if (tier === "soft" && !shadow && sawToolContinuation && !await compactionDeferred()) {
+          shadow = launchShadow();
+        }
+      }
+    }
+    const assistant = await streamAssistantResponse(
+      working,
+      configForTurn(config, turns, working.messages),
+      emit,
+      signal,
+      streamFn
+    );
+    working.messages.push(assistant);
+    newMessages.push(assistant);
+    turns++;
+    if (config.hooks?.onResponse) await config.hooks.onResponse(assistant);
+    if (assistant.stopReason === "error" || assistant.stopReason === "aborted") {
+      await emit({ type: "turn_end", message: assistant, toolResults: [] });
+      break;
+    }
+    const toolCalls = toolCallsOf(assistant);
+    hasMoreToolCalls = false;
+    if (toolCalls.length === 0) {
+      await emit({ type: "turn_end", message: assistant, toolResults: [] });
+      const followUp = await drainFollowUp();
+      if (followUp.length > 0) {
+        pending = followUp;
+        continue;
+      }
+      break;
+    }
+    const batch = await executeToolCalls({
+      toolCalls,
+      tools: config.tools ?? [],
+      hooks: config.hooks,
+      signal,
+      mode: config.toolExecution ?? "parallel",
+      assistantMessage: assistant,
+      context: working,
+      emit: (event) => emit(event)
+    });
+    for (const result of batch.messages) {
+      await emit({ type: "message_start", message: result });
+      working.messages.push(result);
+      newMessages.push(result);
+      await emit({ type: "message_end", message: result });
+    }
+    await emit({ type: "turn_end", message: assistant, toolResults: batch.messages });
+    if (batch.terminate) {
+      const followUp = await drainFollowUp();
+      if (followUp.length > 0) {
+        pending = followUp;
+        continue;
+      }
+      break;
+    }
+    if (signal?.aborted) break;
+    hasMoreToolCalls = true;
+    sawToolContinuation = true;
+  }
+  if (shadow && !shadow.settled) {
+    shadow.abort.abort();
+    shadow.cleanup();
+  }
+  await emit({ type: "agent_end", messages: newMessages });
+  return newMessages;
+}
+async function runAgentLoopContinue(context, config, emit, signal) {
+  const last = context.messages.at(-1);
+  if (!last) throw new Error("Cannot continue: no messages in context");
+  if (last.role === "assistant") {
+    throw new Error("Cannot continue from message role: assistant");
+  }
+  return runAgentLoop([], context, config, emit, signal);
+}
+function makeEventStream(run) {
+  const queue = [];
+  const waiters = [];
+  let done = false;
+  const emit = (event) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter({ value: event, done: false });
+    else queue.push(event);
+  };
+  const resultPromise = run(emit).finally(() => {
+    done = true;
+    while (waiters.length > 0) {
+      waiters.shift()?.({ value: void 0, done: true });
+    }
+  });
+  return {
+    result: () => resultPromise,
+    async *[Symbol.asyncIterator]() {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift();
+        } else if (done) {
+          return;
+        } else {
+          const next = await new Promise((resolve2) => {
+            waiters.push(resolve2);
+          });
+          if (next.done) return;
+          yield next.value;
+        }
+      }
+    }
+  };
+}
+function agentLoop(prompts, context, config, signal) {
+  return makeEventStream((emit) => runAgentLoop(prompts, context, config, emit, signal));
+}
+function agentLoopContinue(context, config, signal) {
+  const last = context.messages.at(-1);
+  if (!last) throw new Error("Cannot continue: no messages in context");
+  if (last.role === "assistant") {
+    throw new Error("Cannot continue from message role: assistant");
+  }
+  return makeEventStream((emit) => runAgentLoopContinue(context, config, emit, signal));
+}
+
+// src/agent.ts
+function finalTextOf(message) {
+  if (!message) return "";
+  return message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+function lastAssistant(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role === "assistant") return message;
+  }
+  return void 0;
+}
+var Agent = class {
+  model;
+  systemPrompt;
+  reasoning;
+  maxLoops;
+  toolExecution;
+  streamOptions;
+  hooks;
+  streamFn;
+  sessionId;
+  autoCompact;
+  previousSummary;
+  toolList;
+  transcript;
+  running = false;
+  controller;
+  lastError;
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * One shared FIFO of pending host-queued messages, each tagged with its
+   * {@link QueueMode}. `steer`-mode entries drain at each turn boundary
+   * (mid-run injection); everything left — `followUp`, `nextTurn`, and any
+   * late `steer` — drains when the run would otherwise stop (the rescue).
+   * JS is single-threaded, so enqueue is a plain push and drain is a plain
+   * splice at a loop boundary: no locking, no lost update.
+   */
+  pending = [];
+  /** A never-aborted signal handed to listeners for out-of-run queue events. */
+  idleSignal = new AbortController().signal;
+  constructor(options) {
+    this.model = options.model;
+    this.systemPrompt = options.systemPrompt;
+    this.reasoning = options.reasoning;
+    this.maxLoops = options.maxLoops;
+    this.toolExecution = options.toolExecution ?? "parallel";
+    this.streamOptions = options.streamOptions;
+    this.hooks = options.hooks ?? {};
+    this.streamFn = options.streamFn;
+    this.sessionId = options.sessionId;
+    this.autoCompact = options.autoCompact;
+    this.previousSummary = options.previousSummary;
+    this.toolList = options.tools ? [...options.tools] : [];
+    this.transcript = options.messages ? [...options.messages] : [];
+  }
+  /** A defensive snapshot of the agent's state. */
+  get state() {
+    return {
+      systemPrompt: this.systemPrompt,
+      model: this.model,
+      messages: [...this.transcript],
+      tools: [...this.toolList],
+      isRunning: this.running,
+      errorMessage: this.lastError
+    };
+  }
+  /** Whether a run is in progress. */
+  get isRunning() {
+    return this.running;
+  }
+  /** The abort signal of the active run, if any. */
+  get signal() {
+    return this.controller?.signal;
+  }
+  /** The full transcript (a copy). */
+  get messages() {
+    return [...this.transcript];
+  }
+  /** The registered tools (a copy). Setting replaces the list with a copy. */
+  get tools() {
+    return [...this.toolList];
+  }
+  set tools(tools) {
+    this.toolList = [...tools];
+  }
+  /** Register an event listener. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Queue a steering message. During a live run it is injected at the next turn
+   * boundary (before the next assistant turn streams); a steer queued during the
+   * final turn is rescued into the follow-up drain so it still extends the run.
+   * While idle it rides into the next run's first turn. Safe to call any time.
+   */
+  steer(message) {
+    this.enqueue("steer", message);
+  }
+  /** Queue a follow-up message that extends the run once it would otherwise stop. */
+  followUp(message) {
+    this.enqueue("followUp", message);
+  }
+  /**
+   * Queue a next-turn message. At the Agent level this shares the follow-up
+   * drain (delivered when the run would stop); the mode tag is preserved on
+   * `queue_update` so a host/harness can apply richer next-prompt semantics.
+   */
+  nextTurn(message) {
+    this.enqueue("nextTurn", message);
+  }
+  /**
+   * Move every pending host-queued message (steer/followUp/nextTurn, in queue
+   * order, mode tags intact) from `source` into this agent's queue. Used when a
+   * host replaces its agent mid-conversation (e.g. a compaction reseed) so
+   * messages queued while idle survive the rebuild instead of being dropped.
+   */
+  adoptPendingFrom(source) {
+    this.pending.push(...source.pending.splice(0, source.pending.length));
+  }
+  /** Abort the active run, if any. */
+  abort() {
+    this.controller?.abort();
+  }
+  /** Clear the transcript and any error state. Rejects while running. */
+  reset() {
+    if (this.running) {
+      throw new AgentHarnessError("busy", "Cannot reset while a run is in progress");
+    }
+    this.transcript = [];
+    this.lastError = void 0;
+  }
+  /**
+   * Append a user prompt and run the loop to completion. Returns the final
+   * assistant message. Throws {@link AgentHarnessError} `busy` if already running.
+   */
+  async prompt(input) {
+    if (this.running) {
+      throw new AgentHarnessError("busy", "Agent is already processing a run");
+    }
+    const prompts = this.normalizePrompts(input);
+    return this.runWithLifecycle(
+      (emit, signal) => runAgentLoop(prompts, this.currentContext(), this.currentConfig(), emit, signal)
+    );
+  }
+  /** Continue the loop from the current transcript with no new prompt. */
+  async continue() {
+    if (this.running) {
+      throw new AgentHarnessError("busy", "Agent is already processing a run");
+    }
+    return this.runWithLifecycle(
+      (emit, signal) => runAgentLoopContinue(this.currentContext(), this.currentConfig(), emit, signal)
+    );
+  }
+  normalizePrompts(input) {
+    if (typeof input === "string") {
+      return [{ role: "user", content: input, timestamp: Date.now() }];
+    }
+    return Array.isArray(input) ? input : [input];
+  }
+  currentContext() {
+    return {
+      systemPrompt: this.systemPrompt,
+      messages: [...this.transcript],
+      tools: this.toolList.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters
+      }))
+    };
+  }
+  currentConfig() {
+    return {
+      model: this.model,
+      systemPrompt: this.systemPrompt,
+      tools: this.toolList,
+      reasoning: this.reasoning,
+      maxLoops: this.maxLoops,
+      toolExecution: this.toolExecution,
+      streamOptions: this.streamOptions,
+      hooks: this.composedHooks(),
+      streamFn: this.streamFn,
+      compaction: resolveAutoCompact(this.autoCompact),
+      previousSummary: this.previousSummary
+    };
+  }
+  /**
+   * Wire the shared pending queue into the loop's two drain hooks, COMPOSED
+   * with any user-supplied hooks (never clobbered): the queue is drained first,
+   * then the user's hook is consulted and appended. `getSteeringMessages`
+   * drains `steer`-mode entries (mid-run inject); `getFollowUpMessages` drains
+   * everything left — `followUp`, `nextTurn`, and any late `steer` (the rescue).
+   * When the queue is empty and the user set no hook, each returns `[]`, which
+   * the loop treats identically to an absent hook (byte-identical no-queue path).
+   */
+  composedHooks() {
+    const userHooks = this.hooks;
+    return {
+      ...userHooks,
+      getSteeringMessages: async () => {
+        const drained = this.drainQueue((mode) => mode === "steer");
+        if (drained.length > 0) await this.emitQueueUpdate();
+        const fromUser = userHooks.getSteeringMessages ? await userHooks.getSteeringMessages() : [];
+        return [...drained, ...fromUser];
+      },
+      getFollowUpMessages: async () => {
+        const drained = this.drainQueue(() => true);
+        if (drained.length > 0) await this.emitQueueUpdate();
+        const fromUser = userHooks.getFollowUpMessages ? await userHooks.getFollowUpMessages() : [];
+        return [...drained, ...fromUser];
+      }
+    };
+  }
+  /** Enqueue a pending message and notify observers via `queue_update`. */
+  enqueue(mode, message) {
+    this.pending.push({ mode, message });
+    void this.emitQueueUpdate();
+  }
+  /** Remove and return (in FIFO order) the messages whose mode matches. */
+  drainQueue(match) {
+    if (this.pending.length === 0) return [];
+    const drained = [];
+    const remaining = [];
+    for (const entry of this.pending) {
+      if (match(entry.mode)) drained.push(entry.message);
+      else remaining.push(entry);
+    }
+    this.pending = remaining;
+    return drained;
+  }
+  /**
+   * Emit a `queue_update` snapshot to every listener. Best-effort and
+   * out-of-band: a failing observer is isolated so it can neither break an
+   * enqueue nor the active run. Uses the active run's signal when running, else
+   * a never-aborted idle signal.
+   */
+  async emitQueueUpdate() {
+    const byMode = (mode) => this.pending.filter((entry) => entry.mode === mode).map((entry) => entry.message);
+    const event = {
+      type: "queue_update",
+      steer: byMode("steer"),
+      followUp: byMode("followUp"),
+      nextTurn: byMode("nextTurn")
+    };
+    const signal = this.controller?.signal ?? this.idleSignal;
+    for (const listener of this.listeners) {
+      try {
+        await listener(event, signal);
+      } catch {
+      }
+    }
+  }
+  async runWithLifecycle(run) {
+    this.running = true;
+    this.lastError = void 0;
+    this.controller = new AbortController();
+    const signal = this.controller.signal;
+    const emit = async (event) => {
+      if (event.type === "compaction") this.previousSummary = event.summary;
+      for (const listener of this.listeners) {
+        await listener(event, signal);
+      }
+    };
+    try {
+      const newMessages = await run(emit, signal);
+      this.transcript.push(...newMessages);
+      const assistant = lastAssistant(newMessages);
+      if (assistant?.errorMessage) this.lastError = assistant.errorMessage;
+      if (!assistant) {
+        throw new AgentHarnessError("invalid_state", "Run completed without an assistant message");
+      }
+      return assistant;
+    } finally {
+      this.running = false;
+      this.controller = void 0;
+    }
+  }
+};
+
+// src/backend.ts
+var EMPTY_USAGE = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+};
+function toRunResult(messages) {
+  const assistant = lastAssistant(messages);
+  return {
+    messages,
+    finalText: finalTextOf(assistant),
+    usage: assistant?.usage ?? EMPTY_USAGE,
+    stopReason: assistant?.stopReason ?? "error",
+    errorMessage: assistant?.errorMessage
+  };
+}
+function toPrompts(task) {
+  if (typeof task === "string") {
+    return [{ role: "user", content: task, timestamp: Date.now() }];
+  }
+  return task;
+}
+var Ap3xRuntimeBackend = class _Ap3xRuntimeBackend {
+  options;
+  ephemeral;
+  stateful;
+  active;
+  listeners = /* @__PURE__ */ new Set();
+  constructor(options) {
+    const { ephemeral, ...agentOptions } = options;
+    this.options = agentOptions;
+    this.ephemeral = ephemeral ?? true;
+  }
+  newAgent() {
+    return new Agent(this.options);
+  }
+  agentFor() {
+    if (this.ephemeral) return this.newAgent();
+    if (!this.stateful) this.stateful = this.newAgent();
+    return this.stateful;
+  }
+  async run(task, opts) {
+    const agent = this.agentFor();
+    this.active = agent;
+    const unsubscribers = [...this.listeners].map(
+      (listener) => agent.subscribe((event) => listener(event))
+    );
+    let onExternalAbort;
+    if (opts?.signal) {
+      onExternalAbort = () => agent.abort();
+      if (opts.signal.aborted) {
+        queueMicrotask(() => agent.abort());
+      } else {
+        opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+    }
+    const before = this.ephemeral ? 0 : agent.messages.length;
+    try {
+      await agent.prompt(toPrompts(task));
+    } finally {
+      for (const unsubscribe of unsubscribers) unsubscribe();
+      if (opts?.signal && onExternalAbort) {
+        opts.signal.removeEventListener("abort", onExternalAbort);
+      }
+      this.active = void 0;
+    }
+    const messages = this.ephemeral ? agent.messages : agent.messages.slice(before);
+    return toRunResult(messages);
+  }
+  runStream(task, opts) {
+    const agent = this.agentFor();
+    return agentLoop(
+      toPrompts(task),
+      {
+        systemPrompt: this.options.systemPrompt,
+        messages: this.ephemeral ? [] : [...agent.messages],
+        tools: this.options.tools?.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.parameters
+        }))
+      },
+      {
+        model: this.options.model,
+        systemPrompt: this.options.systemPrompt,
+        tools: this.options.tools,
+        reasoning: this.options.reasoning,
+        maxLoops: this.options.maxLoops,
+        toolExecution: this.options.toolExecution,
+        streamOptions: this.options.streamOptions,
+        hooks: this.options.hooks,
+        streamFn: this.options.streamFn,
+        compaction: resolveAutoCompact(this.options.autoCompact),
+        previousSummary: this.options.previousSummary
+      },
+      opts?.signal
+    );
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  abort() {
+    this.active?.abort();
+  }
+  clone() {
+    return new _Ap3xRuntimeBackend({ ...this.options, ephemeral: this.ephemeral });
+  }
+  supports(capability) {
+    switch (capability) {
+      case "stream":
+      case "subscribe":
+      case "abort":
+      case "clone":
+        return true;
+      case "tools":
+        return (this.options.tools?.length ?? 0) > 0;
+      default:
+        return false;
+    }
+  }
+  getCurrentModel() {
+    return this.options.model;
+  }
+};
+function createRuntimeBackend(options) {
+  return new Ap3xRuntimeBackend(options);
+}
+
+// src/session.ts
+function createSessionId() {
+  return `session-${uuidv7()}`;
+}
+function pathToRoot(entries, leafId) {
+  const reversed = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = leafId;
+  while (current !== null) {
+    if (seen.has(current)) {
+      throw new SessionError("invalid_session", `Cycle detected in session tree at ${current}`);
+    }
+    seen.add(current);
+    const entry = entries.get(current);
+    if (!entry) {
+      throw new SessionError("not_found", `Session entry not found: ${current}`);
+    }
+    reversed.push(entry);
+    current = entry.parentId;
+  }
+  return reversed.reverse();
+}
+function producesContextMessage(entry) {
+  return entry.type === "message" || entry.type === "branch_summary" && entry.summary !== "";
+}
+function buildSessionContext(path) {
+  const context = { messages: [] };
+  let compactionIndex = -1;
+  for (let i = path.length - 1; i >= 0; i--) {
+    if (path[i]?.type === "compaction") {
+      compactionIndex = i;
+      break;
+    }
+  }
+  let startMessageId;
+  if (compactionIndex >= 0) {
+    const compaction = path[compactionIndex];
+    context.messages.push({
+      role: "user",
+      content: `[Earlier conversation summarized]
+${compaction.summary}`,
+      timestamp: compaction.timestamp
+    });
+    context.compactionSummary = compaction.summary;
+    startMessageId = compaction.firstKeptEntryId;
+  }
+  let collecting = startMessageId === void 0;
+  for (const entry of path) {
+    if (entry.type === "model_change") {
+      context.model = { provider: entry.provider, modelId: entry.modelId };
+      continue;
+    }
+    if (entry.type === "thinking_level_change") {
+      context.thinkingLevel = entry.thinkingLevel;
+      continue;
+    }
+    if (entry.type === "active_tools_change") {
+      context.activeToolNames = [...entry.activeToolNames];
+      continue;
+    }
+    if (entry.type === "session_info") {
+      context.sessionName = entry.name?.trim() || void 0;
+      continue;
+    }
+    if (entry.type !== "message" && entry.type !== "branch_summary") continue;
+    if (!collecting) {
+      if (entry.id === startMessageId) collecting = true;
+      else continue;
+    }
+    if (entry.type === "branch_summary") {
+      if (producesContextMessage(entry)) {
+        context.messages.push({
+          role: "user",
+          content: `[Summary of a branch this conversation returned from]
+${entry.summary}`,
+          timestamp: entry.timestamp
+        });
+      }
+      continue;
+    }
+    context.messages.push(entry.message);
+  }
+  return context;
+}
+var Session = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  storage;
+  getStorage() {
+    return this.storage;
+  }
+  getMetadata() {
+    return this.storage.getMetadata();
+  }
+  getLeafId() {
+    return this.storage.getLeafId();
+  }
+  getEntry(id) {
+    return this.storage.getEntry(id);
+  }
+  getEntries() {
+    return this.storage.getEntries();
+  }
+  getLabel(id) {
+    return this.storage.getLabel(id);
+  }
+  /** The root→leaf path of entries for the current (or a given) leaf. */
+  getBranch(fromId) {
+    const leaf = fromId ?? this.storage.getLeafId();
+    if (leaf === null) return [];
+    return this.storage.getPathToRoot(leaf);
+  }
+  /** Reconstruct the conversation context from the current branch. */
+  buildContext() {
+    return buildSessionContext(this.getBranch());
+  }
+  appendUnder(parentId, build) {
+    const id = this.storage.createEntryId();
+    const entry = build(id);
+    this.storage.appendEntry({ ...entry, id, parentId, timestamp: Date.now() });
+    this.storage.setLeafId(id);
+    return id;
+  }
+  /** Append a transcript message under the current leaf. Returns the new id. */
+  appendMessage(message) {
+    return this.appendUnder(this.storage.getLeafId(), (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "message",
+      message
+    }));
+  }
+  /** Append a compaction boundary. Returns the new id. */
+  appendCompaction(summary, firstKeptEntryId, tokensBefore) {
+    if (!this.storage.getEntry(firstKeptEntryId)) {
+      throw new SessionError(
+        "invalid_session",
+        `firstKeptEntryId does not resolve: ${firstKeptEntryId}`
+      );
+    }
+    return this.appendUnder(this.storage.getLeafId(), (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "compaction",
+      summary,
+      firstKeptEntryId,
+      tokensBefore
+    }));
+  }
+  /** Record a model change at the current leaf. Returns the new id. */
+  appendModelChange(provider, modelId) {
+    return this.appendUnder(this.storage.getLeafId(), (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "model_change",
+      provider,
+      modelId
+    }));
+  }
+  /** Attach a label to a target entry. Returns the new id. */
+  appendLabel(targetId, label) {
+    if (!this.storage.getEntry(targetId)) {
+      throw new SessionError("not_found", `Label target not found: ${targetId}`);
+    }
+    return this.appendUnder(this.storage.getLeafId(), (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "label",
+      targetId,
+      label
+    }));
+  }
+  /**
+   * Branch the conversation: repoint the leaf to an existing entry. Subsequent
+   * appends grow a new branch from that point. Returns the new leaf id.
+   */
+  branch(targetId) {
+    if (!this.storage.getEntry(targetId)) {
+      throw new SessionError("not_found", `Branch target not found: ${targetId}`);
+    }
+    this.storage.setLeafId(targetId);
+    return targetId;
+  }
+  /**
+   * Repoint the conversation head to an existing entry (or `null` to clear it),
+   * optionally recording a summary of the branch being left behind. When a
+   * summary is supplied the new leaf becomes that {@link BranchSummaryEntry}
+   * (parented to `entryId`) so it folds into the reconstructed context;
+   * otherwise the leaf is `entryId` itself. Returns the new branch-summary id,
+   * or `undefined` when no summary was recorded.
+   */
+  moveTo(entryId, summary) {
+    if (entryId !== null && !this.storage.getEntry(entryId)) {
+      throw new SessionError("not_found", `moveTo target not found: ${entryId}`);
+    }
+    this.storage.setLeafId(entryId);
+    if (!summary) return void 0;
+    return this.appendUnder(entryId, (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "branch_summary",
+      fromId: entryId ?? "root",
+      summary: summary.summary,
+      details: summary.details,
+      fromHook: summary.fromHook
+    }));
+  }
+  /**
+   * Record (or update) the human-readable session name. Line breaks are
+   * collapsed to spaces and the value is trimmed. Returns the new id.
+   */
+  appendSessionName(name) {
+    const sanitized = name.replace(/[\r\n]+/g, " ").trim();
+    return this.appendUnder(this.storage.getLeafId(), (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "session_info",
+      name: sanitized
+    }));
+  }
+};
+function makeInitialState(options) {
+  return {
+    metadata: {
+      id: options?.sessionId ?? createSessionId(),
+      timestamp: Date.now(),
+      cwd: options?.cwd ?? process.cwd()
+    },
+    entries: /* @__PURE__ */ new Map(),
+    order: [],
+    leafId: null
+  };
+}
+function createSharedStorage(state) {
+  const usedIds = new Set(state.order);
+  return {
+    getMetadata: () => state.metadata,
+    getLeafId: () => state.leafId,
+    setLeafId: (id) => {
+      if (id !== null && !state.entries.has(id)) {
+        throw new SessionError("invalid_session", `Leaf points at missing entry: ${id}`);
+      }
+      state.leafId = id;
+    },
+    createEntryId: () => {
+      const id = shortId(usedIds);
+      return id;
+    },
+    appendEntry: (entry) => {
+      state.entries.set(entry.id, entry);
+      state.order.push(entry.id);
+      usedIds.add(entry.id);
+    },
+    getEntry: (id) => state.entries.get(id),
+    getEntries: () => state.order.map((id) => state.entries.get(id)),
+    findEntries: (type) => state.order.map((id) => state.entries.get(id)).filter((entry) => entry.type === type),
+    getLabel: (id) => {
+      for (let i = state.order.length - 1; i >= 0; i--) {
+        const entry = state.entries.get(state.order[i]);
+        if (entry?.type === "label" && entry.targetId === id) return entry.label;
+      }
+      return void 0;
+    },
+    getPathToRoot: (leafId) => pathToRoot(state.entries, leafId)
+  };
+}
+var InMemorySessionStorage = class {
+  inner;
+  state;
+  constructor(options) {
+    this.state = makeInitialState(options);
+    this.inner = createSharedStorage(this.state);
+  }
+  getMetadata() {
+    return this.inner.getMetadata();
+  }
+  getLeafId() {
+    return this.inner.getLeafId();
+  }
+  setLeafId(id) {
+    this.inner.setLeafId(id);
+  }
+  createEntryId() {
+    return this.inner.createEntryId();
+  }
+  appendEntry(entry) {
+    this.inner.appendEntry(entry);
+  }
+  getEntry(id) {
+    return this.inner.getEntry(id);
+  }
+  getEntries() {
+    return this.inner.getEntries();
+  }
+  findEntries(type) {
+    return this.inner.findEntries(type);
+  }
+  getLabel(id) {
+    return this.inner.getLabel(id);
+  }
+  getPathToRoot(leafId) {
+    return this.inner.getPathToRoot(leafId);
+  }
+};
+var SESSION_FILE_VERSION = 1;
+var JsonlSessionStorage = class _JsonlSessionStorage {
+  file;
+  state;
+  inner;
+  constructor(file, state) {
+    this.file = file;
+    this.state = state;
+    this.inner = createSharedStorage(state);
+  }
+  /** Create a brand-new JSONL session, writing the header line. */
+  static create(file, options) {
+    const state = makeInitialState(options);
+    if (options?.parentSessionId) state.metadata.parentSessionId = options.parentSessionId;
+    const header = {
+      type: "session",
+      version: SESSION_FILE_VERSION,
+      id: state.metadata.id,
+      timestamp: state.metadata.timestamp,
+      cwd: state.metadata.cwd,
+      ...state.metadata.parentSessionId ? { parentSessionId: state.metadata.parentSessionId } : {}
+    };
+    file.append(`${JSON.stringify(header)}
+`);
+    return new _JsonlSessionStorage(file, state);
+  }
+  /** Open an existing JSONL session, replaying entries to rebuild the tree. */
+  static open(file) {
+    const content = file.read();
+    const lines = content.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+      throw new SessionError("invalid_session", "Empty session file: missing session header");
+    }
+    let header;
+    try {
+      header = JSON.parse(lines[0]);
+    } catch (error) {
+      throw new SessionError("invalid_session", "Session header is not valid JSON", error);
+    }
+    if (header.type !== "session" || typeof header.id !== "string") {
+      throw new SessionError("invalid_session", "Malformed session header");
+    }
+    const state = {
+      metadata: {
+        id: header.id,
+        timestamp: header.timestamp,
+        cwd: header.cwd,
+        ...header.parentSessionId ? { parentSessionId: header.parentSessionId } : {}
+      },
+      entries: /* @__PURE__ */ new Map(),
+      order: [],
+      leafId: null
+    };
+    for (let i = 1; i < lines.length; i++) {
+      let entry;
+      try {
+        entry = JSON.parse(lines[i]);
+      } catch (error) {
+        throw new SessionError("invalid_entry", `Invalid entry on line ${i + 1}`, error);
+      }
+      state.entries.set(entry.id, entry);
+      state.order.push(entry.id);
+      state.leafId = entry.type === "leaf" ? entry.targetId : entry.id;
+    }
+    return new _JsonlSessionStorage(file, state);
+  }
+  getMetadata() {
+    return this.inner.getMetadata();
+  }
+  getLeafId() {
+    return this.inner.getLeafId();
+  }
+  setLeafId(id) {
+    const previous = this.state.leafId;
+    this.inner.setLeafId(id);
+    if (id !== null && id !== previous) {
+      const lastAppended = this.state.order.at(-1);
+      if (id !== lastAppended) {
+        const leafEntry = {
+          id: shortId(new Set(this.state.order)),
+          parentId: previous,
+          timestamp: Date.now(),
+          type: "leaf",
+          targetId: id
+        };
+        this.state.entries.set(leafEntry.id, leafEntry);
+        this.state.order.push(leafEntry.id);
+        this.file.append(`${JSON.stringify(leafEntry)}
+`);
+      }
+    }
+  }
+  createEntryId() {
+    return this.inner.createEntryId();
+  }
+  appendEntry(entry) {
+    this.inner.appendEntry(entry);
+    this.file.append(`${JSON.stringify(entry)}
+`);
+  }
+  getEntry(id) {
+    return this.inner.getEntry(id);
+  }
+  getEntries() {
+    return this.inner.getEntries();
+  }
+  findEntries(type) {
+    return this.inner.findEntries(type);
+  }
+  getLabel(id) {
+    return this.inner.getLabel(id);
+  }
+  getPathToRoot(leafId) {
+    return this.inner.getPathToRoot(leafId);
+  }
+};
+var StringJsonlFile = class {
+  buffer;
+  constructor(initial = "") {
+    this.buffer = initial;
+  }
+  read() {
+    return this.buffer;
+  }
+  append(line) {
+    this.buffer += line;
+  }
+  /** The current serialized contents (the JSONL text). */
+  toString() {
+    return this.buffer;
+  }
+};
+
+// src/harness.ts
+var AgentHarness = class {
+  session;
+  agent;
+  agentOptions;
+  /** Harness-owned subscribers; a single forwarder relays each agent's events. */
+  listeners = /* @__PURE__ */ new Set();
+  /** Unsubscribes the forwarder from the current agent (re-wired on rebuild). */
+  agentUnsub;
+  /** Messages queued by {@link nextTurn}, prepended to (and cleared by) the next prompt. */
+  pendingNextTurn = [];
+  /**
+   * Summary of an in-memory (unpersistable) compaction — set when {@link compact}
+   * finds no session entry to anchor a durable CompactionEntry on (the agent runs
+   * on seeded `messages` the session never held). Threads into the NEXT compaction
+   * as `previousSummary` so it merges instead of being re-read as conversation
+   * text; cleared whenever the agent is reseeded from the session, which replaces
+   * the in-memory context this summary describes.
+   */
+  unpersistedSummary;
+  busy = false;
+  constructor(options) {
+    const { session, ...agentOptions } = options;
+    this.session = session;
+    this.agentOptions = agentOptions;
+    const context = session.buildContext();
+    this.buildAgent(context.messages.length > 0 ? context.messages : agentOptions.messages);
+  }
+  /**
+   * Run a single turn and persist all new messages to the session. Only
+   * turn-produced messages are appended — seeded {@link AgentOptions.messages}
+   * stay context-only and are never persisted (see that option's doc; B21).
+   */
+  async prompt(text) {
+    if (this.busy) throw new AgentHarnessError("busy", "AgentHarness is busy");
+    this.busy = true;
+    const before = this.agent.messages.length;
+    try {
+      const carried = this.pendingNextTurn;
+      this.pendingNextTurn = [];
+      const userMessage = { role: "user", content: text, timestamp: Date.now() };
+      const assistant = await this.agent.prompt([...carried, userMessage]);
+      const produced = this.agent.messages.slice(before);
+      for (const message of produced) {
+        this.session.appendMessage(message);
+      }
+      return assistant;
+    } finally {
+      this.busy = false;
+    }
+  }
+  /**
+   * Inject a steering message into the live run at the next turn boundary (or,
+   * while idle, into the next run's first turn). Delegates to the agent's queue.
+   */
+  steer(message) {
+    this.agent.steer(this.toMessage(message));
+  }
+  /** Queue a follow-up that extends the current run once it would otherwise stop. */
+  followUp(message) {
+    this.agent.followUp(this.toMessage(message));
+  }
+  /**
+   * Carry a message to the NEXT {@link prompt}: it is prepended to that prompt
+   * and the queue is cleared. Unlike {@link followUp}, this never extends the
+   * currently-running turn — the message is held at the harness (session) layer
+   * until the next prompt begins.
+   */
+  nextTurn(message) {
+    this.pendingNextTurn.push(this.toMessage(message));
+  }
+  /**
+   * Compact the agent's current context: summarize older history, persist a
+   * compaction boundary to the session, and reseed the agent from the compacted
+   * context so subsequent prompts run against the shortened transcript. Options
+   * are forwarded to the P13 {@link compact}. Throws the underlying
+   * {@link CompactionError} if summarization fails.
+   *
+   * When the agent runs on seeded `messages` the session never held (no entry
+   * can anchor a durable CompactionEntry), the compaction is applied to the
+   * live agent in-memory instead: the returned summary is real and the next
+   * provider call sees the compacted context, but no compaction boundary is
+   * persisted to the session for that run.
+   */
+  async compact(options) {
+    if (this.busy) throw new AgentHarnessError("busy", "AgentHarness is busy");
+    const settings = resolveCompactionSettings(
+      options?.settings ?? DEFAULT_COMPACTION_SETTINGS,
+      this.agent.model.contextWindow
+    );
+    const previousSummary = options?.previousSummary ?? this.unpersistedSummary ?? this.session.buildContext().compactionSummary;
+    const result = await compact(this.agent.messages, this.agent.model, {
+      ...options,
+      settings,
+      ...previousSummary !== void 0 ? { previousSummary } : {}
+    });
+    if (!result.ok) throw result.error;
+    const value = result.value;
+    if (value.summary !== "") {
+      const contextEntries = this.session.getBranch().filter(producesContextMessage);
+      const cut = contextEntries.length - value.keptMessages.length;
+      const firstKept = cut >= 0 ? contextEntries[cut] : void 0;
+      if (!firstKept) {
+        this.unpersistedSummary = value.summary;
+        this.buildAgent(
+          [
+            {
+              role: "user",
+              content: `[Earlier conversation summarized]
+${value.summary}`,
+              timestamp: Date.now()
+            },
+            ...value.keptMessages
+          ],
+          this.agent
+        );
+        return value;
+      }
+      this.session.appendCompaction(value.summary, firstKept.id, value.tokensBefore);
+    } else if (this.session.buildContext().messages.length === 0) {
+      return value;
+    }
+    this.reseedFromSession(this.agent);
+    return value;
+  }
+  /**
+   * Move the session's active branch to `entryId` and reseed the agent from that
+   * branch's reconstructed context, so subsequent prompts continue from the
+   * navigated-to point (rewind / branch-switch).
+   */
+  navigateTree(entryId) {
+    if (this.busy) throw new AgentHarnessError("busy", "AgentHarness is busy");
+    this.session.moveTo(entryId);
+    this.reseedFromSession();
+  }
+  /** Subscribe to the underlying agent's lifecycle events. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Typed event subscription: `handler` receives only events of `type`, narrowed
+   * to that variant. Returns an unsubscribe function.
+   */
+  on(type, handler) {
+    return this.subscribe((event) => {
+      if (event.type === type) return handler(event);
+    });
+  }
+  /** Abort the active run. */
+  abort() {
+    this.agent.abort();
+  }
+  /**
+   * Rebuild the inner agent over `messages`, re-wiring the event forwarder.
+   * When `previous` is given (a rebuild that CONTINUES the same conversation),
+   * its pending steer/followUp/nextTurn queue is carried into the new agent.
+   */
+  buildAgent(messages, previous) {
+    this.agentUnsub?.();
+    this.agent = new Agent({ ...this.agentOptions, messages });
+    if (previous) this.agent.adoptPendingFrom(previous);
+    this.agentUnsub = this.agent.subscribe(async (event) => {
+      for (const listener of this.listeners) await listener(event);
+    });
+  }
+  /** Reseed the agent from the session's current branch context. */
+  reseedFromSession(previous) {
+    this.unpersistedSummary = void 0;
+    this.buildAgent(this.session.buildContext().messages, previous);
+  }
+  /** Normalize a string prompt into a user {@link AgentMessage}. */
+  toMessage(message) {
+    return typeof message === "string" ? { role: "user", content: message, timestamp: Date.now() } : message;
+  }
+};
+
+// src/system-prompt.ts
+var DEFAULT_SEPARATOR = "\n\n";
+var SYSTEM_PROMPT_SECTIONS = {
+  /** Base persona / role instructions. */
+  persona: "persona",
+  /** Caller-supplied extra instructions appended to the base. */
+  custom: "custom",
+  /** Skills catalog slot — filled by the skills subsystem. */
+  skills: "skills",
+  /** Runtime environment: current date + working directory (placed last). */
+  environment: "environment"
+};
+function renderedContent(section) {
+  const trimmed = section.content?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function assembleSystemPrompt(sections, options = {}) {
+  const separator = options.separator ?? DEFAULT_SEPARATOR;
+  const parts = [];
+  for (const section of sections) {
+    const content = renderedContent(section);
+    if (content !== void 0) parts.push(content);
+  }
+  return parts.join(separator);
+}
+var SystemPromptBuilder = class {
+  sections = [];
+  separator;
+  constructor(options = {}) {
+    this.separator = options.separator ?? DEFAULT_SEPARATOR;
+  }
+  /** Append a named section in order. Chainable. */
+  section(name, content) {
+    this.sections.push({ name, content });
+    return this;
+  }
+  /** Render the accumulated sections to a single system-prompt string. */
+  render() {
+    return assembleSystemPrompt(this.sections, { separator: this.separator });
+  }
+};
+function environmentSection(input) {
+  const now = input.date;
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  const lines = [`Current date: ${year}-${month}-${day}`];
+  if (input.cwd) {
+    lines.push(`Current working directory: ${input.cwd.replace(/\\/g, "/")}`);
+  }
+  return { name: SYSTEM_PROMPT_SECTIONS.environment, content: lines.join("\n") };
+}
+
+// src/prompt-templates.ts
+import { readFile as readFile2 } from "fs/promises";
+import { basename } from "path";
+
+// src/loader.ts
+import { readFile } from "fs/promises";
+import { Type } from "@ap3x/ai";
+import { parse as yamlParse } from "yaml";
+var AgentSpecSchema = Type.Object({
+  name: Type.String(),
+  description: Type.Optional(Type.String()),
+  modelName: Type.Optional(Type.String()),
+  systemPrompt: Type.Optional(Type.String()),
+  temperature: Type.Optional(Type.Number()),
+  maxLoops: Type.Optional(Type.Integer()),
+  maxTokens: Type.Optional(Type.Integer()),
+  contextLength: Type.Optional(Type.Integer()),
+  outputType: Type.Optional(Type.String()),
+  autosave: Type.Optional(Type.Boolean()),
+  verbose: Type.Optional(Type.Boolean()),
+  streamingOn: Type.Optional(Type.Boolean()),
+  dynamicTemperatureEnabled: Type.Optional(Type.Boolean()),
+  retryAttempts: Type.Optional(Type.Integer()),
+  userName: Type.Optional(Type.String())
+});
+var DEFAULT_MODEL = "gpt-4";
+function asString(value) {
+  if (value === void 0 || value === null) return void 0;
+  return String(value);
+}
+function asNumber(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  const n = Number(value);
+  return Number.isNaN(n) ? void 0 : n;
+}
+function asBool(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value === "boolean") return value;
+  const s = String(value).trim().toLowerCase();
+  if (s === "true" || s === "1" || s === "yes") return true;
+  if (s === "false" || s === "0" || s === "no") return false;
+  return void 0;
+}
+function buildSpec(raw, fallbackSystemPrompt) {
+  const name = asString(raw.name ?? raw.agent_name ?? raw.agentName);
+  if (!name) throw new Error("Agent spec is missing a name.");
+  const spec = { name };
+  const description = asString(raw.description);
+  if (description !== void 0) spec.description = description;
+  spec.modelName = asString(raw.model_name ?? raw.modelName) ?? DEFAULT_MODEL;
+  const systemPrompt = asString(raw.system_prompt ?? raw.systemPrompt) ?? fallbackSystemPrompt;
+  if (systemPrompt !== void 0) spec.systemPrompt = systemPrompt;
+  const temperature = asNumber(raw.temperature);
+  if (temperature !== void 0) spec.temperature = temperature;
+  const maxLoops = asNumber(raw.max_loops ?? raw.maxLoops);
+  if (maxLoops !== void 0) spec.maxLoops = maxLoops;
+  const maxTokens = asNumber(raw.max_tokens ?? raw.maxTokens);
+  if (maxTokens !== void 0) spec.maxTokens = maxTokens;
+  const contextLength = asNumber(raw.context_length ?? raw.contextLength);
+  if (contextLength !== void 0) spec.contextLength = contextLength;
+  const outputType = asString(raw.output_type ?? raw.outputType);
+  if (outputType !== void 0) spec.outputType = outputType;
+  const retryAttempts = asNumber(raw.retry_attempts ?? raw.retryAttempts);
+  if (retryAttempts !== void 0) spec.retryAttempts = retryAttempts;
+  const userName = asString(raw.user_name ?? raw.userName);
+  if (userName !== void 0) spec.userName = userName;
+  const autosave = asBool(raw.autosave);
+  if (autosave !== void 0) spec.autosave = autosave;
+  const verbose = asBool(raw.verbose);
+  if (verbose !== void 0) spec.verbose = verbose;
+  const streamingOn = asBool(raw.streaming_on ?? raw.streamingOn);
+  if (streamingOn !== void 0) spec.streamingOn = streamingOn;
+  const dynamicTemp = asBool(raw.dynamic_temperature_enabled ?? raw.dynamicTemperatureEnabled);
+  if (dynamicTemp !== void 0) spec.dynamicTemperatureEnabled = dynamicTemp;
+  return spec;
+}
+function parseYamlFrontmatter(content) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return { frontmatter: {}, body: content };
+  let endMarker = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      endMarker = i;
+      break;
+    }
+  }
+  if (endMarker === -1) return { frontmatter: {}, body: content };
+  const frontmatterText = lines.slice(1, endMarker).join("\n");
+  const body = lines.slice(endMarker + 1).join("\n").trim();
+  let frontmatter = {};
+  try {
+    frontmatter = yamlParse(frontmatterText) ?? {};
+  } catch {
+    return { frontmatter: {}, body: content };
+  }
+  return { frontmatter, body };
+}
+function parseCsvLine(line) {
+  const fields = [];
+  let current = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (line[i + 1] === '"') {
+          current += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"') {
+      inQuotes = true;
+    } else if (ch === ",") {
+      fields.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  fields.push(current);
+  return fields;
+}
+var AgentLoader = class {
+  concurrent;
+  constructor(options = {}) {
+    this.concurrent = options.concurrent ?? true;
+  }
+  /** Parse one markdown file (YAML frontmatter + body as system prompt). */
+  async loadAgentFromMarkdown(filePath) {
+    const content = await readFile(filePath, "utf-8");
+    const { frontmatter, body } = parseYamlFrontmatter(content);
+    return buildSpec(frontmatter, body || void 0);
+  }
+  /** Parse one or more markdown files. */
+  async loadAgentsFromMarkdown(filePaths, options = {}) {
+    const paths = Array.isArray(filePaths) ? filePaths : [filePaths];
+    const concurrent = options.concurrent ?? this.concurrent;
+    if (concurrent) {
+      return Promise.all(paths.map((p) => this.loadAgentFromMarkdown(p)));
+    }
+    const specs = [];
+    for (const p of paths) specs.push(await this.loadAgentFromMarkdown(p));
+    return specs;
+  }
+  /** Parse a YAML file containing one agent or a list under `agents`. */
+  async loadAgentsFromYaml(yamlFile) {
+    const content = await readFile(yamlFile, "utf-8");
+    const data = yamlParse(content);
+    let entries;
+    if (Array.isArray(data)) {
+      entries = data;
+    } else if (data && typeof data === "object" && Array.isArray(data.agents)) {
+      entries = data.agents;
+    } else if (data && typeof data === "object") {
+      entries = [data];
+    } else {
+      entries = [];
+    }
+    return entries.map((e) => buildSpec(e));
+  }
+  /** Parse several YAML files. */
+  async loadManyAgentsFromYaml(yamlFiles) {
+    return Promise.all(yamlFiles.map((f) => this.loadAgentsFromYaml(f)));
+  }
+  /** Parse a CSV file (first row is the header). */
+  async loadAgentsFromCsv(csvFile) {
+    const content = await readFile(csvFile, "utf-8");
+    const lines = content.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    if (lines.length === 0) return [];
+    const header = parseCsvLine(lines[0]).map((h) => h.trim());
+    const specs = [];
+    for (let i = 1; i < lines.length; i++) {
+      const cells = parseCsvLine(lines[i]);
+      const row = {};
+      header.forEach((key, idx) => {
+        row[key] = cells[idx];
+      });
+      specs.push(buildSpec(row));
+    }
+    return specs;
+  }
+  /** Dispatch by file extension (.md / .yaml / .yml / .csv). */
+  async auto(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith(".md")) return this.loadAgentsFromMarkdown(filePath);
+    if (lower.endsWith(".yaml") || lower.endsWith(".yml")) return this.loadAgentsFromYaml(filePath);
+    if (lower.endsWith(".csv")) return this.loadAgentsFromCsv(filePath);
+    throw new Error(`Unsupported file type: ${filePath}`);
+  }
+  /** Load a single spec from a file via {@link auto}. */
+  async loadSingleAgent(filePath) {
+    const specs = await this.auto(filePath);
+    const first = specs[0];
+    if (!first) throw new Error(`No agent specifications found in ${filePath}`);
+    return first;
+  }
+  /** Load specs from several files (each may yield multiple), flattened. */
+  async loadMultipleAgents(filePaths) {
+    const results = await Promise.all(filePaths.map((p) => this.auto(p)));
+    return results.flat();
+  }
+};
+var AgentConfigSchema = Type.Object({
+  uuid: Type.String(),
+  name: Type.String(),
+  description: Type.Optional(Type.String()),
+  timeAdded: Type.String(),
+  config: Type.Record(Type.String(), Type.Unknown())
+});
+var AgentRegistrySchema = Type.Object({
+  name: Type.String(),
+  description: Type.String(),
+  agents: Type.Array(AgentConfigSchema),
+  timeRegistryCreated: Type.String(),
+  numberOfAgents: Type.Integer()
+});
+function registrableName(agent) {
+  return agent.agentName ?? agent.name;
+}
+var AgentRegistry = class {
+  name;
+  description;
+  agents = /* @__PURE__ */ new Map();
+  timeCreated;
+  constructor(options = {}) {
+    this.name = options.name ?? "Agent Registry";
+    this.description = options.description ?? "A registry for managing agents.";
+    this.timeCreated = (/* @__PURE__ */ new Date()).toISOString();
+    if (options.agents) this.addMany(options.agents);
+  }
+  /** Add an agent. Throws if the name is already taken. */
+  add(agent) {
+    const name = registrableName(agent);
+    if (!name) throw new Error("Cannot register an agent without a name.");
+    if (this.agents.has(name)) {
+      throw new Error(`Agent with name ${name} already exists.`);
+    }
+    this.agents.set(name, agent);
+  }
+  /** Add several agents. */
+  addMany(agents) {
+    for (const agent of agents) this.add(agent);
+  }
+  /** Delete an agent by name. Throws if it does not exist. */
+  delete(name) {
+    if (!this.agents.has(name)) throw new Error(`Agent with name ${name} does not exist.`);
+    this.agents.delete(name);
+  }
+  /** Replace an agent by name. Throws if it does not exist. */
+  updateAgent(name, newAgent) {
+    if (!this.agents.has(name)) throw new Error(`Agent with name ${name} does not exist.`);
+    this.agents.set(name, newAgent);
+  }
+  /** Get an agent by name. Throws if it does not exist. */
+  get(name) {
+    const agent = this.agents.get(name);
+    if (!agent) throw new Error(`Agent with name ${name} does not exist.`);
+    return agent;
+  }
+  /** List all registered agent names. */
+  listAgents() {
+    return [...this.agents.keys()];
+  }
+  /** Return all registered agents. */
+  returnAllAgents() {
+    return [...this.agents.values()];
+  }
+  /** Filter agents by a predicate (or return all when omitted). */
+  query(condition) {
+    const all = this.returnAllAgents();
+    return condition ? all.filter(condition) : all;
+  }
+  /** Find an agent by name (undefined if absent). */
+  findAgentByName(name) {
+    return this.agents.get(name);
+  }
+  /** Find an agent by id (undefined if absent). */
+  findAgentById(id) {
+    for (const agent of this.agents.values()) {
+      if (agent.id === id) return agent;
+    }
+    return void 0;
+  }
+  /** Number of registered agents. */
+  get size() {
+    return this.agents.size;
+  }
+  /** Serialize every agent's `toDict()` keyed by name. */
+  agentsToJson() {
+    const out = {};
+    for (const [name, agent] of this.agents) {
+      out[name] = agent.toDict ? agent.toDict() : { ...agent };
+    }
+    return JSON.stringify(out, null, 4);
+  }
+  /** Build a validated {@link AgentConfig} record for an agent. */
+  agentToModel(agent) {
+    return {
+      uuid: agent.id ?? uuidv7(),
+      name: registrableName(agent) ?? "unknown",
+      description: agent.description ?? "No description provided",
+      timeAdded: (/* @__PURE__ */ new Date()).toISOString(),
+      config: agent.toDict ? agent.toDict() : { ...agent }
+    };
+  }
+  /** A validated snapshot of the whole registry. */
+  toSchema() {
+    return {
+      name: this.name,
+      description: this.description,
+      agents: this.returnAllAgents().map((a) => this.agentToModel(a)),
+      timeRegistryCreated: this.timeCreated,
+      numberOfAgents: this.agents.size
+    };
+  }
+};
+
+// src/prompt-templates.ts
+var DESCRIPTION_PREVIEW_LIMIT = 60;
+function parseCommandArgs(argsString) {
+  const args = [];
+  let current = "";
+  let inQuote = null;
+  for (let i = 0; i < argsString.length; i++) {
+    const char = argsString[i];
+    if (inQuote) {
+      if (char === inQuote) inQuote = null;
+      else current += char;
+    } else if (char === '"' || char === "'") {
+      inQuote = char;
+    } else if (char === " " || char === "	") {
+      if (current) {
+        args.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) args.push(current);
+  return args;
+}
+function substituteArgs(content, args) {
+  let result = content;
+  result = result.replace(
+    /\$(\d+)/g,
+    (_match, num) => args[Number.parseInt(num, 10) - 1] ?? ""
+  );
+  result = result.replace(
+    /\$\{@:(\d+)(?::(\d+))?\}/g,
+    (_match, startStr, lengthStr) => {
+      let start = Number.parseInt(startStr, 10) - 1;
+      if (start < 0) start = 0;
+      if (lengthStr !== void 0) {
+        return args.slice(start, start + Number.parseInt(lengthStr, 10)).join(" ");
+      }
+      return args.slice(start).join(" ");
+    }
+  );
+  const allArgs = args.join(" ");
+  result = result.replace(/\$ARGUMENTS/g, allArgs);
+  result = result.replace(/\$@/g, allArgs);
+  return result;
+}
+function parsePromptTemplate(name, content) {
+  const { frontmatter, body } = parseYamlFrontmatter(content);
+  let description = typeof frontmatter.description === "string" ? frontmatter.description : "";
+  if (!description) {
+    const firstLine = body.split("\n").find((line) => line.trim());
+    if (firstLine) {
+      description = firstLine.slice(0, DESCRIPTION_PREVIEW_LIMIT);
+      if (firstLine.length > DESCRIPTION_PREVIEW_LIMIT) description += "...";
+    }
+  }
+  return { name, description, content: body };
+}
+async function loadPromptTemplate(filePath) {
+  const content = await readFile2(filePath, "utf-8");
+  const name = basename(filePath).replace(/\.md$/i, "");
+  return parsePromptTemplate(name, content);
+}
+function renderPromptTemplate(template, args = []) {
+  return substituteArgs(template.content, args);
+}
+
+// src/skills.ts
+import { access, readFile as readFile3, readdir } from "fs/promises";
+import { basename as basename2, dirname, join } from "path";
+function parseSkill(fallbackName, content, location) {
+  const { frontmatter, body } = parseYamlFrontmatter(content);
+  const fmName = frontmatter.name;
+  const name = typeof fmName === "string" && fmName.trim() ? fmName : fallbackName;
+  const description = typeof frontmatter.description === "string" ? frontmatter.description : "";
+  return {
+    name,
+    description,
+    location,
+    body,
+    disableModelInvocation: frontmatter["disable-model-invocation"] === true
+  };
+}
+async function loadSkill(filePath) {
+  const content = await readFile3(filePath, "utf-8");
+  const fallbackName = basename2(filePath).replace(/\.md$/i, "");
+  return parseSkill(fallbackName, content, filePath);
+}
+async function loadSkills(filePaths) {
+  return Promise.all(filePaths.map((p) => loadSkill(p)));
+}
+async function discoverSkillFiles(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const candidate = join(dir, entry.name, "SKILL.md");
+      try {
+        await access(candidate);
+        files.push(candidate);
+      } catch {
+      }
+    } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+      files.push(join(dir, entry.name));
+    }
+  }
+  return files.sort();
+}
+async function discoverSkills(dir) {
+  const files = await discoverSkillFiles(dir);
+  const skills = [];
+  for (const file of files) {
+    let content;
+    try {
+      content = await readFile3(file, "utf-8");
+    } catch {
+      continue;
+    }
+    const base = basename2(file);
+    const parent = dirname(file);
+    const fallback = base.toLowerCase() === "skill.md" && parent !== dir ? basename2(parent) : base.replace(/\.md$/i, "");
+    skills.push(parseSkill(fallback, content, file));
+  }
+  return skills;
+}
+var SkillRegistry = class {
+  skills = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    if (options.skills) this.addMany(options.skills);
+  }
+  /** Add a skill. Throws if the name is already registered. */
+  add(skill) {
+    if (this.skills.has(skill.name)) {
+      throw new Error(`Skill with name ${skill.name} already exists.`);
+    }
+    this.skills.set(skill.name, skill);
+  }
+  /** Add several skills. */
+  addMany(skills) {
+    for (const skill of skills) this.add(skill);
+  }
+  /** Get a skill by name. Throws if it does not exist. */
+  get(name) {
+    const skill = this.skills.get(name);
+    if (!skill) throw new Error(`Skill with name ${name} does not exist.`);
+    return skill;
+  }
+  /** Find a skill by name (undefined if absent). */
+  find(name) {
+    return this.skills.get(name);
+  }
+  /** List all registered skills. */
+  list() {
+    return [...this.skills.values()];
+  }
+  /** Filter skills by a predicate (or return all when omitted). */
+  query(condition) {
+    const all = this.list();
+    return condition ? all.filter(condition) : all;
+  }
+  /** Number of registered skills. */
+  get size() {
+    return this.skills.size;
+  }
+};
+var CATALOG_INTRO = "Skills below give focused instructions for particular tasks. When a task matches a skill's description, use the read tool to load its full instructions from the file at its location; resolve any relative path inside that file against the skill's directory.";
+function formatSkillsForSystemPrompt(skills) {
+  const visible = skills.filter((s) => !s.disableModelInvocation);
+  if (visible.length === 0) return "";
+  const lines = [CATALOG_INTRO, "", "<available_skills>"];
+  for (const skill of visible) {
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.location)}</location>`);
+    lines.push("  </skill>");
+  }
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+// src/session-repo.ts
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync
+} from "fs";
+import { homedir } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+var FileJsonlFile = class {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  ensuredDir = false;
+  /** Read the entire file, or "" when it does not exist yet. */
+  read() {
+    try {
+      return readFileSync(this.path, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") return "";
+      throw error;
+    }
+  }
+  /** Append a line (the caller supplies the trailing newline). */
+  append(line) {
+    if (!this.ensuredDir) {
+      mkdirSync(dirname2(this.path), { recursive: true });
+      this.ensuredDir = true;
+    }
+    appendFileSync(this.path, line);
+  }
+};
+function entriesToFork(storage, options) {
+  if (!options.entryId) return storage.getEntries();
+  const target = storage.getEntry(options.entryId);
+  if (!target) {
+    throw new SessionError("not_found", `Fork target not found: ${options.entryId}`);
+  }
+  let effectiveLeafId;
+  if ((options.position ?? "before") === "at") {
+    effectiveLeafId = target.id;
+  } else {
+    if (target.type !== "message" || target.message.role !== "user") {
+      throw new SessionError(
+        "invalid_session",
+        `Fork target is not a user message: ${options.entryId}`
+      );
+    }
+    effectiveLeafId = target.parentId;
+  }
+  if (effectiveLeafId === null) return [];
+  return storage.getPathToRoot(effectiveLeafId);
+}
+var JsonlSessionRepo = class {
+  root;
+  constructor(options) {
+    this.root = options?.root ?? join2(homedir(), ".ap3x", "sessions");
+  }
+  pathFor(id) {
+    return join2(this.root, `${id}.jsonl`);
+  }
+  fileFor(id) {
+    return new FileJsonlFile(this.pathFor(id));
+  }
+  create(options = {}) {
+    const id = options.id ?? createSessionId();
+    const storage = JsonlSessionStorage.create(this.fileFor(id), {
+      cwd: options.cwd,
+      sessionId: id,
+      parentSessionId: options.parentSessionId
+    });
+    return new Session(storage);
+  }
+  open(id) {
+    if (!existsSync(this.pathFor(id))) {
+      throw new SessionError("not_found", `Session not found: ${id}`);
+    }
+    return new Session(JsonlSessionStorage.open(this.fileFor(id)));
+  }
+  list() {
+    let names;
+    try {
+      names = readdirSync(this.root);
+    } catch (error) {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    }
+    const sessions = [];
+    for (const name of names) {
+      if (!name.endsWith(".jsonl")) continue;
+      const path = join2(this.root, name);
+      try {
+        const storage = JsonlSessionStorage.open(new FileJsonlFile(path));
+        const metadata = storage.getMetadata();
+        sessions.push({
+          id: metadata.id,
+          path,
+          cwd: metadata.cwd,
+          name: new Session(storage).buildContext().sessionName,
+          parentSessionId: metadata.parentSessionId,
+          createdAt: metadata.timestamp,
+          updatedAt: statSync(path).mtimeMs
+        });
+      } catch (error) {
+        if (error instanceof SessionError) continue;
+        throw error;
+      }
+    }
+    sessions.sort((a, b) => b.createdAt - a.createdAt);
+    return sessions;
+  }
+  delete(id) {
+    rmSync(this.pathFor(id), { force: true });
+  }
+  fork(id, options = {}) {
+    const source = this.open(id);
+    const forkedEntries = entriesToFork(source.getStorage(), options);
+    const newId = options.id ?? createSessionId();
+    const created = JsonlSessionStorage.create(this.fileFor(newId), {
+      cwd: options.cwd ?? source.getMetadata().cwd,
+      sessionId: newId,
+      parentSessionId: options.parentSessionId ?? id
+    });
+    for (const entry of forkedEntries) created.appendEntry(entry);
+    return new Session(JsonlSessionStorage.open(this.fileFor(newId)));
+  }
+};
+
+// src/env.ts
+import { spawn } from "child_process";
+import { constants } from "fs";
+import { access as access2, appendFile, mkdir, readFile as readFile4, readdir as readdir2, rm, writeFile } from "fs/promises";
+import { isAbsolute, relative, resolve } from "path";
+
+// src/shell-blocklist.ts
+var RULES = [
+  // POSIX recursive force-delete of a root-ish *whole* path argument:
+  // the filesystem root (`/`, `/*`), home (`~`, `~/`, `~/*`, `$HOME...`), or the
+  // bare current directory (`.`, `./`, `./*`). A named subdirectory such as
+  // `./build` or `~/Downloads` is intentionally allowed.
+  {
+    pattern: /\brm\s+(-[a-z]*\s+)*-[a-z]*r[a-z]*f[a-z]*\b[^\n]*?(\s|^)(\/\*?|~\/?\*?|\$HOME\/?\*?|\.\/?\*?)(\s|$)/i,
+    reason: "Recursive force-delete of a root, home, or current-directory path"
+  },
+  // POSIX rm with -rf in either flag order targeting the bare filesystem root.
+  {
+    pattern: /\brm\b[^\n]*\s-[a-z]*[rf][a-z]*[rf][a-z]*[^\n]*\s\/\*?(\s|$)/i,
+    reason: "Recursive force-delete of the filesystem root"
+  },
+  // Windows: rmdir/rd /s recursive removal of a drive root or profile.
+  {
+    pattern: /\b(rmdir|rd)\b[^\n]*\/s[^\n]*\s([a-z]:\\?|%userprofile%|%homedrive%)/i,
+    reason: "Recursive removal of a drive root or user profile"
+  },
+  // Windows: del /s /q against a drive root.
+  {
+    pattern: /\bdel\b[^\n]*\/s[^\n]*\s([a-z]:\\?\*?|%userprofile%)/i,
+    reason: "Recursive delete of a drive root or user profile"
+  },
+  // PowerShell: Remove-Item -Recurse -Force on a root/profile path.
+  {
+    pattern: /\bremove-item\b[^\n]*(-recurse|-force)[^\n]*\s([a-z]:\\?|\$env:userprofile|~)/i,
+    reason: "Recursive Remove-Item on a drive root or user profile"
+  },
+  // Fork bomb (POSIX function-style and bare).
+  { pattern: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, reason: "Shell fork bomb" },
+  // Overwrite a raw block device / partition table.
+  {
+    pattern: /\bdd\b[^\n]*\bof=\/dev\/(sd|nvme|hd|disk|vd)[a-z0-9]*/i,
+    reason: "Raw write to a block device with dd"
+  },
+  // mkfs against a real device.
+  {
+    pattern: /\bmkfs(\.[a-z0-9]+)?\b[^\n]*\/dev\/(sd|nvme|hd|disk|vd)[a-z0-9]*/i,
+    reason: "Formatting a block device with mkfs"
+  },
+  // Windows format of a drive (non-interactive).
+  { pattern: /\bformat\b[^\n]*\s[a-z]:[^\n]*\/(y|q|fs:)/i, reason: "Formatting a Windows drive" },
+  // Redirect to a raw disk device.
+  {
+    pattern: />\s*\/dev\/(sd|nvme|hd|disk|vd)[a-z0-9]*/i,
+    reason: "Redirecting output onto a block device"
+  },
+  // chmod/chown -R on a root path.
+  {
+    pattern: /\b(chmod|chown)\b[^\n]*\s-[a-z]*r[a-z]*\b[^\n]*\s\/(\s|$)/i,
+    reason: "Recursive permission/ownership change on the filesystem root"
+  },
+  // Piping a remote script straight into a shell.
+  {
+    pattern: /\b(curl|wget)\b[^\n|]*\|[^\n]*\b(sh|bash|zsh|powershell|pwsh|iex)\b/i,
+    reason: "Piping a remote download directly into a shell"
+  },
+  // PowerShell download-and-execute via Invoke-Expression.
+  {
+    pattern: /\b(iex|invoke-expression)\b[^\n]*\b(invoke-webrequest|iwr|downloadstring|net\.webclient)\b/i,
+    reason: "Downloading and executing a remote script in PowerShell"
+  },
+  // Disk wipe via cipher /w (Windows) over a drive.
+  { pattern: /\bcipher\b[^\n]*\/w:[a-z]:/i, reason: "Secure-wiping free space on a drive" }
+];
+function matchBlocklist(command) {
+  const normalized = command.trim();
+  for (const rule of RULES) {
+    if (rule.pattern.test(normalized)) {
+      return { reason: rule.reason, pattern: rule.pattern.source };
+    }
+  }
+  return void 0;
+}
+function isBlockedCommand(command) {
+  return matchBlocklist(command) !== void 0;
+}
+
+// src/env.ts
+function isNodeError(value) {
+  return value instanceof Error && "code" in value;
+}
+function toFileError(error, path) {
+  if (error instanceof FileError) return error;
+  const cause = toError(error);
+  if (isNodeError(error)) {
+    switch (error.code) {
+      case "ABORT_ERR":
+        return new FileError("aborted", cause.message, path, cause);
+      case "ENOENT":
+        return new FileError("not_found", cause.message, path, cause);
+      case "EACCES":
+      case "EPERM":
+        return new FileError("permission_denied", cause.message, path, cause);
+      case "ENOTDIR":
+        return new FileError("not_directory", cause.message, path, cause);
+      case "EISDIR":
+        return new FileError("is_directory", cause.message, path, cause);
+      case "EINVAL":
+        return new FileError("invalid", cause.message, path, cause);
+    }
+  }
+  return new FileError("unknown", cause.message, path, cause);
+}
+function killTree(pid) {
+  if (process.platform === "win32") {
+    try {
+      spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+    } catch {
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+}
+async function pathExists(path) {
+  try {
+    await access2(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveShell(customShellPath) {
+  if (customShellPath) {
+    if (await pathExists(customShellPath)) return ok({ shell: customShellPath, args: ["-c"] });
+    return err(
+      new ExecutionError("shell_unavailable", `Custom shell not found: ${customShellPath}`)
+    );
+  }
+  if (process.platform === "win32") {
+    const candidates = [];
+    const programFiles = process.env.ProgramFiles;
+    if (programFiles) candidates.push(`${programFiles}\\Git\\bin\\bash.exe`);
+    const programFilesX86 = process.env["ProgramFiles(x86)"];
+    if (programFilesX86) candidates.push(`${programFilesX86}\\Git\\bin\\bash.exe`);
+    for (const candidate of candidates) {
+      if (await pathExists(candidate)) return ok({ shell: candidate, args: ["-c"] });
+    }
+    const comspec = process.env.ComSpec ?? "cmd.exe";
+    return ok({ shell: comspec, args: ["/d", "/s", "/c"] });
+  }
+  if (await pathExists("/bin/bash")) return ok({ shell: "/bin/bash", args: ["-c"] });
+  return ok({ shell: "sh", args: ["-c"] });
+}
+async function detectShell(customShellPath) {
+  const resolved = await resolveShell(customShellPath);
+  const shell = resolved.ok ? resolved.value.shell : process.platform === "win32" ? process.env.ComSpec ?? "cmd.exe" : "sh";
+  let kind = "sh";
+  if (/bash(\.exe)?$/i.test(shell)) kind = "bash";
+  else if (/cmd\.exe$/i.test(shell) || shell.toLowerCase() === "cmd") kind = "cmd";
+  return { shell, kind };
+}
+var NodeExecutionEnv = class {
+  cwd;
+  shellPath;
+  shellEnv;
+  /** When true (default), the shell blocklist rejects dangerous commands. */
+  enforceBlocklist;
+  /**
+   * When true (default false), {@link writeTextFile} and {@link appendTextFile}
+   * reject any path that resolves outside {@link workspaceRoot}. Off by default
+   * so the write-anywhere behavior is unchanged unless explicitly opted in.
+   */
+  restrictWritesToWorkspace;
+  /** The boundary used when {@link restrictWritesToWorkspace} is on. */
+  workspaceRoot;
+  constructor(options) {
+    this.cwd = options.cwd;
+    this.shellPath = options.shellPath;
+    this.shellEnv = options.shellEnv;
+    this.enforceBlocklist = options.enforceBlocklist ?? true;
+    this.restrictWritesToWorkspace = options.restrictWritesToWorkspace ?? false;
+    this.workspaceRoot = options.workspaceRoot ?? options.cwd;
+  }
+  resolvePath(path) {
+    return isAbsolute(path) ? path : resolve(this.cwd, path);
+  }
+  /**
+   * Guard a mutating write when {@link restrictWritesToWorkspace} is on: returns
+   * a {@link FileError} when `resolved` falls outside {@link workspaceRoot}, else
+   * `undefined`. Inside/outside is computed with `path.relative` (NOT naive
+   * string prefixing, which mis-classifies `/work2` against `/work`): a path is
+   * inside iff the relative path is empty, is not absolute, and does not begin
+   * with a `..` segment. `path.relative` already normalizes separators and
+   * Windows drive-letter casing, so a cross-drive or traversal escape resolves
+   * to an absolute (or `..`-leading) relative path and is rejected.
+   */
+  workspaceWriteError(resolved) {
+    if (!this.restrictWritesToWorkspace) return void 0;
+    const rel = relative(this.workspaceRoot, resolved);
+    const escapes = rel === ".." || /^\.\.[/\\]/.test(rel);
+    const inside = rel === "" || !isAbsolute(rel) && !escapes;
+    if (inside) return void 0;
+    return new FileError(
+      "permission_denied",
+      `Refusing to write outside the workspace root (${this.workspaceRoot}): ${resolved}`,
+      resolved
+    );
+  }
+  async readTextFile(path, signal) {
+    const resolved = this.resolvePath(path);
+    if (signal?.aborted) return err(new FileError("aborted", "aborted", resolved));
+    try {
+      return ok(await readFile4(resolved, { encoding: "utf8", signal }));
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async readBinaryFile(path, signal) {
+    const resolved = this.resolvePath(path);
+    if (signal?.aborted) return err(new FileError("aborted", "aborted", resolved));
+    try {
+      const buf = await readFile4(resolved, { signal });
+      return ok(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async writeTextFile(path, content, signal) {
+    const resolved = this.resolvePath(path);
+    if (signal?.aborted) return err(new FileError("aborted", "aborted", resolved));
+    const boundary = this.workspaceWriteError(resolved);
+    if (boundary) return err(boundary);
+    try {
+      await mkdir(resolve(resolved, ".."), { recursive: true });
+      await writeFile(resolved, content, { signal });
+      return ok(void 0);
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async appendTextFile(path, content) {
+    const resolved = this.resolvePath(path);
+    const boundary = this.workspaceWriteError(resolved);
+    if (boundary) return err(boundary);
+    try {
+      await mkdir(resolve(resolved, ".."), { recursive: true });
+      await appendFile(resolved, content);
+      return ok(void 0);
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async exists(path) {
+    return pathExists(this.resolvePath(path));
+  }
+  async listDir(path) {
+    const resolved = this.resolvePath(path);
+    try {
+      return ok(await readdir2(resolved));
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async createDir(path, options) {
+    const resolved = this.resolvePath(path);
+    const boundary = this.workspaceWriteError(resolved);
+    if (boundary) return err(boundary);
+    try {
+      await mkdir(resolved, { recursive: options?.recursive ?? true });
+      return ok(void 0);
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async remove(path, options) {
+    const resolved = this.resolvePath(path);
+    const boundary = this.workspaceWriteError(resolved);
+    if (boundary) return err(boundary);
+    try {
+      await rm(resolved, {
+        recursive: options?.recursive ?? false,
+        force: options?.force ?? false
+      });
+      return ok(void 0);
+    } catch (error) {
+      return err(toFileError(error, resolved));
+    }
+  }
+  async exec(command, options) {
+    if (this.enforceBlocklist) {
+      const blocked = matchBlocklist(command);
+      if (blocked) {
+        return err(new ExecutionError("blocked", `Command blocked: ${blocked.reason}`));
+      }
+    }
+    if (options?.signal?.aborted) return err(new ExecutionError("aborted", "aborted"));
+    const shellConfig = await resolveShell(this.shellPath);
+    if (!shellConfig.ok) return shellConfig;
+    const cwd = options?.cwd ? this.resolvePath(options.cwd) : this.cwd;
+    return new Promise((resolvePromise) => {
+      let stdout = "";
+      let stderr = "";
+      let settled = false;
+      let timedOut = false;
+      let callbackError;
+      let child;
+      let timer;
+      const onAbort = () => {
+        if (child?.pid) killTree(child.pid);
+      };
+      const settle = (result) => {
+        if (timer) clearTimeout(timer);
+        options?.signal?.removeEventListener("abort", onAbort);
+        if (settled) return;
+        settled = true;
+        resolvePromise(result);
+      };
+      try {
+        child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
+          cwd,
+          detached: process.platform !== "win32",
+          env: { ...process.env, ...this.shellEnv, ...options?.env },
+          stdio: ["ignore", "pipe", "pipe"],
+          windowsHide: true
+        });
+      } catch (error) {
+        const cause = toError(error);
+        settle(err(new ExecutionError("spawn_error", cause.message, cause)));
+        return;
+      }
+      if (typeof options?.timeoutMs === "number") {
+        timer = setTimeout(() => {
+          timedOut = true;
+          if (child?.pid) killTree(child.pid);
+        }, options.timeoutMs);
+      }
+      if (options?.signal) {
+        if (options.signal.aborted) onAbort();
+        else options.signal.addEventListener("abort", onAbort, { once: true });
+      }
+      child.stdout?.setEncoding("utf8");
+      child.stderr?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk;
+        try {
+          options?.onStdout?.(chunk);
+        } catch (error) {
+          callbackError = new ExecutionError("callback_error", toError(error).message, error);
+          onAbort();
+        }
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk;
+        try {
+          options?.onStderr?.(chunk);
+        } catch (error) {
+          callbackError = new ExecutionError("callback_error", toError(error).message, error);
+          onAbort();
+        }
+      });
+      child.on("error", (error) => {
+        settle(err(new ExecutionError("spawn_error", error.message, error)));
+      });
+      child.on("close", (code) => {
+        if (callbackError) return settle(err(callbackError));
+        if (timedOut) {
+          const message = typeof options?.timeoutMs === "number" ? `Command timed out after ${options.timeoutMs}ms` : "Command timed out";
+          return settle(err(new ExecutionError("timeout", message)));
+        }
+        if (options?.signal?.aborted) return settle(err(new ExecutionError("aborted", "aborted")));
+        settle(ok({ stdout, stderr, exitCode: code ?? 0 }));
+      });
+    });
+  }
+};
+var DEFAULT_MAX_OUTPUT_BYTES = 50 * 1024;
+async function executeShellWithCapture(env, command, options) {
+  const maxBytes = options?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const controller = new AbortController();
+  const onParentAbort = () => controller.abort();
+  if (options?.signal) {
+    if (options.signal.aborted) controller.abort();
+    else options.signal.addEventListener("abort", onParentAbort, { once: true });
+  }
+  const timer = typeof options?.timeoutMs === "number" ? setTimeout(() => controller.abort(), options.timeoutMs) : void 0;
+  try {
+    const result = await env.exec(command, {
+      cwd: options?.cwd,
+      env: options?.env,
+      timeoutMs: options?.timeoutMs,
+      signal: controller.signal
+    });
+    if (!result.ok) return result;
+    const truncate = (text) => {
+      if (Buffer.byteLength(text, "utf8") <= maxBytes) return { value: text, truncated: false };
+      const buffer = Buffer.from(text, "utf8");
+      const sliced = buffer.subarray(buffer.length - maxBytes).toString("utf8");
+      return { value: `[output truncated]
+${sliced}`, truncated: true };
+    };
+    const stdout = truncate(result.value.stdout);
+    const stderr = truncate(result.value.stderr);
+    return ok({
+      stdout: stdout.value,
+      stderr: stderr.value,
+      exitCode: result.value.exitCode,
+      truncated: stdout.truncated || stderr.truncated
+    });
+  } finally {
+    if (timer) clearTimeout(timer);
+    options?.signal?.removeEventListener("abort", onParentAbort);
+  }
+}
+
+// src/conversation.ts
+import {
+  appendFileSync as appendFileSync2,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  rmSync as rmSync2,
+  writeFileSync
+} from "fs";
+import { dirname as dirname3, join as join4 } from "path";
+import { parse as yamlParse2, stringify as yamlStringify } from "yaml";
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+function generateConversationId() {
+  return uuidv7();
+}
+function getConversationDir() {
+  const dir = join4(process.cwd(), "conversations");
+  try {
+    mkdirSync2(dir, { recursive: true });
+  } catch {
+  }
+  return dir;
+}
+function contentToString(content) {
+  if (typeof content === "string") return content;
+  if (content === null || content === void 0) return "";
+  return JSON.stringify(content);
+}
+var Conversation = class _Conversation {
+  id;
+  name;
+  systemPrompt;
+  timeEnabled;
+  autosave;
+  saveFilepath;
+  loadFilepath;
+  contextLength;
+  rules;
+  customRulesPrompt;
+  user;
+  saveAsYamlOn;
+  saveAsJsonBool;
+  tokenCount;
+  messageIdOn;
+  tokenizerModelName;
+  conversationsDir;
+  exportMethod;
+  dynamicContextWindow;
+  caching;
+  outputMetadata;
+  memoryMdPath;
+  conversationHistory = [];
+  countTokens;
+  strCache = null;
+  cacheHits = 0;
+  cacheMisses = 0;
+  lastCachedTokens = 0;
+  suppressMemoryMd = true;
+  constructor(options = {}) {
+    this.id = options.id ?? generateConversationId();
+    this.name = options.name ?? this.id;
+    this.systemPrompt = options.systemPrompt;
+    this.timeEnabled = options.timeEnabled ?? false;
+    this.autosave = options.autosave ?? false;
+    this.saveFilepath = options.saveFilepath;
+    this.loadFilepath = options.loadFilepath;
+    this.contextLength = options.contextLength ?? 8192;
+    this.rules = options.rules;
+    this.customRulesPrompt = options.customRulesPrompt;
+    this.user = options.user ?? "User";
+    this.saveAsYamlOn = options.saveAsYamlOn ?? false;
+    this.saveAsJsonBool = options.saveAsJsonBool ?? false;
+    this.tokenCount = options.tokenCount ?? false;
+    this.messageIdOn = options.messageIdOn ?? false;
+    this.tokenizerModelName = options.tokenizerModelName ?? "gpt-4";
+    this.conversationsDir = options.conversationsDir;
+    this.exportMethod = options.exportMethod ?? "json";
+    this.dynamicContextWindow = options.dynamicContextWindow ?? true;
+    this.caching = options.cacheEnabled ?? false;
+    this.outputMetadata = options.outputMetadata ?? false;
+    this.memoryMdPath = options.memoryMdPath;
+    this.countTokens = options.countTokens ?? estimateTokens;
+    if (this.exportMethod !== "json" && this.exportMethod !== "yaml") {
+      throw new Error(`Invalid exportMethod: ${this.exportMethod}. Must be 'json' or 'yaml'`);
+    }
+    if (!this.saveFilepath) {
+      const ext = this.exportMethod === "json" ? ".json" : ".yaml";
+      this.saveFilepath = `conversation_${this.name}${ext}`;
+    }
+    this.initializeNewConversation();
+    this.suppressMemoryMd = false;
+    if (this.memoryMdPath) {
+      this.initMemoryMd();
+      this.preloadMemoryMd();
+    }
+  }
+  initializeNewConversation() {
+    if (this.systemPrompt !== void 0) this.add("System", this.systemPrompt);
+    if (this.rules !== void 0) this.add(this.user || "User", this.rules);
+    if (this.customRulesPrompt !== void 0) this.add(this.user || "User", this.customRulesPrompt);
+  }
+  // ── Core mutations ──────────────────────────────────────────────────────
+  /** Append a message to the in-memory transcript (no MEMORY.md / autosave). */
+  addInMemory(role, content, category) {
+    const message = { role, content };
+    if (this.timeEnabled) message.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    if (this.messageIdOn) message.message_id = uuidv7();
+    if (category) message.category = category;
+    this.conversationHistory.push(message);
+    this.strCache = null;
+    if (this.memoryMdPath) this.appendToMemoryMd(role, content);
+    if (this.tokenCount) {
+      message.token_count = this.countTokens(contentToString(content), this.tokenizerModelName);
+    }
+    return message;
+  }
+  /** Append a message; honors autosave. The primary write entrypoint. */
+  add(role, content, _metadata, category) {
+    const result = this.addInMemory(role, content, category);
+    if (this.autosave) this.export();
+    return result;
+  }
+  /** Append multiple messages in order (roles and contents must be equal length). */
+  addMultiple(roles, contents) {
+    if (roles.length !== contents.length) {
+      throw new Error("Number of roles and contents must match.");
+    }
+    return roles.map((role, i) => this.add(role, contents[i]));
+  }
+  /** Alias of {@link addMultiple} that also honors autosave once. */
+  addMultipleMessages(roles, contents) {
+    const added = this.addMultiple(roles, contents);
+    if (this.autosave) this.export();
+    return added;
+  }
+  /** Append pre-built message objects directly. */
+  batchAdd(messages) {
+    this.conversationHistory.push(...messages);
+    this.strCache = null;
+  }
+  /** Append a tool's output as a message under `role`. */
+  addToolOutputToAgent(role, toolOutput) {
+    return this.add(role, toolOutput);
+  }
+  /** Delete the message at `index`. */
+  delete(index) {
+    this.conversationHistory.splice(index, 1);
+    this.strCache = null;
+  }
+  /** Overwrite the role+content of the message at `index`. */
+  update(index, role, content) {
+    const i = Number(index);
+    if (i >= 0 && i < this.conversationHistory.length) {
+      const message = this.conversationHistory[i];
+      message.role = role;
+      message.content = content;
+      this.strCache = null;
+    }
+  }
+  /** Return the message at `index`, or undefined. */
+  query(index) {
+    const i = Number(index);
+    if (i >= 0 && i < this.conversationHistory.length) return this.conversationHistory[i];
+    return void 0;
+  }
+  /** Remove every message. */
+  clear() {
+    this.conversationHistory = [];
+    this.strCache = null;
+  }
+  /** Alias of {@link clear}. */
+  clearMemory() {
+    this.clear();
+  }
+  // ── Search ──────────────────────────────────────────────────────────────
+  /** Return messages whose stringified content contains `keyword`. */
+  search(keyword) {
+    return this.conversationHistory.filter((m) => contentToString(m.content).includes(keyword));
+  }
+  /** Alias of {@link search}. */
+  searchKeywordInConversation(keyword) {
+    return this.search(keyword);
+  }
+  /** Filter messages visible to `agentName` at/before `turn`. */
+  getVisibleMessages(agentName, turn) {
+    const prev = this.conversationHistory.filter(
+      (m) => typeof m.turn === "number" && m.turn < turn
+    );
+    return prev.filter((m) => {
+      const visibleTo = m.visible_to;
+      return visibleTo === "all" || Array.isArray(visibleTo) && visibleTo.includes(agentName);
+    });
+  }
+  /** Count messages per role. */
+  countMessagesByRole() {
+    const counts = { system: 0, user: 0, assistant: 0, function: 0 };
+    for (const message of this.conversationHistory) {
+      counts[message.role] = (counts[message.role] ?? 0) + 1;
+    }
+    return counts;
+  }
+  // ── Read / format ─────────────────────────────────────────────────────────
+  /** Return the transcript as a single `role: content` string (with caching). */
+  returnHistoryAsString() {
+    if (!this.caching) return this.buildHistoryString();
+    if (this.strCache === null) {
+      this.cacheMisses += 1;
+      this.strCache = this.buildHistoryString();
+      this.lastCachedTokens = this.countTokens(this.strCache, this.tokenizerModelName);
+    } else {
+      this.cacheHits += 1;
+    }
+    return this.strCache;
+  }
+  /** Alias of {@link returnHistoryAsString}. */
+  getStr() {
+    return this.returnHistoryAsString();
+  }
+  buildHistoryString() {
+    if (this.dynamicContextWindow) return this.dynamicAutoChunking();
+    return this.historyStringWorker();
+  }
+  historyStringWorker() {
+    return this.conversationHistory.map((m) => {
+      const content = contentToString(m.content);
+      return m.timestamp ? `[${m.timestamp}] ${m.role}: ${content}` : `${m.role}: ${content}`;
+    }).join("\n\n");
+  }
+  /** Cache stats for {@link returnHistoryAsString}. */
+  getCacheStats() {
+    const total = this.cacheHits + this.cacheMisses;
+    return {
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      cachedTokens: this.lastCachedTokens,
+      hitRate: total > 0 ? this.cacheHits / total : 0
+    };
+  }
+  /** The raw transcript array — the canonical serialized form. */
+  toDict() {
+    return this.conversationHistory;
+  }
+  /** The transcript as a list (alias of {@link toDict}). */
+  toList() {
+    return this.conversationHistory;
+  }
+  /** The transcript serialized to a JSON string. */
+  toJson() {
+    return JSON.stringify(this.conversationHistory);
+  }
+  /** The transcript serialized to a YAML string. */
+  toYaml() {
+    return yamlStringify(this.conversationHistory);
+  }
+  /** Each message as a `role: content` string. */
+  returnMessagesAsList() {
+    return this.conversationHistory.map((m) => `${m.role}: ${contentToString(m.content)}`);
+  }
+  /** Canonical provider format: `[{role, content}]`. */
+  returnMessagesAsDictionary() {
+    return this.conversationHistory.map((m) => ({ role: m.role, content: m.content }));
+  }
+  /** Provider format serialized to a pretty JSON string. */
+  returnJson() {
+    return JSON.stringify(this.returnMessagesAsDictionary(), null, 4);
+  }
+  /** The last message as `role: content`, or "". */
+  getLastMessageAsString() {
+    const last = this.conversationHistory.at(-1);
+    return last ? `${last.role}: ${contentToString(last.content)}` : "";
+  }
+  /** The final message as `role: content`, or "". */
+  getFinalMessage() {
+    return this.getLastMessageAsString();
+  }
+  /** The content of the final message, or "". */
+  getFinalMessageContent() {
+    const last = this.conversationHistory.at(-1);
+    return last ? last.content : "";
+  }
+  /** Final message content as a `[role, content]` 2-tuple. */
+  returnDictFinal() {
+    const last = this.conversationHistory.at(-1);
+    const content = last ? last.content : "";
+    return [content, content];
+  }
+  /** Final message content wrapped in a single-element list. */
+  returnListFinal() {
+    const last = this.conversationHistory.at(-1);
+    return [last ? last.content : ""];
+  }
+  /** All messages except the first two (system + first user). */
+  returnAllExceptFirst() {
+    return this.conversationHistory.slice(2);
+  }
+  /** {@link returnAllExceptFirst} rendered as a newline-joined content string. */
+  returnAllExceptFirstString() {
+    return this.conversationHistory.slice(2).map((m) => contentToString(m.content)).join("\n");
+  }
+  // ── Persistence ───────────────────────────────────────────────────────────
+  /** Save the transcript to `saveFilepath` as JSON. */
+  saveAsJson(force = true) {
+    if (!this.autosave && !force) return;
+    if (!this.saveFilepath) {
+      this.saveFilepath = join4(
+        this.conversationsDir ?? process.cwd(),
+        `conversation_${this.id}.json`
+      );
+    }
+    const dir = dirname3(this.saveFilepath);
+    if (dir) mkdirSync2(dir, { recursive: true });
+    writeFileSync(this.saveFilepath, JSON.stringify(this.conversationHistory, null, 4), "utf-8");
+  }
+  /** Save the transcript to `saveFilepath` as YAML. */
+  saveAsYaml(force = true) {
+    if (!this.autosave && !force) return;
+    if (!this.saveFilepath) {
+      this.saveFilepath = join4(
+        this.conversationsDir ?? process.cwd(),
+        `conversation_${this.id}.yaml`
+      );
+    }
+    const dir = dirname3(this.saveFilepath);
+    if (dir) mkdirSync2(dir, { recursive: true });
+    writeFileSync(this.saveFilepath, yamlStringify(this.conversationHistory), "utf-8");
+  }
+  /** Save using the configured `exportMethod`. */
+  export(force = true) {
+    if (this.exportMethod === "json") this.saveAsJson(force);
+    else this.saveAsYaml(force);
+  }
+  /** Load the transcript from a JSON file. */
+  loadFromJson(filename) {
+    if (!existsSync2(filename)) return;
+    const data = JSON.parse(readFileSync2(filename, "utf-8"));
+    this.conversationHistory = Array.isArray(data) ? data : data.conversation_history ?? [];
+    this.strCache = null;
+  }
+  /** Load the transcript from a YAML file. */
+  loadFromYaml(filename) {
+    if (!existsSync2(filename)) return;
+    const data = yamlParse2(readFileSync2(filename, "utf-8"));
+    this.conversationHistory = Array.isArray(data) ? data : data?.conversation_history ?? [];
+    this.strCache = null;
+  }
+  /** Load the transcript, dispatching on file extension. */
+  load(filename) {
+    if (!existsSync2(filename)) return;
+    const lower = filename.toLowerCase();
+    if (lower.endsWith(".json")) this.loadFromJson(filename);
+    else if (lower.endsWith(".yaml") || lower.endsWith(".yml")) this.loadFromYaml(filename);
+    else throw new Error(`Unsupported file format: ${filename}. Must be .json, .yaml, or .yml`);
+  }
+  /** Export the transcript to `filename` (JSON for `.json`, plain text otherwise). */
+  exportConversation(filename) {
+    if (filename.endsWith(".json")) {
+      const dir = dirname3(filename);
+      if (dir) mkdirSync2(dir, { recursive: true });
+      writeFileSync(filename, JSON.stringify(this.conversationHistory, null, 4), "utf-8");
+    } else {
+      const text = this.conversationHistory.map((m) => `${m.role}: ${contentToString(m.content)}`).join("\n");
+      writeFileSync(filename, `${text}
+`, "utf-8");
+    }
+  }
+  /** Import a transcript from a JSON file. */
+  importConversation(filename) {
+    this.loadFromJson(filename);
+  }
+  // ── Token management ──────────────────────────────────────────────────────
+  /** Truncate, from the front, the rendered history so it fits `contextLength`. */
+  dynamicAutoChunking() {
+    try {
+      return this.dynamicAutoChunkingWorker();
+    } catch {
+      return this.historyStringWorker();
+    }
+  }
+  dynamicAutoChunkingWorker() {
+    const all = this.historyStringWorker();
+    if (this.countTokens(all, this.tokenizerModelName) <= this.contextLength) return all;
+    const target = this.contextLength;
+    let left = 0;
+    let right = all.length;
+    let current = all;
+    while (left < right) {
+      const mid = Math.floor((left + right) / 2);
+      const test = all.slice(mid);
+      if (!test) break;
+      if (this.countTokens(test, this.tokenizerModelName) <= target) {
+        right = mid;
+        current = test;
+      } else {
+        left = mid + 1;
+      }
+    }
+    return current;
+  }
+  /** Truncate the transcript message-by-message until it fits `contextLength`. */
+  truncateMemoryWithTokenizer() {
+    let totalTokens = 0;
+    const truncated = [];
+    for (const message of this.conversationHistory) {
+      const content = contentToString(message.content);
+      const tokenCount = this.countTokens(content, this.tokenizerModelName);
+      if (totalTokens + tokenCount <= this.contextLength) {
+        truncated.push(message);
+        totalTokens += tokenCount;
+      } else {
+        const remaining = this.contextLength - totalTokens;
+        if (remaining <= 0) break;
+        const truncatedContent = this.binarySearchTruncate(
+          content,
+          remaining,
+          this.tokenizerModelName
+        );
+        truncated.push({ ...message, content: truncatedContent });
+        break;
+      }
+    }
+    this.conversationHistory = truncated;
+    this.strCache = null;
+  }
+  /** Binary-search the longest prefix of `text` fitting `targetTokens`. */
+  binarySearchTruncate(text, targetTokens, modelName) {
+    if (!text || targetTokens <= 0) return "";
+    if (this.countTokens(text, modelName) <= targetTokens) return text;
+    let left = 0;
+    let right = text.length;
+    let best = "";
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2);
+      const candidate = text.slice(0, mid);
+      if (this.countTokens(candidate, modelName) <= targetTokens) {
+        best = candidate;
+        left = mid + 1;
+      } else {
+        right = mid - 1;
+      }
+    }
+    for (const delimiter of [".", "!", "?", "\n"]) {
+      const lastPos = best.lastIndexOf(delimiter);
+      if (lastPos > best.length * 0.75) {
+        const atSentence = best.slice(0, lastPos + 1);
+        if (this.countTokens(atSentence, modelName) <= targetTokens) return atSentence;
+      }
+    }
+    return best;
+  }
+  /** Sum tokens for messages tagged `category: "input"` / `"output"`. */
+  exportAndCountCategories() {
+    const inputs = [];
+    const outputs = [];
+    for (const message of this.conversationHistory) {
+      const content = contentToString(message.content);
+      if (message.category === "input") inputs.push(content);
+      else if (message.category === "output") outputs.push(content);
+    }
+    const inputText = inputs.join(" ");
+    const outputText = outputs.join(" ");
+    const inputTokens = inputText.trim() ? this.countTokens(inputText, this.tokenizerModelName) : 0;
+    const outputTokens = outputText.trim() ? this.countTokens(outputText, this.tokenizerModelName) : 0;
+    return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+  }
+  // ── MEMORY.md durable persistence ─────────────────────────────────────────
+  initMemoryMd() {
+    if (!this.memoryMdPath) return;
+    const parent = dirname3(this.memoryMdPath);
+    if (parent) mkdirSync2(parent, { recursive: true });
+    if (!existsSync2(this.memoryMdPath)) {
+      const header = `# Agent Memory
+
+**Conversation:** ${this.name}
+**Created:** ${(/* @__PURE__ */ new Date()).toISOString()}
+
+---
+
+## Interaction Log
+
+`;
+      try {
+        writeFileSync(this.memoryMdPath, header, "utf-8");
+      } catch {
+      }
+    }
+  }
+  preloadMemoryMd() {
+    if (!this.memoryMdPath || !existsSync2(this.memoryMdPath)) return;
+    let content;
+    try {
+      content = readFileSync2(this.memoryMdPath, "utf-8");
+    } catch {
+      return;
+    }
+    if (!content.includes("### ")) return;
+    this.conversationHistory.push({
+      role: "System",
+      content: `[Persistent Memory \u2014 MEMORY.md]
+The following is this conversation's persistent memory from prior sessions. Use it to continue context coherently.
+
+${content}`
+    });
+    this.strCache = null;
+  }
+  appendToMemoryMd(role, content) {
+    if (this.suppressMemoryMd || !this.memoryMdPath) return;
+    if (content === null || content === void 0) return;
+    const contentStr = contentToString(content);
+    if (!contentStr.trim()) return;
+    const stamp = (/* @__PURE__ */ new Date()).toISOString();
+    const block = `### ${role} \u2014 ${stamp}
+
+${contentStr.trim()}
+
+---
+
+`;
+    try {
+      appendFileSync2(this.memoryMdPath, block, "utf-8");
+    } catch {
+    }
+  }
+  archiveMemoryMd() {
+    if (!this.memoryMdPath || !existsSync2(this.memoryMdPath)) return;
+    let content;
+    try {
+      content = readFileSync2(this.memoryMdPath, "utf-8");
+    } catch {
+      return;
+    }
+    if (!content.includes("### ")) return;
+    const agentDir = dirname3(this.memoryMdPath);
+    const archiveDir = join4(agentDir, "archive");
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const archivePath = join4(archiveDir, `history_${stamp}.md`);
+    try {
+      mkdirSync2(archiveDir, { recursive: true });
+      writeFileSync(archivePath, content, "utf-8");
+    } catch {
+    }
+  }
+  /**
+   * Collapse the interaction history into a single `summary`, preserving the
+   * static context (system prompt → rules → custom rules → summary). When
+   * MEMORY.md is configured it is archived, wiped, and re-seeded so the on-disk
+   * log stops growing across compactions.
+   */
+  compact(summary, summaryRole = "System") {
+    this.suppressMemoryMd = true;
+    try {
+      this.conversationHistory = [];
+      this.strCache = null;
+      if (this.systemPrompt !== void 0) {
+        this.conversationHistory.push({ role: "System", content: this.systemPrompt });
+      }
+      if (this.rules !== void 0) {
+        this.conversationHistory.push({ role: this.user || "User", content: this.rules });
+      }
+      if (this.customRulesPrompt !== void 0) {
+        this.conversationHistory.push({
+          role: this.user || "User",
+          content: this.customRulesPrompt
+        });
+      }
+    } finally {
+      this.suppressMemoryMd = false;
+    }
+    if (this.memoryMdPath) {
+      try {
+        this.archiveMemoryMd();
+        if (existsSync2(this.memoryMdPath)) rmSync2(this.memoryMdPath, { force: true });
+        this.initMemoryMd();
+      } catch {
+      }
+    }
+    this.add(summaryRole, summary);
+  }
+  // ── Class helpers ─────────────────────────────────────────────────────────
+  /** Load a conversation by name (or explicit file) from a directory. */
+  static loadConversation(name, conversationsDir, loadFilepath) {
+    if (loadFilepath) {
+      const conversation = new _Conversation({ name });
+      conversation.load(loadFilepath);
+      return conversation;
+    }
+    const dir = conversationsDir ?? getConversationDir();
+    for (const ext of [".json", ".yaml", ".yml"]) {
+      const filepath = join4(dir, `${name}${ext}`);
+      if (existsSync2(filepath)) {
+        const conversation = new _Conversation({ name, conversationsDir: dir });
+        conversation.load(filepath);
+        return conversation;
+      }
+    }
+    return new _Conversation({ name, conversationsDir: dir });
+  }
+};
+
+// src/output-formatter.ts
+import { stringify as yamlStringify2 } from "yaml";
+function escapeXml2(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function toXmlValue(value, indent) {
+  if (value === null || value === void 0) return "";
+  if (Array.isArray(value)) {
+    return value.map((item) => `${indent}<item>${toXmlValue(item, `${indent}  `)}</item>`).join("\n");
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    return `
+${entries.map(([k, v]) => `${indent}<${k}>${toXmlValue(v, `${indent}  `)}</${k}>`).join("\n")}
+${indent.slice(0, -2)}`;
+  }
+  return escapeXml2(String(value));
+}
+function toXmlString(messages) {
+  const body = messages.map((m) => `  <message>${toXmlValue(m, "    ")}</message>`).join("\n");
+  return `<conversation>
+${body}
+</conversation>`;
+}
+function historyOutputFormatter(conversation, type = "list") {
+  switch (type) {
+    case "list":
+      return conversation.returnMessagesAsList();
+    case "dict":
+    case "dictionary":
+      return conversation.toDict();
+    case "string":
+    case "str":
+      return conversation.getStr();
+    case "final":
+    case "last":
+      return conversation.getFinalMessageContent();
+    case "json":
+      return conversation.toJson();
+    case "all":
+      return conversation.getStr();
+    case "yaml":
+      return yamlStringify2(conversation.toDict());
+    case "xml":
+      return toXmlString(conversation.toDict());
+    case "dict-all-except-first":
+      return conversation.returnAllExceptFirst();
+    case "str-all-except-first":
+      return conversation.returnAllExceptFirstString();
+    case "dict-final":
+      return conversation.returnDictFinal();
+    case "list-final":
+      return conversation.returnListFinal();
+    case "basemodel":
+      return conversation.returnMessagesAsDictionary();
+    default: {
+      const _exhaustive = type;
+      void _exhaustive;
+      return conversation.returnMessagesAsList();
+    }
+  }
+}
+
+// src/serialization.ts
+import { mkdir as mkdir2, readFile as readFile5, rename, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname4 } from "path";
+function hasToDict(value) {
+  return typeof value === "object" && value !== null && typeof value.toDict === "function";
+}
+function isJsonSerializable(value) {
+  try {
+    JSON.stringify(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function serializeAttr(value) {
+  if (typeof value === "function") {
+    const fn = value;
+    return { name: fn.name || "anonymous", doc: null };
+  }
+  if (hasToDict(value)) {
+    return value.toDict();
+  }
+  if (isJsonSerializable(value)) {
+    return value;
+  }
+  const typeName = value && typeof value === "object" ? value.constructor?.name ?? "object" : typeof value;
+  return `<Non-serializable: ${typeName}>`;
+}
+function serializeState(obj, exclude = []) {
+  const excluded = new Set(exclude);
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (excluded.has(key)) continue;
+    result[key] = serializeAttr(value);
+  }
+  return result;
+}
+var SerializableMixin = class {
+  /** Field names to omit from `toDict()`. Override in subclasses. */
+  _toDictExclude = [];
+  /** Serialize this instance's own enumerable fields to a plain dictionary. */
+  toDict() {
+    return serializeState(this, this._toDictExclude);
+  }
+};
+var SAFE_PRIMITIVE = /* @__PURE__ */ new Set(["boolean", "number", "string"]);
+function isSafeType(value) {
+  if (value === null || value === void 0) return true;
+  const t = typeof value;
+  if (SAFE_PRIMITIVE.has(t)) return true;
+  if (Array.isArray(value)) return value.every(isSafeType);
+  if (t === "object") {
+    const obj = value;
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) return false;
+    return Object.entries(obj).every(([k, v]) => typeof k === "string" && isSafeType(v));
+  }
+  return false;
+}
+function isClassInstance(value) {
+  if (value === null || value === void 0) return false;
+  if (typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto !== Object.prototype && proto !== null;
+}
+function createStateDict(obj) {
+  const state = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith("_")) continue;
+    if (isSafeType(value)) state[key] = value;
+  }
+  return state;
+}
+function preserveInstances(obj) {
+  const preserved = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith("_")) continue;
+    if (isClassInstance(value)) preserved[key] = value;
+  }
+  return preserved;
+}
+var SafeStateManager = {
+  /**
+   * Atomically save the object's safe state to `filePath`.
+   *
+   * Writes a temp file, backs up any existing file, then renames the temp into
+   * place so a crash mid-write never corrupts the target.
+   */
+  async saveState(obj, filePath) {
+    const stateDict = createStateDict(obj);
+    const dir = dirname4(filePath);
+    if (dir) await mkdir2(dir, { recursive: true });
+    const tempPath = `${filePath}.tmp`;
+    const backupPath = `${filePath}.bak`;
+    await writeFile2(tempPath, JSON.stringify(stateDict, null, 2), "utf-8");
+    try {
+      await rename(filePath, backupPath);
+    } catch {
+    }
+    await rename(tempPath, filePath);
+    await rm2(backupPath, { force: true });
+  },
+  /**
+   * Load persisted safe state into `obj`, preserving any live class-instance
+   * fields the object already holds.
+   */
+  async loadState(obj, filePath) {
+    let raw;
+    try {
+      raw = await readFile5(filePath, "utf-8");
+    } catch {
+      throw new Error(`State file not found: ${filePath}`);
+    }
+    const preserved = preserveInstances(obj);
+    const stateDict = JSON.parse(raw);
+    for (const [key, value] of Object.entries(stateDict)) {
+      if (key.startsWith("_")) continue;
+      if (key in preserved) continue;
+      if (isSafeType(value)) obj[key] = value;
+    }
+    for (const [key, value] of Object.entries(preserved)) {
+      obj[key] = value;
+    }
+  }
+};
+
+// src/agent-errors.ts
+var AgentError = class extends Error {
+  /** Machine-readable, stable error code. */
+  code;
+  cause;
+  constructor(message, code = "agent", cause) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var AgentInitializationError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_initialization", cause);
+  }
+};
+var AgentRunError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_run", cause);
+  }
+};
+var AgentLLMError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_llm", cause);
+  }
+};
+var AgentToolError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_tool", cause);
+  }
+};
+var AgentMemoryError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_memory", cause);
+  }
+};
+var AgentMCPConnectionError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_mcp_connection", cause);
+  }
+};
+var AgentMCPToolError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_mcp_tool", cause);
+  }
+};
+
+// src/index.ts
+var PACKAGE = "@ap3x/agent-core";
+var VERSION = "0.1.0";
+export {
+  Agent,
+  AgentConfigSchema,
+  AgentError,
+  AgentHarness,
+  AgentHarnessError,
+  AgentInitializationError,
+  AgentLLMError,
+  AgentLoader,
+  AgentMCPConnectionError,
+  AgentMCPToolError,
+  AgentMemoryError,
+  AgentRegistry,
+  AgentRegistrySchema,
+  AgentRunError,
+  AgentSpecSchema,
+  AgentToolError,
+  Ap3xError,
+  Ap3xRuntimeBackend,
+  CompactionError,
+  Conversation,
+  DEFAULT_COMPACTION_SETTINGS,
+  DEFAULT_MAX_LOOPS,
+  ExecutionError,
+  FileError,
+  FileJsonlFile,
+  InMemorySessionStorage,
+  JsonlSessionRepo,
+  JsonlSessionStorage,
+  NodeExecutionEnv,
+  PACKAGE,
+  SUMMARIZATION_SYSTEM_PROMPT,
+  SYSTEM_PROMPT_SECTIONS,
+  SafeStateManager,
+  SerializableMixin,
+  Session,
+  SessionError,
+  SkillRegistry,
+  StringJsonlFile,
+  SystemPromptBuilder,
+  VERSION,
+  agentLoop,
+  agentLoopContinue,
+  assembleSystemPrompt,
+  availableParallelism,
+  buildSessionContext,
+  compact,
+  compactionTier,
+  createLimiter,
+  createRuntimeBackend,
+  createSessionId,
+  createStateDict,
+  defineTool,
+  detectShell,
+  discoverSkillFiles,
+  discoverSkills,
+  environmentSection,
+  err,
+  estimateContextTokens,
+  estimateMessageTokens,
+  estimateTokens,
+  executeShellWithCapture,
+  executeToolCalls,
+  finalTextOf,
+  findCutPoint,
+  formatSkillsForSystemPrompt,
+  generateConversationId,
+  getConversationDir,
+  getLogLevel,
+  getOrThrow,
+  getOrUndefined,
+  historyOutputFormatter,
+  isBlockedCommand,
+  isClassInstance,
+  isSafeType,
+  lastAssistant,
+  loadPromptTemplate,
+  loadSkill,
+  loadSkills,
+  logger,
+  mapLimit,
+  matchBlocklist,
+  ok,
+  parseCommandArgs,
+  parsePromptTemplate,
+  parseSkill,
+  parseYamlFrontmatter,
+  prepareCompaction,
+  preserveInstances,
+  producesContextMessage,
+  renderPromptTemplate,
+  resolveAutoCompact,
+  resolveCompactionSettings,
+  runAgentLoop,
+  runAgentLoopContinue,
+  serializeAttr,
+  serializeState,
+  setLogLevel,
+  shortId,
+  shouldCompact,
+  substituteArgs,
+  toError,
+  uuidv7
+};