@jussmor/sdk-ai 0.2.0

package/dist/index.js

@@ -0,0 +1,1536 @@
+// src/protocol.ts
+var PROTOCOL_VERSION = "1";
+
+// src/tool.ts
+function toToolDef(t) {
+  return {
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters
+    }
+  };
+}
+function scoreToolMatch(t, query) {
+  let score = 0;
+  if (t.name.toLowerCase().includes(query)) score += 0.6;
+  if (t.searchHint?.toLowerCase().includes(query)) score += 0.4;
+  if (t.description.toLowerCase().includes(query)) score += 0.3;
+  if (t.category.toLowerCase().includes(query)) score += 0.1;
+  if (t.aliases?.some((a) => a.toLowerCase().includes(query))) score += 0.2;
+  return score;
+}
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  aliases = /* @__PURE__ */ new Map();
+  register(tool) {
+    this.tools.set(tool.name, tool);
+    for (const alias of tool.aliases ?? []) {
+      const trimmed = alias.trim();
+      if (trimmed && trimmed !== tool.name) {
+        this.aliases.set(trimmed, tool.name);
+      }
+    }
+  }
+  get(name) {
+    return this.tools.get(name) ?? this.tools.get(this.aliases.get(name) ?? "");
+  }
+  list() {
+    return Array.from(this.tools.values());
+  }
+  byCategory(category) {
+    return this.list().filter((t) => t.category === category);
+  }
+  names() {
+    return Array.from(this.tools.keys()).sort();
+  }
+  describeAvailable() {
+    const tools = this.list().sort((a, b) => a.name.localeCompare(b.name));
+    if (tools.length === 0) return "- none";
+    const lines = tools.filter((t) => t.name.trim()).map((t) => {
+      const desc = t.description.trim();
+      return desc ? `- ${t.name}: ${desc}` : `- ${t.name}`;
+    });
+    return lines.length === 0 ? "- none" : lines.join("\n");
+  }
+  toolDefs() {
+    return this.list().filter((t) => !t.hidden && !t.deferred).map(toToolDef);
+  }
+  async collectDynamicReminders(signal) {
+    const tools = this.list().filter((t) => t.dynamicReminder != null).sort((a, b) => a.name.localeCompare(b.name));
+    const results = [];
+    for (const t of tools) {
+      const block = await t.dynamicReminder(signal);
+      if (block.trim()) results.push(block);
+    }
+    return results;
+  }
+  search(query) {
+    const q = query.toLowerCase().trim();
+    if (!q) return [];
+    return this.list().map((t) => ({ tool: t, score: scoreToolMatch(t, q) })).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
+  }
+  reveal(name) {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`tool "${name}" not found`);
+    tool.hidden = false;
+  }
+  hide(name) {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`tool "${name}" not found`);
+    tool.hidden = true;
+  }
+};
+
+// src/streaming.ts
+async function collectStream(events) {
+  let text = "";
+  let final;
+  let error;
+  for await (const ev of events) {
+    if (ev.type === "delta" && ev.delta) text += ev.delta;
+    if (ev.type === "done") final = ev.final;
+    if (ev.type === "error") error = ev.error;
+  }
+  return { text, final, error };
+}
+function fanOutStream(source, consumers) {
+  const queues = Array.from({ length: consumers }, () => []);
+  const resolvers = Array(consumers).fill(null);
+  let done = false;
+  void (async () => {
+    for await (const ev of source) {
+      for (let i = 0; i < consumers; i++) {
+        const resolve = resolvers[i];
+        if (resolve) {
+          resolvers[i] = null;
+          resolve({ value: ev, done: false });
+        } else {
+          queues[i].push(ev);
+        }
+      }
+    }
+    done = true;
+    for (let i = 0; i < consumers; i++) {
+      const resolve = resolvers[i];
+      if (resolve) {
+        resolvers[i] = null;
+        resolve({ value: void 0, done: true });
+      }
+    }
+  })();
+  return Array.from({ length: consumers }, (_, i) => {
+    return (async function* () {
+      while (true) {
+        const queued = queues[i].shift();
+        if (queued !== void 0) {
+          yield queued;
+          continue;
+        }
+        if (done) return;
+        const ev = await new Promise((resolve) => {
+          resolvers[i] = resolve;
+        });
+        if (ev.done) return;
+        yield ev.value;
+      }
+    })();
+  });
+}
+
+// src/conversation.ts
+function newConversation(id) {
+  return {
+    id,
+    messages: [],
+    memoryRead: false,
+    turnCount: 0,
+    createdAt: /* @__PURE__ */ new Date()
+  };
+}
+function isCold(conv) {
+  return conv.turnCount === 0;
+}
+function appendUser(conv, content) {
+  conv.messages.push({ role: "user", content });
+}
+function appendAssistant(conv, content) {
+  conv.messages.push({ role: "assistant", content });
+}
+function incrementTurn(conv) {
+  conv.turnCount++;
+  conv.lastTurnAt = /* @__PURE__ */ new Date();
+}
+function messageCount(conv) {
+  return conv.messages.length;
+}
+
+// src/mode.ts
+function isToolAllowed(mode, toolName) {
+  if (!mode.toolsMode || !mode.toolsList?.length) return true;
+  const listed = mode.toolsList.includes(toolName);
+  if (mode.toolsMode === "allowlist") return listed;
+  if (mode.toolsMode === "denylist") return !listed;
+  return true;
+}
+var StaticModeProvider = class {
+  modes;
+  modeList;
+  constructor(modes) {
+    this.modes = /* @__PURE__ */ new Map();
+    this.modeList = [];
+    for (const mode of modes) {
+      if (!mode.id) continue;
+      this.modes.set(mode.id, mode);
+      this.modeList.push(mode);
+    }
+  }
+  async get(modeId) {
+    const mode = this.modes.get(modeId);
+    if (!mode) throw new Error(`mode not found: ${modeId}`);
+    return mode;
+  }
+  async list() {
+    return this.modeList;
+  }
+  async create() {
+    throw new Error("mode creation not supported by static mode provider");
+  }
+  builtinModes() {
+    return [];
+  }
+};
+
+// src/memory.ts
+var DEFAULT_MEMORY_ROOTS = [
+  { scope: "user", path: "/", label: "User memory" },
+  { scope: "project", path: "/", label: "Project memory" }
+];
+
+// src/thread.ts
+var ErrThreadAccessDenied = new Error("thread: access denied");
+
+// src/artifact.ts
+var ARTIFACT_EMITTER_KEY = /* @__PURE__ */ Symbol("artifactEmitter");
+function withArtifactEmitter(ctx, emitter) {
+  return { ...ctx, [ARTIFACT_EMITTER_KEY]: emitter };
+}
+function emitArtifact(ctx, artifact) {
+  ctx[ARTIFACT_EMITTER_KEY]?.(artifact);
+}
+
+// src/interrupt.ts
+var InterruptGate = class {
+  requester;
+  pending = /* @__PURE__ */ new Map();
+  constructor(requester) {
+    this.requester = requester;
+  }
+  async wait(req, signal) {
+    this.pending.set(req.id, req);
+    try {
+      return await this.requester(req, signal);
+    } finally {
+      this.pending.delete(req.id);
+    }
+  }
+  pendingRequests() {
+    return Array.from(this.pending.values());
+  }
+};
+
+// src/safety.ts
+var DANGEROUS_PATTERNS = [
+  /rm\s+-rf\s+\/[^a-z]/i,
+  /curl.*\|\s*(?:bash|sh|python)/i,
+  /wget.*\|\s*(?:bash|sh|python)/i,
+  /mkfs/i,
+  /dd\s+if=/i,
+  />\s*\/dev\/sd[a-z]/i
+];
+var SECRET_PATTERNS = [
+  /sk-[a-zA-Z0-9]{20,}/,
+  /AKIA[0-9A-Z]{16}/,
+  /ghp_[a-zA-Z0-9]{36}/,
+  /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/,
+  /password\s*[:=]\s*['"][^'"]{8,}['"]/i
+];
+var DefaultSafetyFilter = class {
+  inspect(call) {
+    const args = call.arguments;
+    for (const pattern of DANGEROUS_PATTERNS) {
+      if (pattern.test(args)) {
+        return {
+          decision: "block",
+          reason: `dangerous command pattern detected: ${pattern.source}`
+        };
+      }
+    }
+    for (const pattern of SECRET_PATTERNS) {
+      if (pattern.test(args)) {
+        return {
+          decision: "block",
+          reason: "potential secret leak detected in tool arguments"
+        };
+      }
+    }
+    return { decision: "allow" };
+  }
+};
+
+// src/tracing.ts
+import { randomUUID } from "crypto";
+var Tracer = class {
+  _traceId;
+  spans = [];
+  stack = [];
+  constructor() {
+    this._traceId = randomUUID();
+  }
+  traceId() {
+    return this._traceId;
+  }
+  startSpan(name, attrs) {
+    const span = {
+      traceId: this._traceId,
+      spanId: randomUUID(),
+      parentId: this.stack[this.stack.length - 1],
+      name,
+      startedAt: /* @__PURE__ */ new Date(),
+      attrs
+    };
+    this.spans.push(span);
+    this.stack.push(span.spanId);
+    return span;
+  }
+  finishSpan(span, error) {
+    span.finishedAt = /* @__PURE__ */ new Date();
+    if (error) span.error = error.message;
+    const idx = this.stack.lastIndexOf(span.spanId);
+    if (idx !== -1) this.stack.splice(idx, 1);
+  }
+  allSpans() {
+    return this.spans.slice();
+  }
+};
+function withTracer(ctx, tracer) {
+  return { ...ctx, __tracer: tracer };
+}
+function tracerFromContext(ctx) {
+  return ctx.__tracer;
+}
+
+// src/tokenizer.ts
+var HeuristicTokenizer = class {
+  count(text) {
+    return Math.ceil(text.length / 4);
+  }
+  encode(_text) {
+    return [];
+  }
+  decode(_tokens) {
+    return "";
+  }
+};
+function truncateToTokens(text, maxTokens, tok) {
+  if (tok.count(text) <= maxTokens) return text;
+  const tokens = tok.encode(text);
+  if (tokens.length > 0 && tokens.length > maxTokens) {
+    return tok.decode(tokens.slice(0, maxTokens));
+  }
+  const limit = Math.min(maxTokens * 4, text.length);
+  return text.slice(0, limit);
+}
+
+// src/system-prompt.ts
+var LAYER_ORDER = [
+  "core",
+  "behavior",
+  "memory",
+  "session",
+  "mode"
+];
+var SystemPromptBuilder = class {
+  layers = /* @__PURE__ */ new Map();
+  maxLayerTokens = /* @__PURE__ */ new Map();
+  setMaxLayerTokens(layer, maxTokens) {
+    this.maxLayerTokens.set(layer, maxTokens);
+  }
+  build() {
+    return this.buildWithBudget();
+  }
+  buildWithBudget(tok) {
+    const parts = [];
+    for (const layer of LAYER_ORDER) {
+      let content = (this.layers.get(layer) ?? "").trim();
+      if (!content) continue;
+      if (tok) {
+        const cap = this.maxLayerTokens.get(layer);
+        if (cap && cap > 0 && tok.count(content) > cap) {
+          content = truncateToTokens(content, cap, tok);
+        }
+      }
+      parts.push(content);
+    }
+    return parts.join("\n\n");
+  }
+  get(layer) {
+    return this.layers.get(layer) ?? "";
+  }
+  has(layer) {
+    return (this.layers.get(layer) ?? "").trim().length > 0;
+  }
+  set(layer, content) {
+    this.layers.set(layer, content.trim());
+  }
+  append(layer, content) {
+    const existing = this.layers.get(layer) ?? "";
+    if (!existing) {
+      this.layers.set(layer, content.trim());
+    } else {
+      this.layers.set(layer, existing + "\n\n" + content.trim());
+    }
+  }
+  clear(layer) {
+    this.layers.delete(layer);
+  }
+};
+
+// src/system-reminder.ts
+function systemReminder(content) {
+  const trimmed = content.trim();
+  if (!trimmed) return "";
+  return `<system-reminder>
+${trimmed}
+</system-reminder>`;
+}
+function joinSystemReminders(...reminders) {
+  return reminders.filter(Boolean).join("\n\n");
+}
+
+// src/context-budget.ts
+function defaultContextBudget(windowSize) {
+  return {
+    windowSize,
+    skillsReserve: Math.floor(windowSize * 0.1),
+    memoryReserve: Math.floor(windowSize * 0.15),
+    historyReserve: Math.floor(windowSize * 0.6),
+    reserveBuffer: Math.floor(windowSize * 0.05)
+  };
+}
+function enforceContextBudget(budget, conv, memoryTokens, tok) {
+  const result = {
+    overflowTokens: 0,
+    truncatedHistory: false,
+    historyDropped: 0,
+    stillOverflow: false
+  };
+  const available = budget.historyReserve;
+  let used = 0;
+  const kept = [];
+  for (let i = conv.messages.length - 1; i >= 0; i--) {
+    const msg = conv.messages[i];
+    const tokens = tok.count(msg.content);
+    if (used + tokens > available && kept.length > 0) {
+      result.truncatedHistory = true;
+      result.historyDropped = i + 1;
+      result.overflowTokens = used + tokens - available;
+      break;
+    }
+    used += tokens;
+    kept.unshift(msg);
+  }
+  if (result.truncatedHistory) {
+    conv.messages = kept;
+  }
+  return result;
+}
+
+// src/compaction.ts
+var LLMCompactor = class {
+  constructor(llm) {
+    this.llm = llm;
+  }
+  llm;
+  async summarize(messages, signal) {
+    const history = messages.map((m) => `${m.role.toUpperCase()}: ${m.content}`).join("\n\n");
+    const resp = await this.llm.chat(
+      {
+        messages: [
+          {
+            role: "user",
+            content: `Summarize the following conversation history concisely, preserving key decisions, facts, and context:
+
+${history}`
+          }
+        ],
+        maxTokens: 1024
+      },
+      signal
+    );
+    return resp.content;
+  }
+};
+var BulletCompactor = class {
+  async summarize(messages) {
+    const points = [];
+    for (const msg of messages) {
+      if (msg.role === "assistant" && msg.content.trim()) {
+        const first = msg.content.split("\n")[0]?.trim() ?? "";
+        if (first) points.push(`- ${first.slice(0, 120)}`);
+      }
+    }
+    return points.join("\n");
+  }
+};
+async function enforceWithCompaction(budget, compactor, conv, memoryTokens, tok = new HeuristicTokenizer(), signal) {
+  const enforcementResult = enforceContextBudget(budget, conv, memoryTokens, tok);
+  let summary = "";
+  if (compactor && enforcementResult.truncatedHistory) {
+    try {
+      summary = await compactor.summarize(conv.messages.slice(0, enforcementResult.historyDropped), signal);
+    } catch {
+    }
+  }
+  return { enforcementResult, summary };
+}
+
+// src/permissions.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var InterruptApprover = class {
+  constructor(requester) {
+    this.requester = requester;
+  }
+  requester;
+  async ask(tool, args, signal) {
+    const req = {
+      id: randomUUID2(),
+      kind: "approval",
+      title: `Allow ${tool.name}?`,
+      description: tool.description,
+      toolName: tool.name,
+      toolArgs: args,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    const resp = await this.requester(req, signal);
+    if (resp.approved) {
+      return { behavior: "allow" };
+    }
+    return { behavior: "deny", reason: "user denied" };
+  }
+};
+var PermissionEngine = class {
+  rules = [];
+  approver;
+  withRules(rules) {
+    this.rules = rules;
+    return this;
+  }
+  withApprover(approver) {
+    this.approver = approver;
+    return this;
+  }
+  async decide(tool, args, signal) {
+    for (const rule of this.rules) {
+      if (rule.toolName && rule.toolName !== tool.name) continue;
+      if (rule.pathPrefix) {
+        const path = typeof args["path"] === "string" ? args["path"] : "";
+        if (!path.startsWith(rule.pathPrefix)) continue;
+      }
+      if (rule.behavior === "ask") break;
+      return { behavior: rule.behavior, reason: rule.reason };
+    }
+    if (tool.checkPermissions) {
+      const result = await tool.checkPermissions(signal, args);
+      if (result.decision === "deny" || result.decision === "ask_user") {
+        if (this.approver && result.decision === "ask_user") {
+          return this.approver.ask(tool, args, signal);
+        }
+        return { behavior: "deny", reason: result.reason };
+      }
+      return {
+        behavior: "allow",
+        updatedInput: result.updatedArgs
+      };
+    }
+    if (this.approver && tool.isDestructive?.(args)) {
+      return this.approver.ask(tool, args, signal);
+    }
+    return { behavior: "allow" };
+  }
+};
+
+// src/session-context.ts
+function formatSessionContext(sc) {
+  const parts = [];
+  if (sc.currentTime) {
+    parts.push(`Current time: ${sc.currentTime.toISOString()}`);
+  }
+  if (sc.timezone) parts.push(`Timezone: ${sc.timezone}`);
+  if (sc.userId) parts.push(`User ID: ${sc.userId}`);
+  if (sc.username) parts.push(`Username: ${sc.username}`);
+  if (sc.projectId) parts.push(`Project: ${sc.projectId}`);
+  if (sc.activeArtifactId) parts.push(`Active artifact: ${sc.activeArtifactId}`);
+  if (sc.extras) {
+    for (const [k, v] of Object.entries(sc.extras)) {
+      parts.push(`${k}: ${v}`);
+    }
+  }
+  return parts.join("\n");
+}
+
+// src/execution-context.ts
+var InMemoryExecutionContext = class {
+  _todos = [];
+  todos() {
+    return this._todos.slice();
+  }
+  setTodos(todos) {
+    this._todos = todos.slice();
+  }
+  markDone(id) {
+    const todo = this._todos.find((t) => t.id === id);
+    if (todo) todo.status = "completed";
+  }
+};
+
+// src/interrupt-store.ts
+var InMemoryInterruptStore = class {
+  store = /* @__PURE__ */ new Map();
+  async put(req) {
+    this.store.set(req.id, req);
+  }
+  async get(id) {
+    const req = this.store.get(id);
+    if (!req) return { ok: false };
+    return { req, ok: true };
+  }
+  async delete(id) {
+    this.store.delete(id);
+  }
+};
+
+// src/memory-selector.ts
+var KeywordMemorySelector = class {
+  async select(query, headers, limit) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (!terms.length || !headers.length) return [];
+    const scored = headers.map((h) => {
+      const text = `${h.title ?? ""} ${h.description ?? ""} ${h.type ?? ""} ${h.path}`.toLowerCase();
+      const score = terms.reduce((acc, t) => acc + (text.includes(t) ? 1 : 0), 0);
+      return { h, score };
+    });
+    return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.h);
+  }
+};
+
+// src/rule-matcher.ts
+function ruleMatcherFromFn(fn) {
+  return { match: fn };
+}
+function prefixMatcher(argKey) {
+  return {
+    match(rule, input) {
+      if (!rule) return true;
+      const val = input[argKey];
+      return typeof val === "string" && val.startsWith(rule);
+    }
+  };
+}
+function exactMatcher() {
+  return {
+    match(rule, input) {
+      if (!rule) return true;
+      const primary = Object.values(input)[0];
+      return String(primary) === rule;
+    }
+  };
+}
+
+// src/engine.ts
+function newEngine(...opts) {
+  const e = {};
+  for (const opt of opts) opt(e);
+  return e;
+}
+function newEngineWithDefaults(windowSize) {
+  const budget = defaultContextBudget(windowSize);
+  return {
+    prompt: new SystemPromptBuilder(),
+    budget
+  };
+}
+var hasMemory = (e) => e.memory != null;
+var hasSandbox = (e) => e.sandbox != null;
+var hasTools = (e) => e.tools != null;
+var hasThreads = (e) => e.threads != null;
+var hasModes = (e) => e.modes != null;
+var hasLLM = (e) => e.llm != null;
+var hasPrompt = (e) => e.prompt != null;
+var hasBudget = (e) => e.budget != null;
+var withMemory = (p) => (e) => {
+  e.memory = p;
+};
+var withSandbox = (p) => (e) => {
+  e.sandbox = p;
+};
+var withTools = (r) => (e) => {
+  e.tools = r;
+};
+var withThreads = (p) => (e) => {
+  e.threads = p;
+};
+var withModes = (p) => (e) => {
+  e.modes = p;
+};
+var withLLM = (p) => (e) => {
+  e.llm = p;
+};
+var withPrompt = (b) => (e) => {
+  e.prompt = b;
+};
+var withBudget = (b) => (e) => {
+  e.budget = b;
+};
+
+// src/dispatch.ts
+var ToolDispatcher = class {
+  constructor(tools, sandbox) {
+    this.tools = tools;
+    this.sandbox = sandbox;
+  }
+  tools;
+  sandbox;
+  permissions;
+  withPermissions(engine) {
+    this.permissions = engine;
+    return this;
+  }
+  async dispatch(call, sandboxId, signal) {
+    const tool = this.tools.get(call.name);
+    if (!tool) {
+      const err = new Error(`tool "${call.name}" not found`);
+      return {
+        toolCallId: call.id,
+        name: call.name,
+        content: `error: tool "${call.name}" not found in registry`,
+        error: err
+      };
+    }
+    let args = {};
+    if (call.arguments && call.arguments !== "{}") {
+      try {
+        args = JSON.parse(call.arguments);
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content: `error: invalid JSON arguments: ${err.message}`,
+          error: err
+        };
+      }
+    }
+    if (tool.validate) {
+      try {
+        await tool.validate(signal, args);
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content: `error: ${err.message}`,
+          error: err
+        };
+      }
+    }
+    if (this.permissions) {
+      const dec = await this.permissions.decide(tool, args, signal);
+      if (dec.behavior === "deny" || dec.behavior === "ask") {
+        const reason = dec.reason?.trim() || "permission denied";
+        const content = `<tool_use_error>The user did not approve this ${tool.name} call. Reason: ${reason}.
+
+The tool was NOT executed. Do NOT claim success. Do NOT retry the same call. Acknowledge the rejection and ask the user how to proceed (or stop).</tool_use_error>`;
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content,
+          error: new Error(reason)
+        };
+      }
+      if (dec.updatedInput) args = dec.updatedInput;
+    } else if (tool.checkPermissions) {
+      try {
+        const result = await tool.checkPermissions(signal, args);
+        if (result.decision === "deny" || result.decision === "ask_user") {
+          const reason = result.reason?.trim() || "permission denied";
+          return {
+            toolCallId: call.id,
+            name: call.name,
+            content: `error: ${reason}`,
+            error: new Error(reason)
+          };
+        }
+        if (result.updatedArgs) args = result.updatedArgs;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content: `error: permission check failed: ${err.message}`,
+          error: err
+        };
+      }
+    }
+    try {
+      const content = await tool.execute(signal, sandboxId, args);
+      return { toolCallId: call.id, name: call.name, content };
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      return {
+        toolCallId: call.id,
+        name: call.name,
+        content: `error: ${err.message}`,
+        error: err
+      };
+    }
+  }
+  async dispatchAll(calls, sandboxId, signal) {
+    const results = [];
+    for (const call of calls) {
+      results.push(await this.dispatch(call, sandboxId, signal));
+    }
+    return results;
+  }
+  async dispatchParallel(calls, sandboxId, signal) {
+    if (calls.length === 0) return [];
+    if (calls.length === 1) return [await this.dispatch(calls[0], sandboxId, signal)];
+    const results = new Array(calls.length);
+    const safe = [];
+    const unsafe = [];
+    for (let i = 0; i < calls.length; i++) {
+      const call = calls[i];
+      const tool = this.tools.get(call.name);
+      let isSafe = false;
+      if (tool?.isConcurrencySafe) {
+        let args = {};
+        try {
+          if (call.arguments && call.arguments !== "{}") {
+            args = JSON.parse(call.arguments);
+          }
+        } catch {
+        }
+        isSafe = tool.isConcurrencySafe(args);
+      }
+      if (isSafe) {
+        safe.push({ idx: i, call });
+      } else {
+        unsafe.push({ idx: i, call });
+      }
+    }
+    await Promise.all(
+      safe.map(async ({ idx, call }) => {
+        results[idx] = await this.dispatch(call, sandboxId, signal);
+      })
+    );
+    for (const { idx, call } of unsafe) {
+      results[idx] = await this.dispatch(call, sandboxId, signal);
+    }
+    return results;
+  }
+};
+function toolResultsToMessages(assistantToolCalls, results) {
+  const msgs = [
+    { role: "assistant", content: "", toolCalls: assistantToolCalls }
+  ];
+  for (const r of results) {
+    msgs.push({
+      role: "tool",
+      name: r.name,
+      toolCallId: r.toolCallId,
+      content: r.content
+    });
+  }
+  return msgs;
+}
+function areIndependent(calls) {
+  if (calls.length <= 1) return true;
+  return !calls.some(
+    (c) => c.arguments.includes("${") || c.arguments.includes("{{")
+  );
+}
+
+// src/llm-router.ts
+function parseModelRef(ref) {
+  const slash = ref.indexOf("/");
+  if (slash === -1) return ["", ref];
+  return [ref.slice(0, slash), ref.slice(slash + 1)];
+}
+var RoutedLLMProvider = class {
+  routes = /* @__PURE__ */ new Map();
+  fallback;
+  register(provider, llm) {
+    this.routes.set(provider, llm);
+    return this;
+  }
+  withFallback(llm) {
+    this.fallback = llm;
+    return this;
+  }
+  route(model) {
+    const [provider] = parseModelRef(model);
+    const resolved = provider ? this.routes.get(provider) : void 0;
+    if (resolved) return resolved;
+    if (this.fallback) return this.fallback;
+    throw new Error(`no provider registered for model: ${model}`);
+  }
+  async chat(req, signal) {
+    return this.route(req.model ?? "").chat(req, signal);
+  }
+};
+
+// src/agent-loop.ts
+function previewText(value, limit) {
+  const trimmed = value.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= limit || limit <= 3) return trimmed;
+  return trimmed.slice(0, limit - 3) + "...";
+}
+function previewJson(value, limit) {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  try {
+    const parsed = JSON.parse(trimmed);
+    return previewText(JSON.stringify(parsed), limit);
+  } catch {
+    return previewText(trimmed, limit);
+  }
+}
+function buildDefaultRequest(cfg, messages) {
+  const req = {
+    model: cfg.model,
+    messages: []
+  };
+  if (cfg.systemPrompt) {
+    req.messages.push({ role: "system", content: cfg.systemPrompt });
+  }
+  req.messages.push(...messages);
+  if (cfg.tools) {
+    req.tools = cfg.tools.toolDefs();
+  }
+  return req;
+}
+function buildRequest(cfg, messages) {
+  if (cfg.buildRequest) {
+    return cfg.buildRequest(cfg.systemPrompt ?? "", messages, cfg.tools);
+  }
+  return buildDefaultRequest(cfg, messages);
+}
+function classifyError(err) {
+  const msg = err.message.toLowerCase();
+  const permanent = [
+    "unauthorized",
+    "401",
+    "403",
+    "forbidden",
+    "invalid api key",
+    "authentication",
+    "invalid request",
+    "400",
+    "not found",
+    "404",
+    "context length",
+    "context window",
+    "content_filter",
+    "content filter"
+  ];
+  if (permanent.some((p) => msg.includes(p))) return "permanent";
+  const transient = [
+    "rate limit",
+    "429",
+    "too many requests",
+    "timeout",
+    "deadline",
+    "connection reset",
+    "connection refused",
+    "eof",
+    "broken pipe",
+    "500",
+    "502",
+    "503",
+    "504",
+    "server error",
+    "service unavailable",
+    "temporary"
+  ];
+  if (transient.some((t) => msg.includes(t))) return "transient";
+  return "unknown";
+}
+async function callWithRetry(provider, req, maxRetries, onError, signal) {
+  let lastErr = new Error("unknown");
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await provider.chat(req, signal);
+    } catch (e) {
+      lastErr = e instanceof Error ? e : new Error(String(e));
+      switch (classifyError(lastErr)) {
+        case "permanent":
+          throw lastErr;
+        case "transient":
+          if (attempt < maxRetries) {
+            const delay = Math.min(1e3 * 2 ** (attempt - 1), 3e4);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+          break;
+        default:
+          if (onError == null || !onError(lastErr, attempt)) throw lastErr;
+      }
+    }
+  }
+  throw new Error(`max retries (${maxRetries}) exceeded: ${lastErr.message}`);
+}
+async function runAgentLoop(cfg, messages, signal) {
+  if (!cfg.provider) throw new Error("AgentLoopConfig.provider is required");
+  const maxTurns = cfg.maxTurns && cfg.maxTurns > 0 ? cfg.maxTurns : 50;
+  const maxRetries = cfg.maxRetries && cfg.maxRetries > 0 ? cfg.maxRetries : 3;
+  let req = buildRequest(cfg, messages);
+  const dispatcher = cfg.tools ? new ToolDispatcher(cfg.tools, cfg.sandbox) : void 0;
+  if (dispatcher && cfg.permissions) {
+    dispatcher.withPermissions(cfg.permissions);
+  }
+  const result = {
+    finalContent: "",
+    providerReasoning: "",
+    totalTurns: 0,
+    totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    messages: req.messages.slice(),
+    reasoningTrace: [],
+    stopReason: "complete"
+  };
+  let traceSeq = 0;
+  const appendTrace = (type, title, content, details) => {
+    result.reasoningTrace.push({
+      id: `trace-${++traceSeq}`,
+      type,
+      title,
+      content,
+      details
+    });
+  };
+  for (let turn = 1; turn <= maxTurns; turn++) {
+    if (signal?.aborted) {
+      result.stopReason = "aborted";
+      return result;
+    }
+    const resp = await callWithRetry(cfg.provider, req, maxRetries, cfg.onError, signal);
+    result.totalTurns = turn;
+    result.totalUsage.promptTokens += resp.usage.promptTokens;
+    result.totalUsage.completionTokens += resp.usage.completionTokens;
+    result.totalUsage.totalTokens += resp.usage.totalTokens;
+    if (resp.reasoning?.trim()) {
+      result.providerReasoning = result.providerReasoning ? result.providerReasoning + "\n\n" + resp.reasoning : resp.reasoning;
+      appendTrace("thinking", `Provider reasoning ${turn}`, previewText(resp.reasoning, 220));
+    }
+    appendTrace("thinking", `Turn ${turn}`, void 0, [
+      `Finish reason: ${resp.finishReason}`,
+      `Tool calls requested: ${resp.toolCalls?.length ?? 0}`,
+      `Tokens this turn: ${resp.usage.totalTokens}`
+    ]);
+    if (cfg.onTurn && !cfg.onTurn(turn, resp)) {
+      result.finalContent = resp.content;
+      result.stopReason = "aborted";
+      return result;
+    }
+    if (cfg.shouldStop?.(turn, resp)) {
+      result.finalContent = resp.content;
+      result.stopReason = "stopped";
+      result.messages.push({ role: "assistant", content: resp.content });
+      return result;
+    }
+    if (!resp.toolCalls?.length) {
+      result.finalContent = resp.content;
+      result.stopReason = "complete";
+      result.messages.push({ role: "assistant", content: resp.content });
+      return result;
+    }
+    if (!dispatcher) {
+      result.stopReason = "error";
+      throw new Error("LLM requested tool calls but no ToolRegistry is configured");
+    }
+    const callsToRun = resp.toolCalls.filter(
+      (tc) => cfg.onToolCall == null || cfg.onToolCall(tc)
+    );
+    for (const tc of callsToRun) {
+      appendTrace("action", `Tool call: ${tc.name}`, previewJson(tc.arguments, 220));
+    }
+    let toolResults = await dispatcher.dispatchAll(callsToRun, cfg.sandboxId ?? "", signal);
+    if (cfg.onToolResult) {
+      toolResults = toolResults.map(
+        (tr, i) => cfg.onToolResult(callsToRun[i], tr)
+      );
+    }
+    for (const tr of toolResults) {
+      appendTrace(tr.error ? "thinking" : "result", `Tool result: ${tr.name}`, previewText(tr.content, 220));
+    }
+    const toolMsgs = toolResultsToMessages(resp.toolCalls, toolResults);
+    result.messages.push(...toolMsgs);
+    req = buildRequest(cfg, result.messages);
+  }
+  result.stopReason = "max_turns";
+  return result;
+}
+async function runAgentLoopWithEngine(engine, modeId, cfg, messages, signal) {
+  const callerSuppliedPrompt = Boolean(cfg.systemPrompt);
+  let resolvedModel = cfg.model ?? "";
+  if (hasModes(engine) && modeId) {
+    const mode = await engine.modes.get(modeId, signal);
+    if (!cfg.model && mode.modelSettings?.model) {
+      cfg.model = mode.modelSettings.model;
+    }
+    if (!callerSuppliedPrompt) {
+      if (hasPrompt(engine)) {
+        engine.prompt.set("mode", mode.promptContent ?? "");
+        cfg.systemPrompt = engine.prompt.build();
+      } else {
+        cfg.systemPrompt = mode.promptContent ?? "";
+      }
+    }
+    resolvedModel = cfg.model ?? "";
+  } else if (!callerSuppliedPrompt && hasPrompt(engine)) {
+    cfg.systemPrompt = engine.prompt.build();
+  }
+  if (!resolvedModel) resolvedModel = cfg.model ?? "";
+  if (!cfg.provider) {
+    if (!hasLLM(engine)) throw new Error("no LLM provider configured");
+    cfg.provider = resolveProvider(engine, resolvedModel);
+    const [, modelOnly] = parseModelRef(cfg.model ?? "");
+    if (modelOnly) cfg.model = modelOnly;
+  }
+  if (!cfg.tools && hasTools(engine)) cfg.tools = engine.tools;
+  if (!cfg.sandbox && hasSandbox(engine)) cfg.sandbox = engine.sandbox;
+  return runAgentLoop(cfg, messages, signal);
+}
+function resolveProvider(engine, model) {
+  if (!hasLLM(engine)) throw new Error("no LLM provider configured");
+  if (model) {
+    const llm = engine.llm;
+    if ("route" in llm && typeof llm.route === "function") {
+      return llm.route(model);
+    }
+  }
+  return engine.llm;
+}
+
+// src/runtime.ts
+var Runtime = class {
+  engine;
+  mode = "";
+  model = "";
+  safety;
+  tokenizer = new HeuristicTokenizer();
+  store;
+  sessionContext;
+  compactor;
+  maxMemoryTokens = 0;
+  memoryRoots = DEFAULT_MEMORY_ROOTS;
+  thinkingBudget = 0;
+  interruptGate;
+  permissions;
+  planController;
+  _emit;
+  constructor(engine) {
+    this.engine = engine;
+  }
+  withMode(modeId) {
+    this.mode = modeId;
+    return this;
+  }
+  withModel(model) {
+    this.model = model;
+    return this;
+  }
+  withSafety(s) {
+    this.safety = s;
+    return this;
+  }
+  withPermissions(e) {
+    this.permissions = e;
+    return this;
+  }
+  withTokenizer(t) {
+    this.tokenizer = t;
+    return this;
+  }
+  withConversationStore(s) {
+    this.store = s;
+    return this;
+  }
+  withSessionContext(p) {
+    this.sessionContext = p;
+    return this;
+  }
+  withCompactor(c) {
+    this.compactor = c;
+    return this;
+  }
+  withMaxMemoryTokens(n) {
+    this.maxMemoryTokens = n;
+    return this;
+  }
+  withMemoryRoots(...roots) {
+    this.memoryRoots = roots;
+    return this;
+  }
+  withThinkingBudget(tokens) {
+    this.thinkingBudget = tokens;
+    return this;
+  }
+  withInterruptGate(gate) {
+    this.interruptGate = gate;
+    return this;
+  }
+  withPlanController(pc) {
+    const prev = pc.onStateChanged;
+    pc.onStateChanged = (ev) => {
+      prev?.(ev);
+      const planMode = { state: ev.state, plan: ev.plan, reason: ev.reason };
+      this._emit?.({ type: "plan_mode_changed", planMode });
+    };
+    this.planController = pc;
+    return this;
+  }
+  async run(conv, userMessage, signal) {
+    if (!hasLLM(this.engine)) throw new Error("runtime: no LLM provider");
+    if (!conv) throw new Error("runtime: conversation is required");
+    const tracer = new Tracer();
+    const rr = {
+      response: "",
+      turns: 0,
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      stopReason: "",
+      trace: [],
+      traceId: tracer.traceId(),
+      memoryRead: false,
+      memoryWritten: [],
+      warnings: [],
+      startedAt: /* @__PURE__ */ new Date()
+    };
+    appendUser(conv, userMessage);
+    if (isCold(conv)) {
+      await this.orientation(conv, userMessage, rr, signal);
+    } else {
+      await this.warmRefresh(conv, userMessage, signal);
+    }
+    if (signal?.aborted) return rr;
+    await this.preparation(conv, rr, signal);
+    if (signal?.aborted) return rr;
+    const loopResult = await this.execution(conv, rr, signal);
+    if (loopResult?.finalContent) {
+      appendAssistant(conv, loopResult.finalContent);
+    }
+    if (signal?.aborted) return rr;
+    incrementTurn(conv);
+    if (this.store) {
+      try {
+        await this.store.save(conv, signal);
+      } catch (e) {
+        rr.warnings.push(`save conversation: ${e.message}`);
+      }
+    }
+    rr.completedAt = /* @__PURE__ */ new Date();
+    rr.trace = tracer.allSpans();
+    return rr;
+  }
+  async *runStream(conv, userMessage, signal) {
+    const out = [];
+    let resolve = null;
+    let done = false;
+    this._emit = (ev) => {
+      out.push(ev);
+      resolve?.();
+    };
+    const runPromise = this.run(conv, userMessage, signal).then(
+      (result) => {
+        if (result.response) {
+          for (const chunk of chunkBySentence(result.response)) {
+            out.push({ type: "delta", delta: chunk });
+          }
+        }
+        out.push({ type: "done" });
+        done = true;
+        resolve?.();
+      },
+      (err) => {
+        out.push({ type: "error", error: err });
+        out.push({ type: "done" });
+        done = true;
+        resolve?.();
+      }
+    ).finally(() => {
+      this._emit = void 0;
+    });
+    while (!done || out.length > 0) {
+      if (out.length === 0) {
+        await new Promise((r) => {
+          resolve = r;
+        });
+        resolve = null;
+        continue;
+      }
+      yield out.shift();
+    }
+    await runPromise;
+  }
+  async orientation(conv, userMessage, rr, signal) {
+    if (hasMemory(this.engine) && hasPrompt(this.engine)) {
+      const scopes = [...new Set(this.memoryRoots.map((r) => r.scope))];
+      const sections = [];
+      for (const scope of scopes) {
+        try {
+          const index = await this.engine.memory.view(scope, "MEMORY.md", signal);
+          if (index.trim()) sections.push(index.trim());
+        } catch {
+        }
+      }
+      if (sections.length > 0) {
+        let section = sections.join("\n\n");
+        if (this.maxMemoryTokens > 0 && this.tokenizer.count(section) > this.maxMemoryTokens) {
+          section = evictMemoryToTokenBudget(section, this.maxMemoryTokens, this.tokenizer);
+        }
+        this.engine.prompt.set("memory", section);
+        rr.memoryRead = true;
+        conv.memoryRead = true;
+      }
+    }
+    await this.buildSessionLayer(conv, userMessage, signal);
+  }
+  async warmRefresh(conv, userMessage, signal) {
+    await this.buildSessionLayer(conv, userMessage, signal);
+  }
+  async buildSessionLayer(conv, _userMessage, signal) {
+    if (!hasPrompt(this.engine)) return;
+    if (!this.sessionContext) {
+      this.engine.prompt.clear("session");
+      return;
+    }
+    try {
+      const sc = await this.sessionContext.get(conv, signal);
+      if (!sc) {
+        this.engine.prompt.clear("session");
+        return;
+      }
+      const rendered = formatSessionContext(sc);
+      if (!rendered) {
+        this.engine.prompt.clear("session");
+        return;
+      }
+      this.engine.prompt.set("session", rendered);
+    } catch {
+      this.engine.prompt.clear("session");
+    }
+  }
+  async preparation(conv, rr, signal) {
+    if (!hasBudget(this.engine) || !hasPrompt(this.engine)) return;
+    const memoryTokens = this.tokenizer.count(
+      this.engine.prompt.get("memory")
+    );
+    const compResult = await enforceWithCompaction(
+      this.engine.budget,
+      this.compactor,
+      conv,
+      memoryTokens,
+      this.tokenizer,
+      signal
+    );
+    const enforce = compResult.enforcementResult;
+    if (enforce.overflowTokens > 0) {
+      if (enforce.truncatedHistory) {
+        rr.warnings.push(`budget: dropped ${enforce.historyDropped} messages`);
+      }
+      if (enforce.stillOverflow) {
+        rr.warnings.push("budget: still over after enforcement");
+      }
+    }
+    if (compResult.summary) {
+      this.engine.prompt.append(
+        "memory",
+        `
+
+Context summary (from earlier turns):
+${compResult.summary}`
+      );
+    }
+    if (this._emit && enforce.truncatedHistory) {
+      this._emit({
+        type: "compaction",
+        compaction: {
+          messagesDropped: enforce.historyDropped,
+          overflowTokens: enforce.overflowTokens,
+          summary: compResult.summary
+        }
+      });
+    }
+  }
+  async execution(conv, rr, signal) {
+    let systemPrompt = "";
+    if (hasPrompt(this.engine)) {
+      if (this.mode && hasModes(this.engine)) {
+        try {
+          const mode = await this.engine.modes.get(this.mode, signal);
+          this.engine.prompt.set("mode", mode.promptContent ?? "");
+        } catch {
+        }
+      }
+      systemPrompt = this.engine.prompt.build();
+    }
+    if (hasTools(this.engine)) {
+      const blocks = await this.engine.tools.collectDynamicReminders(signal);
+      if (blocks.length > 0) {
+        const wrapped = blocks.map(systemReminder).filter(Boolean);
+        const joined = joinSystemReminders(...wrapped);
+        if (joined) {
+          systemPrompt = systemPrompt ? systemPrompt + "\n\n" + joined : joined;
+        }
+      }
+    }
+    const cfg = {
+      systemPrompt,
+      model: this.model,
+      permissions: this.permissions,
+      maxTurns: 50,
+      onToolCall: (call) => {
+        if (this.safety) {
+          const verdict = this.safety.inspect(call);
+          return verdict.decision !== "block";
+        }
+        return true;
+      }
+    };
+    const loopResult = await runAgentLoopWithEngine(
+      this.engine,
+      this.mode,
+      cfg,
+      conv.messages,
+      signal
+    );
+    rr.turns += loopResult.totalTurns;
+    rr.usage.promptTokens += loopResult.totalUsage.promptTokens;
+    rr.usage.completionTokens += loopResult.totalUsage.completionTokens;
+    rr.usage.totalTokens += loopResult.totalUsage.totalTokens;
+    rr.stopReason = loopResult.stopReason;
+    rr.response = loopResult.finalContent;
+    conv.messages = loopResult.messages;
+    return loopResult;
+  }
+};
+function evictMemoryToTokenBudget(content, maxTokens, tok) {
+  const paragraphs = content.trim().split(/\n\n+/);
+  const kept = [];
+  let used = 0;
+  for (let i = paragraphs.length - 1; i >= 0; i--) {
+    const p = paragraphs[i].trim();
+    if (!p) continue;
+    const tokens = tok.count(p);
+    if (used + tokens > maxTokens && kept.length > 0) break;
+    kept.unshift(p);
+    used += tokens;
+  }
+  if (kept.length < paragraphs.length) {
+    kept.unshift("[Earlier memory entries omitted \u2014 token budget exceeded]");
+  }
+  return kept.join("\n\n");
+}
+function chunkBySentence(text) {
+  if (!text) return [];
+  const chunks = [];
+  let current = "";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    current += ch;
+    if (ch === "." || ch === "!" || ch === "?" || ch === "\n") {
+      const next = text[i + 1];
+      if (!next || next === " " || next === "\n" || next === "	") {
+        const chunk = current.trim();
+        if (chunk) chunks.push(chunk + " ");
+        current = "";
+      }
+    }
+  }
+  if (current.trim()) chunks.push(current.trim());
+  return chunks;
+}
+function newRuntime(engine) {
+  return new Runtime(engine);
+}
+export {
+  BulletCompactor,
+  DEFAULT_MEMORY_ROOTS,
+  DefaultSafetyFilter,
+  ErrThreadAccessDenied,
+  HeuristicTokenizer,
+  InMemoryExecutionContext,
+  InMemoryInterruptStore,
+  InterruptApprover,
+  InterruptGate,
+  KeywordMemorySelector,
+  LLMCompactor,
+  PROTOCOL_VERSION,
+  PermissionEngine,
+  RoutedLLMProvider,
+  Runtime,
+  StaticModeProvider,
+  SystemPromptBuilder,
+  ToolDispatcher,
+  ToolRegistry,
+  Tracer,
+  appendAssistant,
+  appendUser,
+  areIndependent,
+  collectStream,
+  defaultContextBudget,
+  emitArtifact,
+  enforceContextBudget,
+  enforceWithCompaction,
+  exactMatcher,
+  fanOutStream,
+  formatSessionContext,
+  hasBudget,
+  hasLLM,
+  hasMemory,
+  hasModes,
+  hasPrompt,
+  hasSandbox,
+  hasThreads,
+  hasTools,
+  incrementTurn,
+  isCold,
+  isToolAllowed,
+  joinSystemReminders,
+  messageCount,
+  newConversation,
+  newEngine,
+  newEngineWithDefaults,
+  newRuntime,
+  parseModelRef,
+  prefixMatcher,
+  ruleMatcherFromFn,
+  runAgentLoop,
+  runAgentLoopWithEngine,
+  systemReminder,
+  toToolDef,
+  toolResultsToMessages,
+  tracerFromContext,
+  truncateToTokens,
+  withArtifactEmitter,
+  withBudget,
+  withLLM,
+  withMemory,
+  withModes,
+  withPrompt,
+  withSandbox,
+  withThreads,
+  withTools,
+  withTracer
+};
+//# sourceMappingURL=index.js.map