@witqq/agent-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,453 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// src/types.ts
+function isToolDefinition(tool) {
+  return "execute" in tool && typeof tool.execute === "function";
+}
+function isTextContent(content) {
+  return typeof content === "string";
+}
+function isMultiPartContent(content) {
+  return Array.isArray(content);
+}
+function getTextContent(content) {
+  if (typeof content === "string") return content;
+  return content.filter((p) => p.type === "text").map((p) => p.text).join("\n");
+}
+
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+  }
+};
+var ReentrancyError = class extends AgentSDKError {
+  constructor() {
+    super("Agent is already running. Await the current run before starting another.");
+    this.name = "ReentrancyError";
+  }
+};
+var DisposedError = class extends AgentSDKError {
+  constructor(entity) {
+    super(`${entity} has been disposed and cannot be used.`);
+    this.name = "DisposedError";
+  }
+};
+var BackendNotFoundError = class extends AgentSDKError {
+  constructor(backend) {
+    super(
+      `Unknown backend: "${backend}". Built-in: copilot, claude, vercel-ai. Custom: use registerBackend() first.`
+    );
+    this.name = "BackendNotFoundError";
+  }
+};
+var BackendAlreadyRegisteredError = class extends AgentSDKError {
+  constructor(backend) {
+    super(`Backend "${backend}" is already registered. Use a different name or unregister first.`);
+    this.name = "BackendAlreadyRegisteredError";
+  }
+};
+var SubprocessError = class extends AgentSDKError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "SubprocessError";
+  }
+};
+var DependencyError = class extends AgentSDKError {
+  packageName;
+  constructor(packageName) {
+    super(`${packageName} is not installed. Install it: npm install ${packageName}`);
+    this.name = "DependencyError";
+    this.packageName = packageName;
+  }
+};
+var AbortError = class extends AgentSDKError {
+  constructor() {
+    super("Agent run was aborted.");
+    this.name = "AbortError";
+  }
+};
+var ToolExecutionError = class extends AgentSDKError {
+  toolName;
+  constructor(toolName, message, options) {
+    super(`Tool "${toolName}" failed: ${message}`, options);
+    this.name = "ToolExecutionError";
+    this.toolName = toolName;
+  }
+};
+var StructuredOutputError = class extends AgentSDKError {
+  constructor(message, options) {
+    super(`Structured output error: ${message}`, options);
+    this.name = "StructuredOutputError";
+  }
+};
+
+// src/registry.ts
+var registry = /* @__PURE__ */ new Map();
+function registerBackend(name, factory) {
+  if (registry.has(name)) {
+    throw new BackendAlreadyRegisteredError(name);
+  }
+  registry.set(name, { factory, builtin: false });
+}
+function unregisterBackend(name) {
+  return registry.delete(name);
+}
+function hasBackend(name) {
+  return registry.has(name) || isBuiltinName(name);
+}
+function listBackends() {
+  const names = new Set(registry.keys());
+  for (const builtin of BUILTIN_BACKENDS) {
+    names.add(builtin);
+  }
+  return [...names];
+}
+function resetRegistry() {
+  registry.clear();
+}
+var BUILTIN_BACKENDS = /* @__PURE__ */ new Set([
+  "copilot",
+  "claude",
+  "vercel-ai"
+]);
+function isBuiltinName(name) {
+  return BUILTIN_BACKENDS.has(name);
+}
+async function loadBuiltinFactory(name) {
+  switch (name) {
+    case "copilot": {
+      const mod = await import('./backends/copilot.js');
+      return (opts) => mod.createCopilotService(opts);
+    }
+    case "claude": {
+      const mod = await import('./backends/claude.js');
+      return (opts) => mod.createClaudeService(opts);
+    }
+    case "vercel-ai": {
+      const mod = await import('./backends/vercel-ai.js');
+      return (opts) => mod.createVercelAIService(opts);
+    }
+  }
+}
+async function createAgentService(name, options) {
+  const entry = registry.get(name);
+  if (entry) {
+    return entry.factory(options);
+  }
+  if (isBuiltinName(name)) {
+    const factory = await loadBuiltinFactory(name);
+    registry.set(name, { factory, builtin: true });
+    return factory(options);
+  }
+  throw new BackendNotFoundError(name);
+}
+
+// src/base-agent.ts
+var BaseAgent = class {
+  state = "idle";
+  abortController = null;
+  config;
+  constructor(config) {
+    this.config = Object.freeze({ ...config });
+  }
+  // ─── Public Interface ─────────────────────────────────────────
+  async run(prompt, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "running";
+    try {
+      const messages = [{ role: "user", content: prompt }];
+      return await this.executeRun(messages, options, ac.signal);
+    } finally {
+      this.state = "idle";
+      this.abortController = null;
+    }
+  }
+  async runWithContext(messages, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "running";
+    try {
+      return await this.executeRun(messages, options, ac.signal);
+    } finally {
+      this.state = "idle";
+      this.abortController = null;
+    }
+  }
+  async runStructured(prompt, schema, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "running";
+    try {
+      const messages = [{ role: "user", content: prompt }];
+      return await this.executeRunStructured(
+        messages,
+        schema,
+        options,
+        ac.signal
+      );
+    } finally {
+      this.state = "idle";
+      this.abortController = null;
+    }
+  }
+  async *stream(prompt, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "streaming";
+    try {
+      const messages = [{ role: "user", content: prompt }];
+      yield* this.executeStream(messages, options, ac.signal);
+    } finally {
+      this.state = "idle";
+      this.abortController = null;
+    }
+  }
+  abort() {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+  getState() {
+    return this.state;
+  }
+  getConfig() {
+    return this.config;
+  }
+  /** Mark agent as disposed. Override to add cleanup. */
+  dispose() {
+    this.abort();
+    this.state = "disposed";
+  }
+  // ─── Guards ───────────────────────────────────────────────────
+  guardReentrancy() {
+    if (this.state === "running" || this.state === "streaming") {
+      throw new ReentrancyError();
+    }
+  }
+  guardDisposed() {
+    if (this.state === "disposed") {
+      throw new DisposedError("Agent");
+    }
+  }
+  /** Throw AbortError if signal is already aborted */
+  checkAbort(signal) {
+    if (signal.aborted) {
+      throw new AbortError();
+    }
+  }
+  // ─── Internal Helpers ─────────────────────────────────────────
+  createAbortController(externalSignal) {
+    const ac = new AbortController();
+    this.abortController = ac;
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        ac.abort();
+      } else {
+        externalSignal.addEventListener("abort", () => ac.abort(), {
+          once: true
+        });
+      }
+    }
+    return ac;
+  }
+};
+
+// src/utils/schema.ts
+function zodToJsonSchema(schema) {
+  const schemaAny = schema;
+  if ("jsonSchema" in schema && typeof schemaAny.jsonSchema === "function") {
+    return schemaAny.jsonSchema();
+  }
+  return extractSchemaFromDef(schema);
+}
+function extractSchemaFromDef(schema) {
+  const def = schema._def;
+  const typeName = def.typeName;
+  switch (typeName) {
+    case "ZodString":
+      return { type: "string" };
+    case "ZodNumber":
+      return { type: "number" };
+    case "ZodBoolean":
+      return { type: "boolean" };
+    case "ZodNull":
+      return { type: "null" };
+    case "ZodArray":
+      return {
+        type: "array",
+        items: extractSchemaFromDef(def.type)
+      };
+    case "ZodObject": {
+      const shape = schema.shape;
+      const properties = {};
+      const required = [];
+      for (const [key, value] of Object.entries(shape)) {
+        const valueDef = value._def;
+        if (valueDef.typeName === "ZodOptional") {
+          properties[key] = extractSchemaFromDef(valueDef.innerType);
+        } else {
+          properties[key] = extractSchemaFromDef(value);
+          required.push(key);
+        }
+      }
+      return {
+        type: "object",
+        properties,
+        ...required.length > 0 ? { required } : {}
+      };
+    }
+    case "ZodOptional":
+      return extractSchemaFromDef(def.innerType);
+    case "ZodEnum":
+      return { type: "string", enum: def.values };
+    default:
+      return {};
+  }
+}
+
+// src/utils/messages.ts
+function messagesToPrompt(messages) {
+  return messages.map((msg) => {
+    switch (msg.role) {
+      case "user":
+        return contentToText(msg.content);
+      case "assistant":
+        return contentToText(msg.content);
+      case "system":
+        return msg.content;
+      case "tool":
+        return msg.content ?? "";
+    }
+  }).filter(Boolean).join("\n\n");
+}
+function contentToText(content) {
+  return getTextContent(content);
+}
+function buildSystemPrompt(base, schemaInstruction) {
+  if (!schemaInstruction) return base;
+  return `${base}
+
+${schemaInstruction}`;
+}
+var InMemoryPermissionStore = class {
+  approvals = /* @__PURE__ */ new Map();
+  async isApproved(toolName) {
+    return this.approvals.has(toolName);
+  }
+  async approve(toolName, scope) {
+    if (scope === "once") return;
+    this.approvals.set(toolName, scope);
+  }
+  async revoke(toolName) {
+    this.approvals.delete(toolName);
+  }
+  async clear() {
+    this.approvals.clear();
+  }
+  async dispose() {
+    this.approvals.clear();
+  }
+};
+var FilePermissionStore = class {
+  filePath;
+  constructor(filePath) {
+    this.filePath = path.resolve(filePath);
+  }
+  async isApproved(toolName) {
+    const data = this.readFile();
+    return toolName in data.approvals;
+  }
+  async approve(toolName, scope) {
+    if (scope === "once") return;
+    const data = this.readFile();
+    data.approvals[toolName] = { scope, timestamp: Date.now() };
+    this.writeFileAtomic(data);
+  }
+  async revoke(toolName) {
+    const data = this.readFile();
+    delete data.approvals[toolName];
+    this.writeFileAtomic(data);
+  }
+  async clear() {
+    this.writeFileAtomic({ approvals: {} });
+  }
+  async dispose() {
+  }
+  readFile() {
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.approvals === "object") return parsed;
+    } catch {
+    }
+    return { approvals: {} };
+  }
+  writeFileAtomic(data) {
+    const dir = path.dirname(this.filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = this.filePath + `.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+    fs.renameSync(tmpPath, this.filePath);
+  }
+};
+var CompositePermissionStore = class {
+  sessionStore;
+  projectStore;
+  userStore;
+  constructor(sessionStore, projectStore, userStore) {
+    this.sessionStore = sessionStore;
+    this.projectStore = projectStore;
+    this.userStore = userStore ?? projectStore;
+  }
+  async isApproved(toolName) {
+    return await this.sessionStore.isApproved(toolName) || await this.projectStore.isApproved(toolName) || await this.userStore.isApproved(toolName);
+  }
+  async approve(toolName, scope) {
+    if (scope === "once") return;
+    if (scope === "session") {
+      await this.sessionStore.approve(toolName, scope);
+    } else if (scope === "project") {
+      await this.projectStore.approve(toolName, scope);
+    } else {
+      await this.userStore.approve(toolName, scope);
+    }
+  }
+  async revoke(toolName) {
+    await this.sessionStore.revoke(toolName);
+    await this.projectStore.revoke(toolName);
+    await this.userStore.revoke(toolName);
+  }
+  async clear() {
+    await this.sessionStore.clear();
+    await this.projectStore.clear();
+    await this.userStore.clear();
+  }
+  async dispose() {
+    await this.sessionStore.dispose();
+    await this.projectStore.dispose();
+    if (this.userStore !== this.projectStore) {
+      await this.userStore.dispose();
+    }
+  }
+};
+function createDefaultPermissionStore(projectDir) {
+  const sessionStore = new InMemoryPermissionStore();
+  const projectPath = projectDir ? path.join(projectDir, ".agent-sdk", "permissions.json") : path.join(process.cwd(), ".agent-sdk", "permissions.json");
+  const userPath = path.join(os.homedir(), ".agent-sdk", "permissions.json");
+  const projectStore = new FilePermissionStore(projectPath);
+  const userStore = new FilePermissionStore(userPath);
+  return new CompositePermissionStore(sessionStore, projectStore, userStore);
+}
+
+export { AbortError, AgentSDKError, BackendAlreadyRegisteredError, BackendNotFoundError, BaseAgent, CompositePermissionStore, DependencyError, DisposedError, FilePermissionStore, InMemoryPermissionStore, ReentrancyError, StructuredOutputError, SubprocessError, ToolExecutionError, buildSystemPrompt, contentToText, createAgentService, createDefaultPermissionStore, getTextContent, hasBackend, isMultiPartContent, isTextContent, isToolDefinition, listBackends, messagesToPrompt, registerBackend, resetRegistry, unregisterBackend, zodToJsonSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/errors.ts","../src/registry.ts","../src/base-agent.ts","../src/utils/schema.ts","../src/utils/messages.ts","../src/permission-store.ts"],"names":[],"mappings":";;;;;AAkUO,SAAS,iBACd,IAAA,EACwB;AACxB,EAAA,OAAO,SAAA,IAAa,IAAA,IAAQ,OAAQ,IAAA,CAAwB,OAAA,KAAY,UAAA;AAC1E;AAGO,SAAS,cAAc,OAAA,EAA4C;AACxE,EAAA,OAAO,OAAO,OAAA,KAAY,QAAA;AAC5B;AAGO,SAAS,mBACd,OAAA,EAC0B;AAC1B,EAAA,OAAO,KAAA,CAAM,QAAQ,OAAO,CAAA;AAC9B;AAGO,SAAS,eAAe,OAAA,EAAiC;AAC9D,EAAA,IAAI,OAAO,OAAA,KAAY,QAAA,EAAU,OAAO,OAAA;AACxC,EAAA,OAAO,OAAA,CACJ,MAAA,CAAO,CAAC,CAAA,KAAmD,EAAE,IAAA,KAAS,MAAM,CAAA,CAC5E,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,IAAI,CAAA,CACjB,KAAK,IAAI,CAAA;AACd;;;AC1VO,IAAM,aAAA,GAAN,cAA4B,KAAA,CAAM;AAAA,EACvC,WAAA,CAAY,SAAiB,OAAA,EAAwB;AACnD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,eAAA;AAAA,EACd;AACF;AAGO,IAAM,eAAA,GAAN,cAA8B,aAAA,CAAc;AAAA,EACjD,WAAA,GAAc;AACZ,IAAA,KAAA,CAAM,0EAA0E,CAAA;AAChF,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AAAA,EACd;AACF;AAGO,IAAM,aAAA,GAAN,cAA4B,aAAA,CAAc;AAAA,EAC/C,YAAY,MAAA,EAAgB;AAC1B,IAAA,KAAA,CAAM,CAAA,EAAG,MAAM,CAAA,sCAAA,CAAwC,CAAA;AACvD,IAAA,IAAA,CAAK,IAAA,GAAO,eAAA;AAAA,EACd;AACF;AAGO,IAAM,oBAAA,GAAN,cAAmC,aAAA,CAAc;AAAA,EACtD,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA;AAAA,MACE,qBAAqB,OAAO,CAAA,6EAAA;AAAA,KAG9B;AACA,IAAA,IAAA,CAAK,IAAA,GAAO,sBAAA;AAAA,EACd;AACF;AAGO,IAAM,6BAAA,GAAN,cAA4C,aAAA,CAAc;AAAA,EAC/D,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,CAAA,SAAA,EAAY,OAAO,CAAA,kEAAA,CAAoE,CAAA;AAC7F,IAAA,IAAA,CAAK,IAAA,GAAO,+BAAA;AAAA,EACd;AACF;AAGO,IAAM,eAAA,GAAN,cAA8B,aAAA,CAAc;AAAA,EACjD,WAAA,CAAY,SAAiB,OAAA,EAAwB;AACnD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AAAA,EACd;AACF;AAGO,IAAM,eAAA,GAAN,cAA8B,aAAA,CAAc;AAAA,EACjC,WAAA;AAAA,EAEhB,YAAY,WAAA,EAAqB;AAC/B,IAAA,KAAA,CAAM,CAAA,EAAG,WAAW,CAAA,2CAAA,EAA8C,WAAW,CAAA,CAAE,CAAA;AAC/E,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AACZ,IAAA,IAAA,CAAK,WAAA,GAAc,WAAA;AAAA,EACrB;AACF;AAGO,IAAM,UAAA,GAAN,cAAyB,aAAA,CAAc;AAAA,EAC5C,WAAA,GAAc;AACZ,IAAA,KAAA,CAAM,wBAAwB,CAAA;AAC9B,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AAAA,EACd;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,aAAA,CAAc;AAAA,EACpC,QAAA;AAAA,EAEhB,WAAA,CAAY,QAAA,EAAkB,OAAA,EAAiB,OAAA,EAAwB;AACrE,IAAA,KAAA,CAAM,CAAA,MAAA,EAAS,QAAQ,CAAA,UAAA,EAAa,OAAO,IAAI,OAAO,CAAA;AACtD,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AACZ,IAAA,IAAA,CAAK,QAAA,GAAW,QAAA;AAAA,EAClB;AACF;AAGO,IAAM,qBAAA,GAAN,cAAoC,aAAA,CAAc;AAAA,EACvD,WAAA,CAAY,SAAiB,OAAA,EAAwB;AACnD,IAAA,KAAA,CAAM,CAAA,yBAAA,EAA4B,OAAO,CAAA,CAAA,EAAI,OAAO,CAAA;AACpD,IAAA,IAAA,CAAK,IAAA,GAAO,uBAAA;AAAA,EACd;AACF;;;ACpDA,IAAM,QAAA,uBAAe,GAAA,EAA2B;AAGzC,SAAS,eAAA,CACd,MACA,OAAA,EACM;AACN,EAAA,IAAI,QAAA,CAAS,GAAA,CAAI,IAAI,CAAA,EAAG;AACtB,IAAA,MAAM,IAAI,8BAA8B,IAAI,CAAA;AAAA,EAC9C;AACA,EAAA,QAAA,CAAS,IAAI,IAAA,EAAM,EAAE,OAAA,EAAoC,OAAA,EAAS,OAAO,CAAA;AAC3E;AAGO,SAAS,kBAAkB,IAAA,EAAuB;AACvD,EAAA,OAAO,QAAA,CAAS,OAAO,IAAI,CAAA;AAC7B;AAGO,SAAS,WAAW,IAAA,EAAuB;AAChD,EAAA,OAAO,QAAA,CAAS,GAAA,CAAI,IAAI,CAAA,IAAK,cAAc,IAAI,CAAA;AACjD;AAGO,SAAS,YAAA,GAAyB;AACvC,EAAA,MAAM,KAAA,GAAQ,IAAI,GAAA,CAAY,QAAA,CAAS,MAAM,CAAA;AAC7C,EAAA,KAAA,MAAW,WAAW,gBAAA,EAAkB;AACtC,IAAA,KAAA,CAAM,IAAI,OAAO,CAAA;AAAA,EACnB;AACA,EAAA,OAAO,CAAC,GAAG,KAAK,CAAA;AAClB;AAGO,SAAS,aAAA,GAAsB;AACpC,EAAA,QAAA,CAAS,KAAA,EAAM;AACjB;AAIA,IAAM,gBAAA,uBAA4C,GAAA,CAAI;AAAA,EACpD,SAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF,CAAC,CAAA;AAED,SAAS,cAAc,IAAA,EAA0C;AAC/D,EAAA,OAAO,gBAAA,CAAiB,IAAI,IAAI,CAAA;AAClC;AAIA,eAAe,mBACb,IAAA,EACyB;AACzB,EAAA,QAAQ,IAAA;AAAM,IACZ,KAAK,SAAA,EAAW;AACd,MAAA,MAAM,GAAA,GAAM,MAAM,OAAO,uBAAuB,CAAA;AAChD,MAAA,OAAO,CAAC,IAAA,KACN,GAAA,CAAI,oBAAA,CAAqB,IAA6B,CAAA;AAAA,IAC1D;AAAA,IACA,KAAK,QAAA,EAAU;AACb,MAAA,MAAM,GAAA,GAAM,MAAM,OAAO,sBAAsB,CAAA;AAC/C,MAAA,OAAO,CAAC,IAAA,KACN,GAAA,CAAI,mBAAA,CAAoB,IAA4B,CAAA;AAAA,IACxD;AAAA,IACA,KAAK,WAAA,EAAa;AAChB,MAAA,MAAM,GAAA,GAAM,MAAM,OAAO,yBAAyB,CAAA;AAClD,MAAA,OAAO,CAAC,IAAA,KACN,GAAA,CAAI,qBAAA,CAAsB,IAA8B,CAAA;AAAA,IAC5D;AAAA;AAEJ;AAaA,eAAsB,kBAAA,CACpB,MACA,OAAA,EACwB;AAExB,EAAA,MAAM,KAAA,GAAQ,QAAA,CAAS,GAAA,CAAI,IAAI,CAAA;AAC/B,EAAA,IAAI,KAAA,EAAO;AACT,IAAA,OAAO,KAAA,CAAM,QAAQ,OAAO,CAAA;AAAA,EAC9B;AAGA,EAAA,IAAI,aAAA,CAAc,IAAI,CAAA,EAAG;AACvB,IAAA,MAAM,OAAA,GAAU,MAAM,kBAAA,CAAmB,IAAI,CAAA;AAE7C,IAAA,QAAA,CAAS,IAAI,IAAA,EAAM,EAAE,OAAA,EAAS,OAAA,EAAS,MAAM,CAAA;AAC7C,IAAA,OAAO,QAAQ,OAAO,CAAA;AAAA,EACxB;AAEA,EAAA,MAAM,IAAI,qBAAqB,IAAI,CAAA;AACrC;;;AC5HO,IAAe,YAAf,MAA2C;AAAA,EACtC,KAAA,GAAoB,MAAA;AAAA,EACpB,eAAA,GAA0C,IAAA;AAAA,EACjC,MAAA;AAAA,EAEnB,YAAY,MAAA,EAAqB;AAC/B,IAAA,IAAA,CAAK,SAAS,MAAA,CAAO,MAAA,CAAO,EAAE,GAAG,QAAQ,CAAA;AAAA,EAC3C;AAAA;AAAA,EAIA,MAAM,GAAA,CACJ,MAAA,EACA,OAAA,EACsB;AACtB,IAAA,IAAA,CAAK,eAAA,EAAgB;AACrB,IAAA,IAAA,CAAK,aAAA,EAAc;AAEnB,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,qBAAA,CAAsB,OAAA,EAAS,MAAM,CAAA;AACrD,IAAA,IAAA,CAAK,KAAA,GAAQ,SAAA;AAEb,IAAA,IAAI;AACF,MAAA,MAAM,WAAsB,CAAC,EAAE,MAAM,MAAA,EAAQ,OAAA,EAAS,QAAQ,CAAA;AAC9D,MAAA,OAAO,MAAM,IAAA,CAAK,UAAA,CAAW,QAAA,EAAU,OAAA,EAAS,GAAG,MAAM,CAAA;AAAA,IAC3D,CAAA,SAAE;AACA,MAAA,IAAA,CAAK,KAAA,GAAQ,MAAA;AACb,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,MAAM,cAAA,CACJ,QAAA,EACA,OAAA,EACsB;AACtB,IAAA,IAAA,CAAK,eAAA,EAAgB;AACrB,IAAA,IAAA,CAAK,aAAA,EAAc;AAEnB,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,qBAAA,CAAsB,OAAA,EAAS,MAAM,CAAA;AACrD,IAAA,IAAA,CAAK,KAAA,GAAQ,SAAA;AAEb,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,IAAA,CAAK,UAAA,CAAW,QAAA,EAAU,OAAA,EAAS,GAAG,MAAM,CAAA;AAAA,IAC3D,CAAA,SAAE;AACA,MAAA,IAAA,CAAK,KAAA,GAAQ,MAAA;AACb,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,MAAM,aAAA,CACJ,MAAA,EACA,MAAA,EACA,OAAA,EACyB;AACzB,IAAA,IAAA,CAAK,eAAA,EAAgB;AACrB,IAAA,IAAA,CAAK,aAAA,EAAc;AAEnB,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,qBAAA,CAAsB,OAAA,EAAS,MAAM,CAAA;AACrD,IAAA,IAAA,CAAK,KAAA,GAAQ,SAAA;AAEb,IAAA,IAAI;AACF,MAAA,MAAM,WAAsB,CAAC,EAAE,MAAM,MAAA,EAAQ,OAAA,EAAS,QAAQ,CAAA;AAC9D,MAAA,OAAO,MAAM,IAAA,CAAK,oBAAA;AAAA,QAChB,QAAA;AAAA,QACA,MAAA;AAAA,QACA,OAAA;AAAA,QACA,EAAA,CAAG;AAAA,OACL;AAAA,IACF,CAAA,SAAE;AACA,MAAA,IAAA,CAAK,KAAA,GAAQ,MAAA;AACb,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,OAAO,MAAA,CACL,MAAA,EACA,OAAA,EAC2B;AAC3B,IAAA,IAAA,CAAK,eAAA,EAAgB;AACrB,IAAA,IAAA,CAAK,aAAA,EAAc;AAEnB,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,qBAAA,CAAsB,OAAA,EAAS,MAAM,CAAA;AACrD,IAAA,IAAA,CAAK,KAAA,GAAQ,WAAA;AAEb,IAAA,IAAI;AACF,MAAA,MAAM,WAAsB,CAAC,EAAE,MAAM,MAAA,EAAQ,OAAA,EAAS,QAAQ,CAAA;AAC9D,MAAA,OAAO,IAAA,CAAK,aAAA,CAAc,QAAA,EAAU,OAAA,EAAS,GAAG,MAAM,CAAA;AAAA,IACxD,CAAA,SAAE;AACA,MAAA,IAAA,CAAK,KAAA,GAAQ,MAAA;AACb,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,KAAA,GAAc;AACZ,IAAA,IAAI,KAAK,eAAA,EAAiB;AACxB,MAAA,IAAA,CAAK,gBAAgB,KAAA,EAAM;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,QAAA,GAAuB;AACrB,IAAA,OAAO,IAAA,CAAK,KAAA;AAAA,EACd;AAAA,EAEA,SAAA,GAAmC;AACjC,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EACd;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,KAAA,EAAM;AACX,IAAA,IAAA,CAAK,KAAA,GAAQ,UAAA;AAAA,EACf;AAAA;AAAA,EA4BU,eAAA,GAAwB;AAChC,IAAA,IAAI,IAAA,CAAK,KAAA,KAAU,SAAA,IAAa,IAAA,CAAK,UAAU,WAAA,EAAa;AAC1D,MAAA,MAAM,IAAI,eAAA,EAAgB;AAAA,IAC5B;AAAA,EACF;AAAA,EAEU,aAAA,GAAsB;AAC9B,IAAA,IAAI,IAAA,CAAK,UAAU,UAAA,EAAY;AAC7B,MAAA,MAAM,IAAI,cAAc,OAAO,CAAA;AAAA,IACjC;AAAA,EACF;AAAA;AAAA,EAGU,WAAW,MAAA,EAA2B;AAC9C,IAAA,IAAI,OAAO,OAAA,EAAS;AAClB,MAAA,MAAM,IAAI,UAAA,EAAW;AAAA,IACvB;AAAA,EACF;AAAA;AAAA,EAIQ,sBAAsB,cAAA,EAA+C;AAC3E,IAAA,MAAM,EAAA,GAAK,IAAI,eAAA,EAAgB;AAC/B,IAAA,IAAA,CAAK,eAAA,GAAkB,EAAA;AAEvB,IAAA,IAAI,cAAA,EAAgB;AAClB,MAAA,IAAI,eAAe,OAAA,EAAS;AAC1B,QAAA,EAAA,CAAG,KAAA,EAAM;AAAA,MACX,CAAA,MAAO;AACL,QAAA,cAAA,CAAe,gBAAA,CAAiB,OAAA,EAAS,MAAM,EAAA,CAAG,OAAM,EAAG;AAAA,UACzD,IAAA,EAAM;AAAA,SACP,CAAA;AAAA,MACH;AAAA,IACF;AAEA,IAAA,OAAO,EAAA;AAAA,EACT;AACF;;;AC1LO,SAAS,gBAAgB,MAAA,EAA4C;AAE1E,EAAA,MAAM,SAAA,GAAY,MAAA;AAClB,EAAA,IAAI,YAAA,IAAgB,MAAA,IAAU,OAAO,SAAA,CAAU,eAAe,UAAA,EAAY;AACxE,IAAA,OAAQ,UAAU,UAAA,EAA6C;AAAA,EACjE;AAEA,EAAA,OAAO,qBAAqB,MAAM,CAAA;AACpC;AAGA,SAAS,qBAAqB,MAAA,EAA4C;AACxE,EAAA,MAAM,MAAO,MAAA,CAAoD,IAAA;AACjE,EAAA,MAAM,WAAW,GAAA,CAAI,QAAA;AAErB,EAAA,QAAQ,QAAA;AAAU,IAChB,KAAK,WAAA;AACH,MAAA,OAAO,EAAE,MAAM,QAAA,EAAS;AAAA,IAC1B,KAAK,WAAA;AACH,MAAA,OAAO,EAAE,MAAM,QAAA,EAAS;AAAA,IAC1B,KAAK,YAAA;AACH,MAAA,OAAO,EAAE,MAAM,SAAA,EAAU;AAAA,IAC3B,KAAK,SAAA;AACH,MAAA,OAAO,EAAE,MAAM,MAAA,EAAO;AAAA,IACxB,KAAK,UAAA;AACH,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,OAAA;AAAA,QACN,KAAA,EAAO,oBAAA,CAAqB,GAAA,CAAI,IAAiB;AAAA,OACnD;AAAA,IACF,KAAK,WAAA,EAAa;AAChB,MAAA,MAAM,QAAS,MAAA,CAA2D,KAAA;AAC1E,MAAA,MAAM,aAAsC,EAAC;AAC7C,MAAA,MAAM,WAAqB,EAAC;AAE5B,MAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AAChD,QAAA,MAAM,WAAY,KAAA,CAAmD,IAAA;AACrE,QAAA,IAAI,QAAA,CAAS,aAAa,aAAA,EAAe;AACvC,UAAA,UAAA,CAAW,GAAG,CAAA,GAAI,oBAAA,CAAqB,QAAA,CAAS,SAAsB,CAAA;AAAA,QACxE,CAAA,MAAO;AACL,UAAA,UAAA,CAAW,GAAG,CAAA,GAAI,oBAAA,CAAqB,KAAK,CAAA;AAC5C,UAAA,QAAA,CAAS,KAAK,GAAG,CAAA;AAAA,QACnB;AAAA,MACF;AAEA,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,QAAA;AAAA,QACN,UAAA;AAAA,QACA,GAAI,QAAA,CAAS,MAAA,GAAS,IAAI,EAAE,QAAA,KAAa;AAAC,OAC5C;AAAA,IACF;AAAA,IACA,KAAK,aAAA;AACH,MAAA,OAAO,oBAAA,CAAqB,IAAI,SAAsB,CAAA;AAAA,IACxD,KAAK,SAAA;AACH,MAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,IAAA,EAAM,IAAI,MAAA,EAAmB;AAAA,IACxD;AACE,MAAA,OAAO,EAAC;AAAA;AAEd;;;ACzDO,SAAS,iBAAiB,QAAA,EAA6B;AAC5D,EAAA,OAAO,QAAA,CACJ,GAAA,CAAI,CAAC,GAAA,KAAQ;AACZ,IAAA,QAAQ,IAAI,IAAA;AAAM,MAChB,KAAK,MAAA;AACH,QAAA,OAAO,aAAA,CAAc,IAAI,OAAO,CAAA;AAAA,MAClC,KAAK,WAAA;AACH,QAAA,OAAO,aAAA,CAAc,IAAI,OAAO,CAAA;AAAA,MAClC,KAAK,QAAA;AACH,QAAA,OAAO,GAAA,CAAI,OAAA;AAAA,MACb,KAAK,MAAA;AACH,QAAA,OAAO,IAAI,OAAA,IAAW,EAAA;AAAA;AAC1B,EACF,CAAC,CAAA,CACA,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,MAAM,CAAA;AAChB;AAGO,SAAS,cAAc,OAAA,EAAiC;AAC7D,EAAA,OAAO,eAAe,OAAO,CAAA;AAC/B;AAGO,SAAS,iBAAA,CACd,MACA,iBAAA,EACQ;AACR,EAAA,IAAI,CAAC,mBAAmB,OAAO,IAAA;AAC/B,EAAA,OAAO,GAAG,IAAI;;AAAA,EAAO,iBAAiB,CAAA,CAAA;AACxC;ACNO,IAAM,0BAAN,MAA0D;AAAA,EACvD,SAAA,uBAAgB,GAAA,EAA6B;AAAA,EAErD,MAAM,WAAW,QAAA,EAAoC;AACnD,IAAA,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,QAAQ,CAAA;AAAA,EACpC;AAAA,EAEA,MAAM,OAAA,CAAQ,QAAA,EAAkB,KAAA,EAAuC;AACrE,IAAA,IAAI,UAAU,MAAA,EAAQ;AACtB,IAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,QAAA,EAAU,KAAK,CAAA;AAAA,EACpC;AAAA,EAEA,MAAM,OAAO,QAAA,EAAiC;AAC5C,IAAA,IAAA,CAAK,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAChC;AAAA,EAEA,MAAM,KAAA,GAAuB;AAC3B,IAAA,IAAA,CAAK,UAAU,KAAA,EAAM;AAAA,EACvB;AAAA,EAEA,MAAM,OAAA,GAAyB;AAC7B,IAAA,IAAA,CAAK,UAAU,KAAA,EAAM;AAAA,EACvB;AACF;AAcO,IAAM,sBAAN,MAAsD;AAAA,EAC1C,QAAA;AAAA,EAEjB,YAAY,QAAA,EAAkB;AAC5B,IAAA,IAAA,CAAK,QAAA,GAAgB,aAAQ,QAAQ,CAAA;AAAA,EACvC;AAAA,EAEA,MAAM,WAAW,QAAA,EAAoC;AACnD,IAAA,MAAM,IAAA,GAAO,KAAK,QAAA,EAAS;AAC3B,IAAA,OAAO,YAAY,IAAA,CAAK,SAAA;AAAA,EAC1B;AAAA,EAEA,MAAM,OAAA,CAAQ,QAAA,EAAkB,KAAA,EAAuC;AACrE,IAAA,IAAI,UAAU,MAAA,EAAQ;AACtB,IAAA,MAAM,IAAA,GAAO,KAAK,QAAA,EAAS;AAC3B,IAAA,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAA,GAAI,EAAE,OAAO,SAAA,EAAW,IAAA,CAAK,KAAI,EAAE;AAC1D,IAAA,IAAA,CAAK,gBAAgB,IAAI,CAAA;AAAA,EAC3B;AAAA,EAEA,MAAM,OAAO,QAAA,EAAiC;AAC5C,IAAA,MAAM,IAAA,GAAO,KAAK,QAAA,EAAS;AAC3B,IAAA,OAAO,IAAA,CAAK,UAAU,QAAQ,CAAA;AAC9B,IAAA,IAAA,CAAK,gBAAgB,IAAI,CAAA;AAAA,EAC3B;AAAA,EAEA,MAAM,KAAA,GAAuB;AAC3B,IAAA,IAAA,CAAK,eAAA,CAAgB,EAAE,SAAA,EAAW,IAAI,CAAA;AAAA,EACxC;AAAA,EAEA,MAAM,OAAA,GAAyB;AAAA,EAE/B;AAAA,EAEQ,QAAA,GAA0B;AAChC,IAAA,IAAI;AACF,MAAA,MAAM,GAAA,GAAS,EAAA,CAAA,YAAA,CAAa,IAAA,CAAK,QAAA,EAAU,OAAO,CAAA;AAClD,MAAA,MAAM,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AAC7B,MAAA,IAAI,MAAA,IAAU,OAAO,MAAA,CAAO,SAAA,KAAc,UAAU,OAAO,MAAA;AAAA,IAC7D,CAAA,CAAA,MAAQ;AAAA,IAER;AACA,IAAA,OAAO,EAAE,SAAA,EAAW,EAAC,EAAE;AAAA,EACzB;AAAA,EAEQ,gBAAgB,IAAA,EAA2B;AACjD,IAAA,MAAM,GAAA,GAAW,IAAA,CAAA,OAAA,CAAQ,IAAA,CAAK,QAAQ,CAAA;AACtC,IAAG,EAAA,CAAA,SAAA,CAAU,GAAA,EAAK,EAAE,SAAA,EAAW,MAAM,CAAA;AACrC,IAAA,MAAM,OAAA,GAAU,KAAK,QAAA,GAAW,CAAA,KAAA,EAAQ,QAAQ,GAAG,CAAA,CAAA,EAAI,IAAA,CAAK,GAAA,EAAK,CAAA,CAAA;AACjE,IAAG,EAAA,CAAA,aAAA,CAAc,SAAS,IAAA,CAAK,SAAA,CAAU,MAAM,IAAA,EAAM,CAAC,GAAG,OAAO,CAAA;AAChE,IAAG,EAAA,CAAA,UAAA,CAAW,OAAA,EAAS,IAAA,CAAK,QAAQ,CAAA;AAAA,EACtC;AACF;AAWO,IAAM,2BAAN,MAA2D;AAAA,EAC/C,YAAA;AAAA,EACA,YAAA;AAAA,EACA,SAAA;AAAA,EAEjB,WAAA,CACE,YAAA,EACA,YAAA,EACA,SAAA,EACA;AACA,IAAA,IAAA,CAAK,YAAA,GAAe,YAAA;AACpB,IAAA,IAAA,CAAK,YAAA,GAAe,YAAA;AACpB,IAAA,IAAA,CAAK,YAAY,SAAA,IAAa,YAAA;AAAA,EAChC;AAAA,EAEA,MAAM,WAAW,QAAA,EAAoC;AACnD,IAAA,OACG,MAAM,IAAA,CAAK,YAAA,CAAa,UAAA,CAAW,QAAQ,KAC3C,MAAM,IAAA,CAAK,YAAA,CAAa,UAAA,CAAW,QAAQ,CAAA,IAC3C,MAAM,IAAA,CAAK,SAAA,CAAU,WAAW,QAAQ,CAAA;AAAA,EAE7C;AAAA,EAEA,MAAM,OAAA,CAAQ,QAAA,EAAkB,KAAA,EAAuC;AACrE,IAAA,IAAI,UAAU,MAAA,EAAQ;AACtB,IAAA,IAAI,UAAU,SAAA,EAAW;AACvB,MAAA,MAAM,IAAA,CAAK,YAAA,CAAa,OAAA,CAAQ,QAAA,EAAU,KAAK,CAAA;AAAA,IACjD,CAAA,MAAA,IAAW,UAAU,SAAA,EAAW;AAC9B,MAAA,MAAM,IAAA,CAAK,YAAA,CAAa,OAAA,CAAQ,QAAA,EAAU,KAAK,CAAA;AAAA,IACjD,CAAA,MAAO;AAEL,MAAA,MAAM,IAAA,CAAK,SAAA,CAAU,OAAA,CAAQ,QAAA,EAAU,KAAK,CAAA;AAAA,IAC9C;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,QAAA,EAAiC;AAC5C,IAAA,MAAM,IAAA,CAAK,YAAA,CAAa,MAAA,CAAO,QAAQ,CAAA;AACvC,IAAA,MAAM,IAAA,CAAK,YAAA,CAAa,MAAA,CAAO,QAAQ,CAAA;AACvC,IAAA,MAAM,IAAA,CAAK,SAAA,CAAU,MAAA,CAAO,QAAQ,CAAA;AAAA,EACtC;AAAA,EAEA,MAAM,KAAA,GAAuB;AAC3B,IAAA,MAAM,IAAA,CAAK,aAAa,KAAA,EAAM;AAC9B,IAAA,MAAM,IAAA,CAAK,aAAa,KAAA,EAAM;AAC9B,IAAA,MAAM,IAAA,CAAK,UAAU,KAAA,EAAM;AAAA,EAC7B;AAAA,EAEA,MAAM,OAAA,GAAyB;AAC7B,IAAA,MAAM,IAAA,CAAK,aAAa,OAAA,EAAQ;AAChC,IAAA,MAAM,IAAA,CAAK,aAAa,OAAA,EAAQ;AAChC,IAAA,IAAI,IAAA,CAAK,SAAA,KAAc,IAAA,CAAK,YAAA,EAAc;AACxC,MAAA,MAAM,IAAA,CAAK,UAAU,OAAA,EAAQ;AAAA,IAC/B;AAAA,EACF;AACF;AAKO,SAAS,6BACd,UAAA,EAC0B;AAC1B,EAAA,MAAM,YAAA,GAAe,IAAI,uBAAA,EAAwB;AACjD,EAAA,MAAM,WAAA,GAAc,UAAA,GACX,IAAA,CAAA,IAAA,CAAK,UAAA,EAAY,YAAA,EAAc,kBAAkB,CAAA,GACjD,IAAA,CAAA,IAAA,CAAK,OAAA,CAAQ,GAAA,EAAI,EAAG,YAAA,EAAc,kBAAkB,CAAA;AAC7D,EAAA,MAAM,QAAA,GAAgB,IAAA,CAAA,IAAA,CAAQ,EAAA,CAAA,OAAA,EAAQ,EAAG,cAAc,kBAAkB,CAAA;AACzE,EAAA,MAAM,YAAA,GAAe,IAAI,mBAAA,CAAoB,WAAW,CAAA;AACxD,EAAA,MAAM,SAAA,GAAY,IAAI,mBAAA,CAAoB,QAAQ,CAAA;AAClD,EAAA,OAAO,IAAI,wBAAA,CAAyB,YAAA,EAAc,YAAA,EAAc,SAAS,CAAA;AAC3E","file":"index.js","sourcesContent":["import type { z } from \"zod\";\nimport type { IPermissionStore } from \"./permission-store.js\";\n\n// ─── JSON Value ────────────────────────────────────────────────\n\n/** JSON-serializable value used for tool arguments and results */\nexport type JSONValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JSONValue[]\n  | { [key: string]: JSONValue };\n\n// ─── Message Content ───────────────────────────────────────────\n\n/** Message content — plain string or array of text/image parts */\nexport type MessageContent = string | Array<ContentPart>;\n\n/** Individual content part within a multi-part message */\nexport type ContentPart =\n  | { type: \"text\"; text: string }\n  | { type: \"image\"; data: string; mimeType: string };\n\n// ─── Tool System (B1: Declaration/Definition split) ────────────\n\n/** What the LLM sees — name, description, schema. Passed to all backends. */\nexport interface ToolDeclaration<TParams = unknown> {\n  name: string;\n  description: string;\n  parameters: z.ZodType<TParams>;\n  needsApproval?: boolean;\n  metadata?: {\n    category?: string;\n    icon?: string;\n    tags?: string[];\n  };\n}\n\n/** Full tool with execute function. Required for API-based backends.\n *  CLI backends extract declaration; execute map held internally. */\nexport interface ToolDefinition<TParams = unknown>\n  extends ToolDeclaration<TParams> {\n  execute: (params: TParams) => Promise<JSONValue> | JSONValue;\n}\n\n// ─── Tool Calls / Results ──────────────────────────────────────\n\n/** A tool call made by the LLM during execution */\nexport interface ToolCall {\n  id: string;\n  name: string;\n  args: JSONValue;\n}\n\n/** Result of executing a tool call */\nexport interface ToolResult {\n  toolCallId: string;\n  name: string;\n  result: JSONValue;\n  isError?: boolean;\n}\n\n// ─── Messages (Discriminated Union) ────────────────────────────\n\n/** Conversation message — discriminated union on `role` */\nexport type Message =\n  | { role: \"user\"; content: MessageContent }\n  | { role: \"assistant\"; content: MessageContent; toolCalls?: ToolCall[] }\n  | { role: \"tool\"; content?: string; toolResults: ToolResult[] }\n  | { role: \"system\"; content: string };\n\n// ─── Permission System (v3.1 with scopes) ──────────────────────\n\n/** Scope for \"remember this decision\" */\nexport type PermissionScope = \"once\" | \"session\" | \"project\" | \"always\";\n\n/** What the permission callback receives */\nexport interface PermissionRequest {\n  toolName: string;\n  toolArgs: Record<string, unknown>;\n  /** SDK-suggested scope (from Claude CLI's suggestions) */\n  suggestedScope?: PermissionScope;\n  /** Original SDK permission request (for pass-through) */\n  rawSDKRequest?: unknown;\n}\n\n/** What the permission callback returns */\nexport interface PermissionDecision {\n  allowed: boolean;\n  /** How long to remember this decision */\n  scope?: PermissionScope;\n  /** Modified tool arguments (tool args may be altered by user) */\n  modifiedInput?: Record<string, unknown>;\n  /** Denial reason (if denied) */\n  reason?: string;\n}\n\n/** Permission callback signature */\nexport type PermissionCallback = (\n  request: PermissionRequest,\n  signal: AbortSignal,\n) => Promise<PermissionDecision>;\n\n// ─── User Input (Ask User) ────────────────────────────────────\n\n/** Request for user input — separate from permissions */\nexport interface UserInputRequest {\n  question: string;\n  choices?: string[];\n  /** Whether to allow freeform text input (default: true) */\n  allowFreeform?: boolean;\n}\n\n/** Response from user to an input request */\nexport interface UserInputResponse {\n  answer: string;\n  /** true if user typed a custom answer instead of selecting a choice */\n  wasFreeform: boolean;\n  /** Index of selected choice (if choice was selected) */\n  selectedChoiceIndex?: number;\n}\n\n// ─── Supervisor Hooks ──────────────────────────────────────────\n\n/** Hooks for supervisor/UI to intercept agent actions */\nexport interface SupervisorHooks {\n  onPermission?: PermissionCallback;\n  onAskUser?: (\n    request: UserInputRequest,\n    signal: AbortSignal,\n  ) => Promise<UserInputResponse>;\n}\n\n// ─── Structured Output ─────────────────────────────────────────\n\n/** Configuration for typed structured output from LLM */\nexport interface StructuredOutputConfig<T = unknown> {\n  schema: z.ZodType<T>;\n  name?: string;\n  description?: string;\n}\n\n// ─── Agent Events (Streaming) ──────────────────────────────────\n\n/** Events emitted during streaming agent execution */\nexport type AgentEvent =\n  | { type: \"text_delta\"; text: string }\n  | { type: \"tool_call_start\"; toolName: string; args: JSONValue }\n  | { type: \"tool_call_end\"; toolName: string; result: JSONValue }\n  | { type: \"permission_request\"; request: PermissionRequest }\n  | {\n      type: \"permission_response\";\n      toolName: string;\n      decision: PermissionDecision;\n    }\n  | { type: \"ask_user\"; request: UserInputRequest }\n  | { type: \"ask_user_response\"; answer: string }\n  | { type: \"thinking_start\" }\n  | { type: \"thinking_end\" }\n  | {\n      type: \"usage_update\";\n      promptTokens: number;\n      completionTokens: number;\n    }\n  | { type: \"error\"; error: string; recoverable: boolean }\n  | { type: \"done\"; finalOutput: string | null; structuredOutput?: unknown };\n\n// ─── Run Options ───────────────────────────────────────────────\n\n/** Options passed to agent.run() / agent.stream() */\nexport interface RunOptions {\n  /** AbortSignal for cancellation */\n  signal?: AbortSignal;\n  /** Arbitrary context passed to the agent run */\n  context?: Record<string, unknown>;\n}\n\n// ─── Agent Configuration ───────────────────────────────────────\n\n/** LLM model parameters */\nexport interface ModelParams {\n  temperature?: number;\n  maxTokens?: number;\n  topP?: number;\n  stopSequences?: string[];\n}\n\n/** Timeout configuration for agent operations */\nexport interface TimeoutConfig {\n  /** Max time for entire agent run (ms) */\n  total?: number;\n  /** Max time for a single tool execution (ms) */\n  perTool?: number;\n  /** Max time for a single LLM request (ms) */\n  perLLMRequest?: number;\n}\n\n/** Error handling strategy configuration */\nexport interface ErrorHandlingConfig {\n  /** What to do when a tool throws */\n  onToolError?: \"fail\" | \"continue\" | \"ask-llm\";\n  /** Retry config for transient LLM failures */\n  retryLLM?: { maxAttempts: number; backoffMs: number };\n  /** Global error callback for monitoring */\n  onError?: (\n    error: Error,\n    context: { phase: \"tool\" | \"llm\" | \"permission\" | \"ask-user\" },\n  ) => void;\n}\n\n/** Configuration for creating an agent */\nexport interface AgentConfig {\n  model?: string;\n  modelParams?: ModelParams;\n  systemPrompt: string;\n  tools: ToolDefinition[];\n  supervisor?: SupervisorHooks;\n  maxTurns?: number;\n  timeout?: TimeoutConfig;\n  errorHandling?: ErrorHandlingConfig;\n  /** Pluggable store for persisting permission scope decisions across runs */\n  permissionStore?: IPermissionStore;\n}\n\n// ─── Agent Result (Generic) ────────────────────────────────────\n\n/** Result of an agent run, generic over structured output type T */\nexport interface AgentResult<T = void> {\n  output: string | null;\n  structuredOutput: T extends void ? undefined : T;\n  toolCalls: Array<{\n    toolName: string;\n    args: JSONValue;\n    result: JSONValue;\n    approved: boolean;\n  }>;\n  messages: Message[];\n  usage?: { promptTokens: number; completionTokens: number };\n}\n\n// ─── Agent State ───────────────────────────────────────────────\n\n/** Agent lifecycle state */\nexport type AgentState = \"idle\" | \"running\" | \"streaming\" | \"disposed\";\n\n// ─── Agent Interface ───────────────────────────────────────────\n\n/** Core agent interface — run prompts, stream events, manage lifecycle */\nexport interface IAgent {\n  run(prompt: MessageContent, options?: RunOptions): Promise<AgentResult>;\n  runWithContext(\n    messages: Message[],\n    options?: RunOptions,\n  ): Promise<AgentResult>;\n  runStructured<T>(\n    prompt: MessageContent,\n    schema: StructuredOutputConfig<T>,\n    options?: RunOptions,\n  ): Promise<AgentResult<T>>;\n  stream(\n    prompt: MessageContent,\n    options?: RunOptions,\n  ): AsyncIterable<AgentEvent>;\n  abort(): void;\n  getState(): AgentState;\n  getConfig(): Readonly<AgentConfig>;\n  /** Release resources. After dispose(), agent must not be used. */\n  dispose(): void;\n}\n\n// ─── Service Interface ─────────────────────────────────────────\n\n/** Model metadata returned by listModels() */\nexport interface ModelInfo {\n  id: string;\n  name?: string;\n  provider?: string;\n}\n\n/** Result of backend validation check */\nexport interface ValidationResult {\n  valid: boolean;\n  errors: string[];\n}\n\n/** Backend service interface — creates agents, lists models, validates config */\nexport interface IAgentService {\n  readonly name: string;\n  createAgent(config: AgentConfig): IAgent;\n  listModels(): Promise<ModelInfo[]>;\n  validate(): Promise<ValidationResult>;\n  dispose(): Promise<void>;\n}\n\n// ─── Backend Options ───────────────────────────────────────────\n\n/** Options for Copilot CLI backend */\nexport interface CopilotBackendOptions {\n  cliPath?: string;\n  workingDirectory?: string;\n  githubToken?: string;\n  useLoggedInUser?: boolean;\n}\n\n/** Options for Claude CLI backend */\nexport interface ClaudeBackendOptions {\n  cliPath?: string;\n  workingDirectory?: string;\n  maxTurns?: number;\n}\n\n/** Options for Vercel AI SDK backend */\nexport interface VercelAIBackendOptions {\n  apiKey: string;\n  provider?: string;\n  baseUrl?: string;\n}\n\n// ─── Type Guards ───────────────────────────────────────────────\n\n/** Type guard: checks if a ToolDeclaration has an execute function (i.e., is a ToolDefinition) */\nexport function isToolDefinition(\n  tool: ToolDeclaration,\n): tool is ToolDefinition {\n  return \"execute\" in tool && typeof (tool as ToolDefinition).execute === \"function\";\n}\n\n/** Type guard: checks if MessageContent is plain string */\nexport function isTextContent(content: MessageContent): content is string {\n  return typeof content === \"string\";\n}\n\n/** Type guard: checks if MessageContent is multi-part array */\nexport function isMultiPartContent(\n  content: MessageContent,\n): content is ContentPart[] {\n  return Array.isArray(content);\n}\n\n/** Extract text from MessageContent regardless of format */\nexport function getTextContent(content: MessageContent): string {\n  if (typeof content === \"string\") return content;\n  return content\n    .filter((p): p is Extract<ContentPart, { type: \"text\" }> => p.type === \"text\")\n    .map((p) => p.text)\n    .join(\"\\n\");\n}\n","/** Base error class for agent-sdk */\nexport class AgentSDKError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"AgentSDKError\";\n  }\n}\n\n/** Thrown when agent.run() is called while already running (M8 re-entrancy guard) */\nexport class ReentrancyError extends AgentSDKError {\n  constructor() {\n    super(\"Agent is already running. Await the current run before starting another.\");\n    this.name = \"ReentrancyError\";\n  }\n}\n\n/** Thrown when an operation is attempted on a disposed agent/service */\nexport class DisposedError extends AgentSDKError {\n  constructor(entity: string) {\n    super(`${entity} has been disposed and cannot be used.`);\n    this.name = \"DisposedError\";\n  }\n}\n\n/** Thrown when a backend is not found in the registry */\nexport class BackendNotFoundError extends AgentSDKError {\n  constructor(backend: string) {\n    super(\n      `Unknown backend: \"${backend}\". ` +\n      `Built-in: copilot, claude, vercel-ai. ` +\n      `Custom: use registerBackend() first.`,\n    );\n    this.name = \"BackendNotFoundError\";\n  }\n}\n\n/** Thrown when a backend is already registered */\nexport class BackendAlreadyRegisteredError extends AgentSDKError {\n  constructor(backend: string) {\n    super(`Backend \"${backend}\" is already registered. Use a different name or unregister first.`);\n    this.name = \"BackendAlreadyRegisteredError\";\n  }\n}\n\n/** Thrown when subprocess management fails */\nexport class SubprocessError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"SubprocessError\";\n  }\n}\n\n/** Thrown when a required peer dependency is not installed */\nexport class DependencyError extends AgentSDKError {\n  public readonly packageName: string;\n\n  constructor(packageName: string) {\n    super(`${packageName} is not installed. Install it: npm install ${packageName}`);\n    this.name = \"DependencyError\";\n    this.packageName = packageName;\n  }\n}\n\n/** Thrown when an agent run is aborted */\nexport class AbortError extends AgentSDKError {\n  constructor() {\n    super(\"Agent run was aborted.\");\n    this.name = \"AbortError\";\n  }\n}\n\n/** Thrown when a tool execution fails */\nexport class ToolExecutionError extends AgentSDKError {\n  public readonly toolName: string;\n\n  constructor(toolName: string, message: string, options?: ErrorOptions) {\n    super(`Tool \"${toolName}\" failed: ${message}`, options);\n    this.name = \"ToolExecutionError\";\n    this.toolName = toolName;\n  }\n}\n\n/** Thrown when structured output parsing fails */\nexport class StructuredOutputError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(`Structured output error: ${message}`, options);\n    this.name = \"StructuredOutputError\";\n  }\n}\n","import type {\n  IAgentService,\n  CopilotBackendOptions,\n  ClaudeBackendOptions,\n  VercelAIBackendOptions,\n} from \"./types.js\";\nimport {\n  BackendNotFoundError,\n  BackendAlreadyRegisteredError,\n} from \"./errors.js\";\n\n// ─── Backend Factory Types ──────────────────────────────────────\n\n/** Factory function that creates a backend service from options */\nexport type BackendFactory<TOptions = unknown> = (\n  options: TOptions,\n) => IAgentService | Promise<IAgentService>;\n\n/** Map of built-in backend names to their options types */\nexport interface BackendOptionsMap {\n  copilot: CopilotBackendOptions;\n  claude: ClaudeBackendOptions;\n  \"vercel-ai\": VercelAIBackendOptions;\n}\n\n/** All known backend names (built-in + custom) */\nexport type BuiltinBackendName = keyof BackendOptionsMap;\n\n// ─── Registry ───────────────────────────────────────────────────\n\ninterface RegistryEntry {\n  factory: BackendFactory;\n  /** Whether this is a built-in backend loaded lazily */\n  builtin: boolean;\n}\n\nconst registry = new Map<string, RegistryEntry>();\n\n/** Register a custom backend factory */\nexport function registerBackend<TOptions = unknown>(\n  name: string,\n  factory: BackendFactory<TOptions>,\n): void {\n  if (registry.has(name)) {\n    throw new BackendAlreadyRegisteredError(name);\n  }\n  registry.set(name, { factory: factory as BackendFactory, builtin: false });\n}\n\n/** Unregister a backend (primarily for testing) */\nexport function unregisterBackend(name: string): boolean {\n  return registry.delete(name);\n}\n\n/** Check if a backend is registered */\nexport function hasBackend(name: string): boolean {\n  return registry.has(name) || isBuiltinName(name);\n}\n\n/** List all registered backend names */\nexport function listBackends(): string[] {\n  const names = new Set<string>(registry.keys());\n  for (const builtin of BUILTIN_BACKENDS) {\n    names.add(builtin);\n  }\n  return [...names];\n}\n\n/** Reset registry to initial state (for testing) */\nexport function resetRegistry(): void {\n  registry.clear();\n}\n\n// ─── Built-in Backend Names ─────────────────────────────────────\n\nconst BUILTIN_BACKENDS: ReadonlySet<string> = new Set([\n  \"copilot\",\n  \"claude\",\n  \"vercel-ai\",\n]);\n\nfunction isBuiltinName(name: string): name is BuiltinBackendName {\n  return BUILTIN_BACKENDS.has(name);\n}\n\n// ─── Lazy Import for Built-in Backends ──────────────────────────\n\nasync function loadBuiltinFactory(\n  name: BuiltinBackendName,\n): Promise<BackendFactory> {\n  switch (name) {\n    case \"copilot\": {\n      const mod = await import(\"./backends/copilot.js\");\n      return (opts: unknown) =>\n        mod.createCopilotService(opts as CopilotBackendOptions);\n    }\n    case \"claude\": {\n      const mod = await import(\"./backends/claude.js\");\n      return (opts: unknown) =>\n        mod.createClaudeService(opts as ClaudeBackendOptions);\n    }\n    case \"vercel-ai\": {\n      const mod = await import(\"./backends/vercel-ai.js\");\n      return (opts: unknown) =>\n        mod.createVercelAIService(opts as VercelAIBackendOptions);\n    }\n  }\n}\n\n// ─── Type-Safe Factory (B6) ─────────────────────────────────────\n\n/** Create a backend service with type-safe options */\nexport async function createAgentService<K extends BuiltinBackendName>(\n  name: K,\n  options: BackendOptionsMap[K],\n): Promise<IAgentService>;\nexport async function createAgentService(\n  name: string,\n  options: unknown,\n): Promise<IAgentService>;\nexport async function createAgentService(\n  name: string,\n  options: unknown,\n): Promise<IAgentService> {\n  // Check custom registry first\n  const entry = registry.get(name);\n  if (entry) {\n    return entry.factory(options);\n  }\n\n  // Try built-in lazy load\n  if (isBuiltinName(name)) {\n    const factory = await loadBuiltinFactory(name);\n    // Cache for future calls\n    registry.set(name, { factory, builtin: true });\n    return factory(options);\n  }\n\n  throw new BackendNotFoundError(name);\n}\n","import type {\n  IAgent,\n  AgentConfig,\n  AgentState,\n  AgentResult,\n  AgentEvent,\n  MessageContent,\n  Message,\n  RunOptions,\n  StructuredOutputConfig,\n} from \"./types.js\";\nimport { ReentrancyError, DisposedError, AbortError } from \"./errors.js\";\n\n/** Abstract base agent with shared lifecycle logic.\n *  Concrete backends extend this and implement the protected _run/_stream methods. */\nexport abstract class BaseAgent implements IAgent {\n  protected state: AgentState = \"idle\";\n  protected abortController: AbortController | null = null;\n  protected readonly config: AgentConfig;\n\n  constructor(config: AgentConfig) {\n    this.config = Object.freeze({ ...config });\n  }\n\n  // ─── Public Interface ─────────────────────────────────────────\n\n  async run(\n    prompt: MessageContent,\n    options?: RunOptions,\n  ): Promise<AgentResult> {\n    this.guardReentrancy();\n    this.guardDisposed();\n\n    const ac = this.createAbortController(options?.signal);\n    this.state = \"running\";\n\n    try {\n      const messages: Message[] = [{ role: \"user\", content: prompt }];\n      return await this.executeRun(messages, options, ac.signal);\n    } finally {\n      this.state = \"idle\";\n      this.abortController = null;\n    }\n  }\n\n  async runWithContext(\n    messages: Message[],\n    options?: RunOptions,\n  ): Promise<AgentResult> {\n    this.guardReentrancy();\n    this.guardDisposed();\n\n    const ac = this.createAbortController(options?.signal);\n    this.state = \"running\";\n\n    try {\n      return await this.executeRun(messages, options, ac.signal);\n    } finally {\n      this.state = \"idle\";\n      this.abortController = null;\n    }\n  }\n\n  async runStructured<T>(\n    prompt: MessageContent,\n    schema: StructuredOutputConfig<T>,\n    options?: RunOptions,\n  ): Promise<AgentResult<T>> {\n    this.guardReentrancy();\n    this.guardDisposed();\n\n    const ac = this.createAbortController(options?.signal);\n    this.state = \"running\";\n\n    try {\n      const messages: Message[] = [{ role: \"user\", content: prompt }];\n      return await this.executeRunStructured(\n        messages,\n        schema,\n        options,\n        ac.signal,\n      );\n    } finally {\n      this.state = \"idle\";\n      this.abortController = null;\n    }\n  }\n\n  async *stream(\n    prompt: MessageContent,\n    options?: RunOptions,\n  ): AsyncIterable<AgentEvent> {\n    this.guardReentrancy();\n    this.guardDisposed();\n\n    const ac = this.createAbortController(options?.signal);\n    this.state = \"streaming\";\n\n    try {\n      const messages: Message[] = [{ role: \"user\", content: prompt }];\n      yield* this.executeStream(messages, options, ac.signal);\n    } finally {\n      this.state = \"idle\";\n      this.abortController = null;\n    }\n  }\n\n  abort(): void {\n    if (this.abortController) {\n      this.abortController.abort();\n    }\n  }\n\n  getState(): AgentState {\n    return this.state;\n  }\n\n  getConfig(): Readonly<AgentConfig> {\n    return this.config;\n  }\n\n  /** Mark agent as disposed. Override to add cleanup. */\n  dispose(): void {\n    this.abort();\n    this.state = \"disposed\";\n  }\n\n  // ─── Abstract Methods (implemented by backends) ───────────────\n\n  /** Execute a blocking run. Backend implements the actual LLM call. */\n  protected abstract executeRun(\n    messages: Message[],\n    options: RunOptions | undefined,\n    signal: AbortSignal,\n  ): Promise<AgentResult>;\n\n  /** Execute a structured output run. Backend implements parsing. */\n  protected abstract executeRunStructured<T>(\n    messages: Message[],\n    schema: StructuredOutputConfig<T>,\n    options: RunOptions | undefined,\n    signal: AbortSignal,\n  ): Promise<AgentResult<T>>;\n\n  /** Execute a streaming run. Backend yields events. */\n  protected abstract executeStream(\n    messages: Message[],\n    options: RunOptions | undefined,\n    signal: AbortSignal,\n  ): AsyncIterable<AgentEvent>;\n\n  // ─── Guards ───────────────────────────────────────────────────\n\n  protected guardReentrancy(): void {\n    if (this.state === \"running\" || this.state === \"streaming\") {\n      throw new ReentrancyError();\n    }\n  }\n\n  protected guardDisposed(): void {\n    if (this.state === \"disposed\") {\n      throw new DisposedError(\"Agent\");\n    }\n  }\n\n  /** Throw AbortError if signal is already aborted */\n  protected checkAbort(signal: AbortSignal): void {\n    if (signal.aborted) {\n      throw new AbortError();\n    }\n  }\n\n  // ─── Internal Helpers ─────────────────────────────────────────\n\n  private createAbortController(externalSignal?: AbortSignal): AbortController {\n    const ac = new AbortController();\n    this.abortController = ac;\n\n    if (externalSignal) {\n      if (externalSignal.aborted) {\n        ac.abort();\n      } else {\n        externalSignal.addEventListener(\"abort\", () => ac.abort(), {\n          once: true,\n        });\n      }\n    }\n\n    return ac;\n  }\n}\n","import type { z } from \"zod\";\n\n/** Convert a Zod schema to JSON Schema.\n *  Uses zod's built-in jsonSchema() if available, falls back to _def extraction. */\nexport function zodToJsonSchema(schema: z.ZodType): Record<string, unknown> {\n  // Try zod's built-in jsonSchema() method (available in zod v3.24+)\n  const schemaAny = schema as unknown as Record<string, unknown>;\n  if (\"jsonSchema\" in schema && typeof schemaAny.jsonSchema === \"function\") {\n    return (schemaAny.jsonSchema as () => Record<string, unknown>)();\n  }\n\n  return extractSchemaFromDef(schema);\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\nfunction extractSchemaFromDef(schema: z.ZodType): Record<string, unknown> {\n  const def = (schema as unknown as { _def: Record<string, any> })._def;\n  const typeName = def.typeName as string;\n\n  switch (typeName) {\n    case \"ZodString\":\n      return { type: \"string\" };\n    case \"ZodNumber\":\n      return { type: \"number\" };\n    case \"ZodBoolean\":\n      return { type: \"boolean\" };\n    case \"ZodNull\":\n      return { type: \"null\" };\n    case \"ZodArray\":\n      return {\n        type: \"array\",\n        items: extractSchemaFromDef(def.type as z.ZodType),\n      };\n    case \"ZodObject\": {\n      const shape = (schema as unknown as { shape: Record<string, z.ZodType> }).shape;\n      const properties: Record<string, unknown> = {};\n      const required: string[] = [];\n\n      for (const [key, value] of Object.entries(shape)) {\n        const valueDef = (value as unknown as { _def: Record<string, any> })._def;\n        if (valueDef.typeName === \"ZodOptional\") {\n          properties[key] = extractSchemaFromDef(valueDef.innerType as z.ZodType);\n        } else {\n          properties[key] = extractSchemaFromDef(value);\n          required.push(key);\n        }\n      }\n\n      return {\n        type: \"object\",\n        properties,\n        ...(required.length > 0 ? { required } : {}),\n      };\n    }\n    case \"ZodOptional\":\n      return extractSchemaFromDef(def.innerType as z.ZodType);\n    case \"ZodEnum\":\n      return { type: \"string\", enum: def.values as string[] };\n    default:\n      return {};\n  }\n}\n/* eslint-enable @typescript-eslint/no-explicit-any */\n","import type { Message, MessageContent } from \"../types.js\";\nimport { getTextContent } from \"../types.js\";\n\n/** Convert our Message[] to a flat prompt string (for CLIs that accept text) */\nexport function messagesToPrompt(messages: Message[]): string {\n  return messages\n    .map((msg) => {\n      switch (msg.role) {\n        case \"user\":\n          return contentToText(msg.content);\n        case \"assistant\":\n          return contentToText(msg.content);\n        case \"system\":\n          return msg.content;\n        case \"tool\":\n          return msg.content ?? \"\";\n      }\n    })\n    .filter(Boolean)\n    .join(\"\\n\\n\");\n}\n\n/** Convert MessageContent to plain text */\nexport function contentToText(content: MessageContent): string {\n  return getTextContent(content);\n}\n\n/** Build a system prompt with optional structured output instruction */\nexport function buildSystemPrompt(\n  base: string,\n  schemaInstruction?: string,\n): string {\n  if (!schemaInstruction) return base;\n  return `${base}\\n\\n${schemaInstruction}`;\n}\n","import * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport * as os from \"node:os\";\nimport type { PermissionScope } from \"./types.js\";\n\n// ─── Interface ──────────────────────────────────────────────────\n\n/** Pluggable store for persisting permission (scope) decisions across runs. */\nexport interface IPermissionStore {\n  /** Check if tool is already approved */\n  isApproved(toolName: string): Promise<boolean>;\n\n  /** Store an approval decision */\n  approve(toolName: string, scope: PermissionScope): Promise<void>;\n\n  /** Revoke approval for a tool */\n  revoke(toolName: string): Promise<void>;\n\n  /** Clear all approvals */\n  clear(): Promise<void>;\n\n  /** Dispose resources */\n  dispose(): Promise<void>;\n}\n\n// ─── InMemoryPermissionStore ────────────────────────────────────\n\n/** In-memory store — approvals live until process exits (or dispose). */\nexport class InMemoryPermissionStore implements IPermissionStore {\n  private approvals = new Map<string, PermissionScope>();\n\n  async isApproved(toolName: string): Promise<boolean> {\n    return this.approvals.has(toolName);\n  }\n\n  async approve(toolName: string, scope: PermissionScope): Promise<void> {\n    if (scope === \"once\") return; // \"once\" means don't persist\n    this.approvals.set(toolName, scope);\n  }\n\n  async revoke(toolName: string): Promise<void> {\n    this.approvals.delete(toolName);\n  }\n\n  async clear(): Promise<void> {\n    this.approvals.clear();\n  }\n\n  async dispose(): Promise<void> {\n    this.approvals.clear();\n  }\n}\n\n// ─── FilePermissionStore ────────────────────────────────────────\n\ninterface FileStoreEntry {\n  scope: PermissionScope;\n  timestamp: number;\n}\n\ninterface FileStoreData {\n  approvals: Record<string, FileStoreEntry>;\n}\n\n/** File-backed store — reads/writes a JSON file for persistent approvals. */\nexport class FilePermissionStore implements IPermissionStore {\n  private readonly filePath: string;\n\n  constructor(filePath: string) {\n    this.filePath = path.resolve(filePath);\n  }\n\n  async isApproved(toolName: string): Promise<boolean> {\n    const data = this.readFile();\n    return toolName in data.approvals;\n  }\n\n  async approve(toolName: string, scope: PermissionScope): Promise<void> {\n    if (scope === \"once\") return;\n    const data = this.readFile();\n    data.approvals[toolName] = { scope, timestamp: Date.now() };\n    this.writeFileAtomic(data);\n  }\n\n  async revoke(toolName: string): Promise<void> {\n    const data = this.readFile();\n    delete data.approvals[toolName];\n    this.writeFileAtomic(data);\n  }\n\n  async clear(): Promise<void> {\n    this.writeFileAtomic({ approvals: {} });\n  }\n\n  async dispose(): Promise<void> {\n    // No resources to release\n  }\n\n  private readFile(): FileStoreData {\n    try {\n      const raw = fs.readFileSync(this.filePath, \"utf-8\");\n      const parsed = JSON.parse(raw) as FileStoreData;\n      if (parsed && typeof parsed.approvals === \"object\") return parsed;\n    } catch {\n      // File doesn't exist or is invalid — start fresh\n    }\n    return { approvals: {} };\n  }\n\n  private writeFileAtomic(data: FileStoreData): void {\n    const dir = path.dirname(this.filePath);\n    fs.mkdirSync(dir, { recursive: true });\n    const tmpPath = this.filePath + `.tmp.${process.pid}.${Date.now()}`;\n    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), \"utf-8\");\n    fs.renameSync(tmpPath, this.filePath);\n  }\n}\n\n// ─── CompositePermissionStore ───────────────────────────────────\n\n/**\n * Composes multiple stores — checks in order, routes writes by scope.\n *\n * - \"session\" → sessionStore (in-memory)\n * - \"project\" → projectStore (file-based in project directory)\n * - \"always\"  → userStore (file-based in user home)\n */\nexport class CompositePermissionStore implements IPermissionStore {\n  private readonly sessionStore: IPermissionStore;\n  private readonly projectStore: IPermissionStore;\n  private readonly userStore: IPermissionStore;\n\n  constructor(\n    sessionStore: IPermissionStore,\n    projectStore: IPermissionStore,\n    userStore?: IPermissionStore,\n  ) {\n    this.sessionStore = sessionStore;\n    this.projectStore = projectStore;\n    this.userStore = userStore ?? projectStore;\n  }\n\n  async isApproved(toolName: string): Promise<boolean> {\n    return (\n      (await this.sessionStore.isApproved(toolName)) ||\n      (await this.projectStore.isApproved(toolName)) ||\n      (await this.userStore.isApproved(toolName))\n    );\n  }\n\n  async approve(toolName: string, scope: PermissionScope): Promise<void> {\n    if (scope === \"once\") return;\n    if (scope === \"session\") {\n      await this.sessionStore.approve(toolName, scope);\n    } else if (scope === \"project\") {\n      await this.projectStore.approve(toolName, scope);\n    } else {\n      // \"always\" → user-level store\n      await this.userStore.approve(toolName, scope);\n    }\n  }\n\n  async revoke(toolName: string): Promise<void> {\n    await this.sessionStore.revoke(toolName);\n    await this.projectStore.revoke(toolName);\n    await this.userStore.revoke(toolName);\n  }\n\n  async clear(): Promise<void> {\n    await this.sessionStore.clear();\n    await this.projectStore.clear();\n    await this.userStore.clear();\n  }\n\n  async dispose(): Promise<void> {\n    await this.sessionStore.dispose();\n    await this.projectStore.dispose();\n    if (this.userStore !== this.projectStore) {\n      await this.userStore.dispose();\n    }\n  }\n}\n\n// ─── Helpers ────────────────────────────────────────────────────\n\n/** Create a default composite store with separate project and user-level persistence. */\nexport function createDefaultPermissionStore(\n  projectDir?: string,\n): CompositePermissionStore {\n  const sessionStore = new InMemoryPermissionStore();\n  const projectPath = projectDir\n    ? path.join(projectDir, \".agent-sdk\", \"permissions.json\")\n    : path.join(process.cwd(), \".agent-sdk\", \"permissions.json\");\n  const userPath = path.join(os.homedir(), \".agent-sdk\", \"permissions.json\");\n  const projectStore = new FilePermissionStore(projectPath);\n  const userStore = new FilePermissionStore(userPath);\n  return new CompositePermissionStore(sessionStore, projectStore, userStore);\n}\n"]}