@vorim/sdk 1.0.2 → 2.0.0

package/dist/integrations/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/langchain.ts"],"sourcesContent":["// ============================================================================\n// VORIM SDK — LangChain / LangGraph JS Integration\n// Provides tool wrapping with permission checks + audit trail,\n// a callback handler for observability, and a factory for creating\n// Vorim-secured LangGraph ReAct agents.\n//\n// Peer dependencies:\n//   @langchain/core >=0.3.0\n//   @langchain/langgraph >=0.2.0\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { PermissionScope, AuditEventInput } from '../types.js';\n\n// ─── Re-declared LangChain types (peer dependency — not bundled) ──────────\n// These mirror the actual types from @langchain/core so consumers don't\n// need to import them separately for basic usage.\n\n/** Minimal subset of @langchain/core Serialized */\ninterface Serialized {\n  lc: number;\n  type: string;\n  id: string[];\n  kwargs?: Record<string, unknown>;\n}\n\n// ─── Configuration ────────────────────────────────────────────────────────\n\nexport interface VorimLangChainConfig {\n  /** Vorim SDK instance. */\n  vorim: VorimSDK;\n  /** The Vorim agent_id to associate with this LangChain agent. */\n  agentId: string;\n  /** Map tool names → Vorim permission scopes. Unmapped tools default to 'agent:execute'. */\n  permissionMap?: Record<string, PermissionScope>;\n  /** Default permission scope for tools not in permissionMap. @default 'agent:execute' */\n  defaultPermission?: PermissionScope;\n  /** Whether to emit audit events asynchronously (fire-and-forget). @default true */\n  asyncAudit?: boolean;\n}\n\n// ─── Tool Wrapper ─────────────────────────────────────────────────────────\n\n/**\n * Wraps a LangChain `StructuredTool` (or `DynamicStructuredTool`) with\n * Vorim permission checks before execution and audit event emission after.\n *\n * Works with any tool that has `name`, `description`, `schema`, and `_call`.\n *\n * @example\n * ```ts\n * import { DynamicStructuredTool } from \"@langchain/core/tools\";\n * import { wrapTool } from \"@vorim/sdk/integrations/langchain\";\n *\n * const guarded = wrapTool(myTool, {\n *   vorim, agentId: \"agid_acme_a1b2c3d4\",\n *   permissionMap: { search_docs: \"agent:read\" },\n * });\n * ```\n */\nexport function wrapTool<T extends LangChainTool>(\n  tool: T,\n  config: VorimLangChainConfig,\n): T {\n  const { vorim, agentId, permissionMap = {}, defaultPermission = 'agent:execute', asyncAudit = true } = config;\n\n  const originalCall = tool._call.bind(tool);\n\n  // Override _call to inject permission check + audit\n  (tool as any)._call = async function vorimGuardedCall(\n    arg: unknown,\n    runManager?: unknown,\n    parentConfig?: unknown,\n  ): Promise<unknown> {\n    const scope = permissionMap[tool.name] ?? defaultPermission;\n\n    // 1. Permission check\n    const { allowed, reason } = await vorim.check(agentId, scope);\n\n    if (!allowed) {\n      const event: AuditEventInput = {\n        agent_id: agentId,\n        event_type: 'tool_call',\n        action: tool.name,\n        resource: truncate(JSON.stringify(arg), 500),\n        permission: scope,\n        result: 'denied',\n        metadata: { reason, framework: 'langchain' },\n      };\n      emitAudit(vorim, event, asyncAudit);\n      throw new Error(`Vorim: permission denied for \"${tool.name}\" — scope \"${scope}\"${reason ? `: ${reason}` : ''}`);\n    }\n\n    // 2. Execute the original tool\n    const start = Date.now();\n    let result: unknown;\n    try {\n      result = await originalCall(arg, runManager, parentConfig);\n    } catch (err) {\n      const event: AuditEventInput = {\n        agent_id: agentId,\n        event_type: 'tool_call',\n        action: tool.name,\n        resource: truncate(JSON.stringify(arg), 500),\n        permission: scope,\n        result: 'error',\n        latency_ms: Date.now() - start,\n        error_code: err instanceof Error ? err.name : 'UNKNOWN',\n        metadata: { error: err instanceof Error ? err.message : String(err), framework: 'langchain' },\n      };\n      emitAudit(vorim, event, asyncAudit);\n      throw err;\n    }\n\n    // 3. Audit success\n    const event: AuditEventInput = {\n      agent_id: agentId,\n      event_type: 'tool_call',\n      action: tool.name,\n      resource: truncate(JSON.stringify(arg), 500),\n      permission: scope,\n      result: 'success',\n      latency_ms: Date.now() - start,\n      metadata: { framework: 'langchain' },\n    };\n    emitAudit(vorim, event, asyncAudit);\n\n    return result;\n  };\n\n  return tool;\n}\n\n/**\n * Wraps an array of LangChain tools with Vorim permission + audit.\n */\nexport function wrapTools<T extends LangChainTool>(\n  tools: T[],\n  config: VorimLangChainConfig,\n): T[] {\n  return tools.map(t => wrapTool(t, config));\n}\n\n// ─── Callback Handler ─────────────────────────────────────────────────────\n\n/**\n * LangChain callback handler that emits Vorim audit events for every\n * tool invocation. This is a **non-intrusive** observability layer —\n * it does not block or modify tool execution.\n *\n * Attach it to any LangChain invoke/stream call:\n * ```ts\n * const handler = new VorimCallbackHandler(vorim, \"agid_acme_a1b2c3d4\");\n * await agent.invoke({ messages }, { callbacks: [handler] });\n * ```\n */\nexport class VorimCallbackHandler {\n  name = 'VorimCallbackHandler';\n  private vorim: VorimSDK;\n  private agentId: string;\n  private runMap = new Map<string, { tool: string; input: string; startTime: number }>();\n\n  // Flags to satisfy BaseCallbackHandler interface\n  ignoreLLM = true;\n  ignoreChain = true;\n  ignoreAgent = true;\n  ignoreRetriever = true;\n  ignoreCustomEvent = true;\n  lc_serializable = false;\n\n  get lc_id(): string[] { return ['vorim', 'callbacks', 'VorimCallbackHandler']; }\n  get lc_namespace(): string[] { return ['vorim', 'callbacks']; }\n\n  constructor(vorim: VorimSDK, agentId: string) {\n    this.vorim = vorim;\n    this.agentId = agentId;\n  }\n\n  async handleToolStart(\n    tool: Serialized,\n    input: string,\n    runId: string,\n    _parentRunId?: string,\n    _tags?: string[],\n    _metadata?: Record<string, unknown>,\n    runName?: string,\n  ): Promise<void> {\n    const toolName = runName ?? tool.id?.[tool.id.length - 1] ?? 'unknown';\n    this.runMap.set(runId, { tool: toolName, input, startTime: Date.now() });\n  }\n\n  async handleToolEnd(\n    _output: unknown,\n    runId: string,\n  ): Promise<void> {\n    const run = this.runMap.get(runId);\n    if (!run) return;\n    this.runMap.delete(runId);\n\n    await this.vorim.emit({\n      agent_id: this.agentId,\n      event_type: 'tool_call',\n      action: run.tool,\n      resource: truncate(run.input, 500),\n      result: 'success',\n      latency_ms: Date.now() - run.startTime,\n      metadata: { framework: 'langchain' },\n    }).catch(() => {}); // never throw from callback\n  }\n\n  async handleToolError(\n    err: Error,\n    runId: string,\n  ): Promise<void> {\n    const run = this.runMap.get(runId);\n    if (!run) return;\n    this.runMap.delete(runId);\n\n    await this.vorim.emit({\n      agent_id: this.agentId,\n      event_type: 'tool_call',\n      action: run.tool,\n      resource: truncate(run.input, 500),\n      result: 'error',\n      latency_ms: Date.now() - run.startTime,\n      error_code: err.name,\n      metadata: { error: err.message, framework: 'langchain' },\n    }).catch(() => {});\n  }\n\n  // Required by BaseCallbackHandler — no-op for events we don't need\n  copy(): VorimCallbackHandler {\n    return new VorimCallbackHandler(this.vorim, this.agentId);\n  }\n\n  toJSON() {\n    return { lc: 1, type: 'not_implemented', id: this.lc_id };\n  }\n\n  toJSONNotImplemented() {\n    return this.toJSON();\n  }\n}\n\n// ─── Agent Factory ────────────────────────────────────────────────────────\n\nexport interface CreateVorimAgentConfig extends VorimLangChainConfig {\n  /** Display name for the agent when registering with Vorim. */\n  name: string;\n  /** Agent capabilities (e.g. [\"web_search\", \"code_execution\"]). */\n  capabilities: string[];\n  /** Initial permission scopes to grant. */\n  scopes: PermissionScope[];\n  /** Optional description. */\n  description?: string;\n}\n\n/**\n * Registers a new agent with Vorim and returns wrapped tools + callback handler\n * ready to use with `createReactAgent` or any LangChain agent.\n *\n * @example\n * ```ts\n * import { createReactAgent } from \"@langchain/langgraph/prebuilt\";\n * import { ChatOpenAI } from \"@langchain/openai\";\n * import { createVorimAgent } from \"@vorim/sdk/integrations/langchain\";\n *\n * const { agentId, tools, callbackHandler } = await createVorimAgent({\n *   vorim,\n *   name: \"research-agent\",\n *   capabilities: [\"web_search\"],\n *   scopes: [\"agent:read\", \"agent:execute\"],\n *   tools: [searchTool, analysisTool],\n * });\n *\n * const agent = createReactAgent({\n *   llm: new ChatOpenAI({ model: \"gpt-4o\" }),\n *   tools,\n * });\n *\n * const result = await agent.invoke(\n *   { messages: [{ role: \"user\", content: \"Research AI trends\" }] },\n *   { callbacks: [callbackHandler] },\n * );\n * ```\n */\nexport async function createVorimAgent<T extends LangChainTool>(config: CreateVorimAgentConfig & { tools: T[] }) {\n  const { vorim, name, capabilities, scopes, description, tools: rawTools, permissionMap, defaultPermission, asyncAudit } = config;\n\n  // Register agent with Vorim\n  const registration = await vorim.register({\n    name,\n    description,\n    capabilities,\n    scopes,\n  });\n\n  const agentId = registration.agent.agent_id;\n  const agentConfig: VorimLangChainConfig = { vorim, agentId, permissionMap, defaultPermission, asyncAudit };\n\n  // Wrap tools with permission checks\n  const tools = wrapTools(rawTools, agentConfig);\n\n  // Create callback handler for audit trail\n  const callbackHandler = new VorimCallbackHandler(vorim, agentId);\n\n  return {\n    /** The Vorim agent_id. */\n    agentId,\n    /** The full agent registration result. */\n    registration,\n    /** Tools wrapped with Vorim permission checks + audit. */\n    tools,\n    /** Callback handler for audit trail observability. */\n    callbackHandler,\n    /** The private key (store securely — shown once). */\n    privateKey: registration.private_key,\n  };\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────\n\n/** Minimal interface matching any LangChain StructuredTool / DynamicStructuredTool. */\ninterface LangChainTool {\n  name: string;\n  description: string;\n  schema: unknown;\n  _call(arg: any, runManager?: any, parentConfig?: any): Promise<any>;\n}\n\nfunction truncate(str: string, max: number): string {\n  return str.length > max ? str.slice(0, max) + '…' : str;\n}\n\nfunction emitAudit(vorim: VorimSDK, event: AuditEventInput, async: boolean): void {\n  if (async) {\n    vorim.emit(event).catch(() => {});\n  } else {\n    vorim.emit(event).catch(() => {});\n  }\n}\n"],"mappings":";AA4DO,SAAS,SACd,MACA,QACG;AACH,QAAM,EAAE,OAAO,SAAS,gBAAgB,CAAC,GAAG,oBAAoB,iBAAiB,aAAa,KAAK,IAAI;AAEvG,QAAM,eAAe,KAAK,MAAM,KAAK,IAAI;AAGzC,EAAC,KAAa,QAAQ,eAAe,iBACnC,KACA,YACA,cACkB;AAClB,UAAM,QAAQ,cAAc,KAAK,IAAI,KAAK;AAG1C,UAAM,EAAE,SAAS,OAAO,IAAI,MAAM,MAAM,MAAM,SAAS,KAAK;AAE5D,QAAI,CAAC,SAAS;AACZ,YAAMA,SAAyB;AAAA,QAC7B,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,QAAQ,KAAK;AAAA,QACb,UAAU,SAAS,KAAK,UAAU,GAAG,GAAG,GAAG;AAAA,QAC3C,YAAY;AAAA,QACZ,QAAQ;AAAA,QACR,UAAU,EAAE,QAAQ,WAAW,YAAY;AAAA,MAC7C;AACA,gBAAU,OAAOA,QAAO,UAAU;AAClC,YAAM,IAAI,MAAM,iCAAiC,KAAK,IAAI,mBAAc,KAAK,IAAI,SAAS,KAAK,MAAM,KAAK,EAAE,EAAE;AAAA,IAChH;AAGA,UAAM,QAAQ,KAAK,IAAI;AACvB,QAAI;AACJ,QAAI;AACF,eAAS,MAAM,aAAa,KAAK,YAAY,YAAY;AAAA,IAC3D,SAAS,KAAK;AACZ,YAAMA,SAAyB;AAAA,QAC7B,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,QAAQ,KAAK;AAAA,QACb,UAAU,SAAS,KAAK,UAAU,GAAG,GAAG,GAAG;AAAA,QAC3C,YAAY;AAAA,QACZ,QAAQ;AAAA,QACR,YAAY,KAAK,IAAI,IAAI;AAAA,QACzB,YAAY,eAAe,QAAQ,IAAI,OAAO;AAAA,QAC9C,UAAU,EAAE,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,GAAG,WAAW,YAAY;AAAA,MAC9F;AACA,gBAAU,OAAOA,QAAO,UAAU;AAClC,YAAM;AAAA,IACR;AAGA,UAAM,QAAyB;AAAA,MAC7B,UAAU;AAAA,MACV,YAAY;AAAA,MACZ,QAAQ,KAAK;AAAA,MACb,UAAU,SAAS,KAAK,UAAU,GAAG,GAAG,GAAG;AAAA,MAC3C,YAAY;AAAA,MACZ,QAAQ;AAAA,MACR,YAAY,KAAK,IAAI,IAAI;AAAA,MACzB,UAAU,EAAE,WAAW,YAAY;AAAA,IACrC;AACA,cAAU,OAAO,OAAO,UAAU;AAElC,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAKO,SAAS,UACd,OACA,QACK;AACL,SAAO,MAAM,IAAI,OAAK,SAAS,GAAG,MAAM,CAAC;AAC3C;AAeO,IAAM,uBAAN,MAAM,sBAAqB;AAAA,EAChC,OAAO;AAAA,EACC;AAAA,EACA;AAAA,EACA,SAAS,oBAAI,IAAgE;AAAA;AAAA,EAGrF,YAAY;AAAA,EACZ,cAAc;AAAA,EACd,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,kBAAkB;AAAA,EAElB,IAAI,QAAkB;AAAE,WAAO,CAAC,SAAS,aAAa,sBAAsB;AAAA,EAAG;AAAA,EAC/E,IAAI,eAAyB;AAAE,WAAO,CAAC,SAAS,WAAW;AAAA,EAAG;AAAA,EAE9D,YAAY,OAAiB,SAAiB;AAC5C,SAAK,QAAQ;AACb,SAAK,UAAU;AAAA,EACjB;AAAA,EAEA,MAAM,gBACJ,MACA,OACA,OACA,cACA,OACA,WACA,SACe;AACf,UAAM,WAAW,WAAW,KAAK,KAAK,KAAK,GAAG,SAAS,CAAC,KAAK;AAC7D,SAAK,OAAO,IAAI,OAAO,EAAE,MAAM,UAAU,OAAO,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,EACzE;AAAA,EAEA,MAAM,cACJ,SACA,OACe;AACf,UAAM,MAAM,KAAK,OAAO,IAAI,KAAK;AACjC,QAAI,CAAC,IAAK;AACV,SAAK,OAAO,OAAO,KAAK;AAExB,UAAM,KAAK,MAAM,KAAK;AAAA,MACpB,UAAU,KAAK;AAAA,MACf,YAAY;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,UAAU,SAAS,IAAI,OAAO,GAAG;AAAA,MACjC,QAAQ;AAAA,MACR,YAAY,KAAK,IAAI,IAAI,IAAI;AAAA,MAC7B,UAAU,EAAE,WAAW,YAAY;AAAA,IACrC,CAAC,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACnB;AAAA,EAEA,MAAM,gBACJ,KACA,OACe;AACf,UAAM,MAAM,KAAK,OAAO,IAAI,KAAK;AACjC,QAAI,CAAC,IAAK;AACV,SAAK,OAAO,OAAO,KAAK;AAExB,UAAM,KAAK,MAAM,KAAK;AAAA,MACpB,UAAU,KAAK;AAAA,MACf,YAAY;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,UAAU,SAAS,IAAI,OAAO,GAAG;AAAA,MACjC,QAAQ;AAAA,MACR,YAAY,KAAK,IAAI,IAAI,IAAI;AAAA,MAC7B,YAAY,IAAI;AAAA,MAChB,UAAU,EAAE,OAAO,IAAI,SAAS,WAAW,YAAY;AAAA,IACzD,CAAC,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACnB;AAAA;AAAA,EAGA,OAA6B;AAC3B,WAAO,IAAI,sBAAqB,KAAK,OAAO,KAAK,OAAO;AAAA,EAC1D;AAAA,EAEA,SAAS;AACP,WAAO,EAAE,IAAI,GAAG,MAAM,mBAAmB,IAAI,KAAK,MAAM;AAAA,EAC1D;AAAA,EAEA,uBAAuB;AACrB,WAAO,KAAK,OAAO;AAAA,EACrB;AACF;AA4CA,eAAsB,iBAA0C,QAAiD;AAC/G,QAAM,EAAE,OAAO,MAAM,cAAc,QAAQ,aAAa,OAAO,UAAU,eAAe,mBAAmB,WAAW,IAAI;AAG1H,QAAM,eAAe,MAAM,MAAM,SAAS;AAAA,IACxC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,UAAU,aAAa,MAAM;AACnC,QAAM,cAAoC,EAAE,OAAO,SAAS,eAAe,mBAAmB,WAAW;AAGzG,QAAM,QAAQ,UAAU,UAAU,WAAW;AAG7C,QAAM,kBAAkB,IAAI,qBAAqB,OAAO,OAAO;AAE/D,SAAO;AAAA;AAAA,IAEL;AAAA;AAAA,IAEA;AAAA;AAAA,IAEA;AAAA;AAAA,IAEA;AAAA;AAAA,IAEA,YAAY,aAAa;AAAA,EAC3B;AACF;AAYA,SAAS,SAAS,KAAa,KAAqB;AAClD,SAAO,IAAI,SAAS,MAAM,IAAI,MAAM,GAAG,GAAG,IAAI,WAAM;AACtD;AAEA,SAAS,UAAU,OAAiB,OAAwB,OAAsB;AAChF,MAAI,OAAO;AACT,UAAM,KAAK,KAAK,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EAClC,OAAO;AACL,UAAM,KAAK,KAAK,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EAClC;AACF;","names":["event"]}

package/dist/integrations/llamaindex.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrations/llamaindex.ts
+var llamaindex_exports = {};
+__export(llamaindex_exports, {
+  createVorimAgent: () => createVorimAgent,
+  emitLlamaIndexEvent: () => emitLlamaIndexEvent,
+  wrapTool: () => wrapTool,
+  wrapTools: () => wrapTools
+});
+module.exports = __toCommonJS(llamaindex_exports);
+function wrapTool(tool, config) {
+  const {
+    vorim,
+    agentId,
+    permissionMap = {},
+    defaultPermission = "agent:execute",
+    asyncAudit = true
+  } = config;
+  const originalCall = tool.call.bind(tool);
+  const toolName = tool.metadata.name;
+  const scope = permissionMap[toolName] ?? defaultPermission;
+  const wrapped = Object.create(Object.getPrototypeOf(tool), {
+    ...Object.getOwnPropertyDescriptors(tool),
+    call: {
+      value: async function vorimGuardedCall(input) {
+        const { allowed, reason } = await vorim.check(agentId, scope);
+        if (!allowed) {
+          const event2 = {
+            agent_id: agentId,
+            event_type: "tool_call",
+            action: toolName,
+            resource: truncate(JSON.stringify(input), 500),
+            permission: scope,
+            result: "denied",
+            metadata: { reason, framework: "llamaindex" }
+          };
+          emitAudit(vorim, event2, asyncAudit);
+          throw new Error(
+            `Vorim: permission denied for "${toolName}" \u2014 scope "${scope}"${reason ? `: ${reason}` : ""}`
+          );
+        }
+        const start = Date.now();
+        let result;
+        try {
+          result = await originalCall(input);
+        } catch (err) {
+          const event2 = {
+            agent_id: agentId,
+            event_type: "tool_call",
+            action: toolName,
+            resource: truncate(JSON.stringify(input), 500),
+            permission: scope,
+            result: "error",
+            latency_ms: Date.now() - start,
+            error_code: err instanceof Error ? err.name : "UNKNOWN",
+            metadata: {
+              error: err instanceof Error ? err.message : String(err),
+              framework: "llamaindex"
+            }
+          };
+          emitAudit(vorim, event2, asyncAudit);
+          throw err;
+        }
+        const event = {
+          agent_id: agentId,
+          event_type: "tool_call",
+          action: toolName,
+          resource: truncate(JSON.stringify(input), 500),
+          permission: scope,
+          result: "success",
+          latency_ms: Date.now() - start,
+          metadata: { framework: "llamaindex" }
+        };
+        emitAudit(vorim, event, asyncAudit);
+        return result;
+      },
+      writable: true,
+      configurable: true,
+      enumerable: true
+    }
+  });
+  return wrapped;
+}
+function wrapTools(tools, config) {
+  return tools.map((t) => wrapTool(t, config));
+}
+async function createVorimAgent(config) {
+  const { vorim, name, capabilities, scopes, description, tools: rawTools, permissionMap, defaultPermission, asyncAudit } = config;
+  const registration = await vorim.register({
+    name,
+    description,
+    capabilities,
+    scopes
+  });
+  const agentId = registration.agent.agent_id;
+  const toolConfig = { vorim, agentId, permissionMap, defaultPermission, asyncAudit };
+  const tools = wrapTools(rawTools, toolConfig);
+  return {
+    /** The Vorim agent_id. */
+    agentId,
+    /** Full registration result. */
+    registration,
+    /** Tools wrapped with Vorim permission checks + audit. */
+    tools,
+    /** The private key (store securely — shown once). */
+    privateKey: registration.private_key
+  };
+}
+async function emitLlamaIndexEvent(vorim, agentId, event) {
+  await vorim.emit({
+    agent_id: agentId,
+    event_type: "api_request",
+    action: event.action,
+    resource: event.resource,
+    result: event.result,
+    latency_ms: event.latencyMs,
+    error_code: event.error ? "LLAMAINDEX_ERROR" : void 0,
+    metadata: {
+      framework: "llamaindex",
+      ...event.error ? { error: event.error } : {},
+      ...event.metadata
+    }
+  });
+}
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max) + "\u2026" : str;
+}
+function emitAudit(vorim, event, async) {
+  if (async) {
+    vorim.emit(event).catch(() => {
+    });
+  } else {
+    vorim.emit(event).catch(() => {
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createVorimAgent,
+  emitLlamaIndexEvent,
+  wrapTool,
+  wrapTools
+});
+//# sourceMappingURL=llamaindex.cjs.map

package/dist/integrations/llamaindex.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/llamaindex.ts"],"sourcesContent":["// ============================================================================\n// VORIM SDK — LlamaIndex TS Integration\n// Wraps LlamaIndex tools with Vorim permission checks + audit trails.\n// Provides a tool wrapper and agent registration factory.\n//\n// Peer dependency: llamaindex >=0.4.0 (or @llamaindex/core)\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { PermissionScope, AuditEventInput } from '../types.js';\n\n// ─── Re-declared LlamaIndex types (peer dependency — not bundled) ─────────\n// These mirror the actual interfaces from @llamaindex/core/llms and\n// @llamaindex/core/tools so consumers don't need to wrangle imports.\n\n/** Matches @llamaindex/core ToolMetadata */\ninterface ToolMetadata<P extends Record<string, unknown> = Record<string, unknown>> {\n  name: string;\n  description: string;\n  parameters?: P;\n}\n\n/**\n * Matches @llamaindex/core BaseTool.\n * In LlamaIndex, `call` is optional on BaseTool but required on BaseToolWithCall.\n */\ninterface LlamaIndexTool<Input = any> {\n  metadata: ToolMetadata;\n  call: (input: Input) => any | Promise<any>;\n}\n\n// ─── Configuration ────────────────────────────────────────────────────────\n\nexport interface VorimLlamaIndexConfig {\n  /** Vorim SDK instance. */\n  vorim: VorimSDK;\n  /** The Vorim agent_id to associate. */\n  agentId: string;\n  /** Map tool names → Vorim permission scopes. */\n  permissionMap?: Record<string, PermissionScope>;\n  /** Default permission scope for unmapped tools. @default 'agent:execute' */\n  defaultPermission?: PermissionScope;\n  /** Whether to emit audit events asynchronously (fire-and-forget). @default true */\n  asyncAudit?: boolean;\n}\n\n// ─── Tool Wrapper ─────────────────────────────────────────────────────────\n\n/**\n * Wraps a LlamaIndex tool (`BaseTool` / `BaseToolWithCall` / `FunctionTool`)\n * with Vorim permission checks before execution and audit event emission after.\n *\n * The wrapper implements the same `BaseTool` interface so it's a drop-in\n * replacement anywhere LlamaIndex expects a tool.\n *\n * @example\n * ```ts\n * import { FunctionTool } from \"llamaindex\";\n * import createVorim from \"@vorim/sdk\";\n * import { wrapTool } from \"@vorim/sdk/integrations/llamaindex\";\n *\n * const vorim = createVorim({ apiKey: \"agid_sk_live_...\" });\n *\n * const searchTool = FunctionTool.from(\n *   async ({ query }: { query: string }) => `Results for: ${query}`,\n *   { name: \"search\", description: \"Search documents\", parameters: { ... } }\n * );\n *\n * const guarded = wrapTool(searchTool, {\n *   vorim,\n *   agentId: \"agid_acme_a1b2c3d4\",\n *   permissionMap: { search: \"agent:read\" },\n * });\n *\n * // Use with any LlamaIndex agent\n * const agent = new OpenAIAgent({ tools: [guarded] });\n * ```\n */\nexport function wrapTool<T extends LlamaIndexTool>(\n  tool: T,\n  config: VorimLlamaIndexConfig,\n): T {\n  const {\n    vorim, agentId,\n    permissionMap = {},\n    defaultPermission = 'agent:execute',\n    asyncAudit = true,\n  } = config;\n\n  const originalCall = tool.call.bind(tool);\n  const toolName = tool.metadata.name;\n  const scope = permissionMap[toolName] ?? defaultPermission;\n\n  // Create a new object that preserves the tool's prototype chain\n  // and all properties, but overrides `call`\n  const wrapped = Object.create(Object.getPrototypeOf(tool), {\n    ...Object.getOwnPropertyDescriptors(tool),\n    call: {\n      value: async function vorimGuardedCall(input: any): Promise<any> {\n        // 1. Permission check\n        const { allowed, reason } = await vorim.check(agentId, scope);\n\n        if (!allowed) {\n          const event: AuditEventInput = {\n            agent_id: agentId,\n            event_type: 'tool_call',\n            action: toolName,\n            resource: truncate(JSON.stringify(input), 500),\n            permission: scope,\n            result: 'denied',\n            metadata: { reason, framework: 'llamaindex' },\n          };\n          emitAudit(vorim, event, asyncAudit);\n          throw new Error(\n            `Vorim: permission denied for \"${toolName}\" — scope \"${scope}\"${reason ? `: ${reason}` : ''}`,\n          );\n        }\n\n        // 2. Execute the original tool\n        const start = Date.now();\n        let result: any;\n        try {\n          result = await originalCall(input);\n        } catch (err) {\n          const event: AuditEventInput = {\n            agent_id: agentId,\n            event_type: 'tool_call',\n            action: toolName,\n            resource: truncate(JSON.stringify(input), 500),\n            permission: scope,\n            result: 'error',\n            latency_ms: Date.now() - start,\n            error_code: err instanceof Error ? err.name : 'UNKNOWN',\n            metadata: {\n              error: err instanceof Error ? err.message : String(err),\n              framework: 'llamaindex',\n            },\n          };\n          emitAudit(vorim, event, asyncAudit);\n          throw err;\n        }\n\n        // 3. Audit success\n        const event: AuditEventInput = {\n          agent_id: agentId,\n          event_type: 'tool_call',\n          action: toolName,\n          resource: truncate(JSON.stringify(input), 500),\n          permission: scope,\n          result: 'success',\n          latency_ms: Date.now() - start,\n          metadata: { framework: 'llamaindex' },\n        };\n        emitAudit(vorim, event, asyncAudit);\n\n        return result;\n      },\n      writable: true,\n      configurable: true,\n      enumerable: true,\n    },\n  }) as T;\n\n  return wrapped;\n}\n\n/**\n * Wraps an array of LlamaIndex tools with Vorim permission + audit.\n */\nexport function wrapTools<T extends LlamaIndexTool>(\n  tools: T[],\n  config: VorimLlamaIndexConfig,\n): T[] {\n  return tools.map(t => wrapTool(t, config));\n}\n\n// ─── Agent Factory ────────────────────────────────────────────────────────\n\nexport interface CreateVorimLlamaIndexAgentConfig extends VorimLlamaIndexConfig {\n  /** Display name for the agent. */\n  name: string;\n  /** Agent capabilities. */\n  capabilities: string[];\n  /** Initial permission scopes. */\n  scopes: PermissionScope[];\n  /** Optional description. */\n  description?: string;\n}\n\n/**\n * Registers a new agent with Vorim and returns wrapped tools ready for\n * use with any LlamaIndex agent (OpenAIAgent, ReActAgent, etc.).\n *\n * @example\n * ```ts\n * import { OpenAIAgent, FunctionTool } from \"llamaindex\";\n * import createVorim from \"@vorim/sdk\";\n * import { createVorimAgent } from \"@vorim/sdk/integrations/llamaindex\";\n *\n * const vorim = createVorim({ apiKey: \"agid_sk_live_...\" });\n *\n * const searchTool = FunctionTool.from(...);\n * const writeTool = FunctionTool.from(...);\n *\n * const { agentId, tools } = await createVorimAgent({\n *   vorim,\n *   name: \"research-agent\",\n *   capabilities: [\"search\", \"write\"],\n *   scopes: [\"agent:read\", \"agent:write\", \"agent:execute\"],\n *   tools: [searchTool, writeTool],\n *   permissionMap: {\n *     search: \"agent:read\",\n *     write: \"agent:write\",\n *   },\n * });\n *\n * // Create LlamaIndex agent with Vorim-wrapped tools\n * const agent = new OpenAIAgent({ tools });\n * const response = await agent.chat({ message: \"Research AI trends\" });\n * ```\n */\nexport async function createVorimAgent<T extends LlamaIndexTool>(\n  config: CreateVorimLlamaIndexAgentConfig & { tools: T[] },\n) {\n  const { vorim, name, capabilities, scopes, description, tools: rawTools, permissionMap, defaultPermission, asyncAudit } = config;\n\n  // Register agent with Vorim\n  const registration = await vorim.register({\n    name,\n    description,\n    capabilities,\n    scopes,\n  });\n\n  const agentId = registration.agent.agent_id;\n  const toolConfig: VorimLlamaIndexConfig = { vorim, agentId, permissionMap, defaultPermission, asyncAudit };\n\n  // Wrap tools with permission checks\n  const tools = wrapTools(rawTools, toolConfig);\n\n  return {\n    /** The Vorim agent_id. */\n    agentId,\n    /** Full registration result. */\n    registration,\n    /** Tools wrapped with Vorim permission checks + audit. */\n    tools,\n    /** The private key (store securely — shown once). */\n    privateKey: registration.private_key,\n  };\n}\n\n// ─── Audit Helpers ────────────────────────────────────────────────────────\n\n/**\n * Emit a manual audit event for a LlamaIndex agent action that isn't\n * captured by the tool wrapper (e.g. RAG retrieval, chat responses).\n */\nexport async function emitLlamaIndexEvent(\n  vorim: VorimSDK,\n  agentId: string,\n  event: {\n    action: string;\n    resource?: string;\n    result: 'success' | 'denied' | 'error';\n    latencyMs?: number;\n    error?: string;\n    metadata?: Record<string, unknown>;\n  },\n): Promise<void> {\n  await vorim.emit({\n    agent_id: agentId,\n    event_type: 'api_request',\n    action: event.action,\n    resource: event.resource,\n    result: event.result,\n    latency_ms: event.latencyMs,\n    error_code: event.error ? 'LLAMAINDEX_ERROR' : undefined,\n    metadata: {\n      framework: 'llamaindex',\n      ...(event.error ? { error: event.error } : {}),\n      ...event.metadata,\n    },\n  });\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────\n\nfunction truncate(str: string, max: number): string {\n  return str.length > max ? str.slice(0, max) + '…' : str;\n}\n\nfunction emitAudit(vorim: VorimSDK, event: AuditEventInput, async: boolean): void {\n  if (async) {\n    vorim.emit(event).catch(() => {});\n  } else {\n    vorim.emit(event).catch(() => {});\n  }\n}\n"],"mappings":"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","names":["event"]}

package/dist/integrations/llamaindex.d.cts

@@ -0,0 +1,131 @@
+import { VorimSDK, PermissionScope, AgentRegistrationResult } from '../index.cjs';
+
+/** Matches @llamaindex/core ToolMetadata */
+interface ToolMetadata<P extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    parameters?: P;
+}
+/**
+ * Matches @llamaindex/core BaseTool.
+ * In LlamaIndex, `call` is optional on BaseTool but required on BaseToolWithCall.
+ */
+interface LlamaIndexTool<Input = any> {
+    metadata: ToolMetadata;
+    call: (input: Input) => any | Promise<any>;
+}
+interface VorimLlamaIndexConfig {
+    /** Vorim SDK instance. */
+    vorim: VorimSDK;
+    /** The Vorim agent_id to associate. */
+    agentId: string;
+    /** Map tool names → Vorim permission scopes. */
+    permissionMap?: Record<string, PermissionScope>;
+    /** Default permission scope for unmapped tools. @default 'agent:execute' */
+    defaultPermission?: PermissionScope;
+    /** Whether to emit audit events asynchronously (fire-and-forget). @default true */
+    asyncAudit?: boolean;
+}
+/**
+ * Wraps a LlamaIndex tool (`BaseTool` / `BaseToolWithCall` / `FunctionTool`)
+ * with Vorim permission checks before execution and audit event emission after.
+ *
+ * The wrapper implements the same `BaseTool` interface so it's a drop-in
+ * replacement anywhere LlamaIndex expects a tool.
+ *
+ * @example
+ * ```ts
+ * import { FunctionTool } from "llamaindex";
+ * import createVorim from "@vorim/sdk";
+ * import { wrapTool } from "@vorim/sdk/integrations/llamaindex";
+ *
+ * const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+ *
+ * const searchTool = FunctionTool.from(
+ *   async ({ query }: { query: string }) => `Results for: ${query}`,
+ *   { name: "search", description: "Search documents", parameters: { ... } }
+ * );
+ *
+ * const guarded = wrapTool(searchTool, {
+ *   vorim,
+ *   agentId: "agid_acme_a1b2c3d4",
+ *   permissionMap: { search: "agent:read" },
+ * });
+ *
+ * // Use with any LlamaIndex agent
+ * const agent = new OpenAIAgent({ tools: [guarded] });
+ * ```
+ */
+declare function wrapTool<T extends LlamaIndexTool>(tool: T, config: VorimLlamaIndexConfig): T;
+/**
+ * Wraps an array of LlamaIndex tools with Vorim permission + audit.
+ */
+declare function wrapTools<T extends LlamaIndexTool>(tools: T[], config: VorimLlamaIndexConfig): T[];
+interface CreateVorimLlamaIndexAgentConfig extends VorimLlamaIndexConfig {
+    /** Display name for the agent. */
+    name: string;
+    /** Agent capabilities. */
+    capabilities: string[];
+    /** Initial permission scopes. */
+    scopes: PermissionScope[];
+    /** Optional description. */
+    description?: string;
+}
+/**
+ * Registers a new agent with Vorim and returns wrapped tools ready for
+ * use with any LlamaIndex agent (OpenAIAgent, ReActAgent, etc.).
+ *
+ * @example
+ * ```ts
+ * import { OpenAIAgent, FunctionTool } from "llamaindex";
+ * import createVorim from "@vorim/sdk";
+ * import { createVorimAgent } from "@vorim/sdk/integrations/llamaindex";
+ *
+ * const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+ *
+ * const searchTool = FunctionTool.from(...);
+ * const writeTool = FunctionTool.from(...);
+ *
+ * const { agentId, tools } = await createVorimAgent({
+ *   vorim,
+ *   name: "research-agent",
+ *   capabilities: ["search", "write"],
+ *   scopes: ["agent:read", "agent:write", "agent:execute"],
+ *   tools: [searchTool, writeTool],
+ *   permissionMap: {
+ *     search: "agent:read",
+ *     write: "agent:write",
+ *   },
+ * });
+ *
+ * // Create LlamaIndex agent with Vorim-wrapped tools
+ * const agent = new OpenAIAgent({ tools });
+ * const response = await agent.chat({ message: "Research AI trends" });
+ * ```
+ */
+declare function createVorimAgent<T extends LlamaIndexTool>(config: CreateVorimLlamaIndexAgentConfig & {
+    tools: T[];
+}): Promise<{
+    /** The Vorim agent_id. */
+    agentId: string;
+    /** Full registration result. */
+    registration: AgentRegistrationResult;
+    /** Tools wrapped with Vorim permission checks + audit. */
+    tools: T[];
+    /** The private key (store securely — shown once). */
+    privateKey: string;
+}>;
+/**
+ * Emit a manual audit event for a LlamaIndex agent action that isn't
+ * captured by the tool wrapper (e.g. RAG retrieval, chat responses).
+ */
+declare function emitLlamaIndexEvent(vorim: VorimSDK, agentId: string, event: {
+    action: string;
+    resource?: string;
+    result: 'success' | 'denied' | 'error';
+    latencyMs?: number;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<void>;
+
+export { type CreateVorimLlamaIndexAgentConfig, type VorimLlamaIndexConfig, createVorimAgent, emitLlamaIndexEvent, wrapTool, wrapTools };

package/dist/integrations/llamaindex.d.ts

@@ -0,0 +1,131 @@
+import { VorimSDK, PermissionScope, AgentRegistrationResult } from '../index.js';
+
+/** Matches @llamaindex/core ToolMetadata */
+interface ToolMetadata<P extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    parameters?: P;
+}
+/**
+ * Matches @llamaindex/core BaseTool.
+ * In LlamaIndex, `call` is optional on BaseTool but required on BaseToolWithCall.
+ */
+interface LlamaIndexTool<Input = any> {
+    metadata: ToolMetadata;
+    call: (input: Input) => any | Promise<any>;
+}
+interface VorimLlamaIndexConfig {
+    /** Vorim SDK instance. */
+    vorim: VorimSDK;
+    /** The Vorim agent_id to associate. */
+    agentId: string;
+    /** Map tool names → Vorim permission scopes. */
+    permissionMap?: Record<string, PermissionScope>;
+    /** Default permission scope for unmapped tools. @default 'agent:execute' */
+    defaultPermission?: PermissionScope;
+    /** Whether to emit audit events asynchronously (fire-and-forget). @default true */
+    asyncAudit?: boolean;
+}
+/**
+ * Wraps a LlamaIndex tool (`BaseTool` / `BaseToolWithCall` / `FunctionTool`)
+ * with Vorim permission checks before execution and audit event emission after.
+ *
+ * The wrapper implements the same `BaseTool` interface so it's a drop-in
+ * replacement anywhere LlamaIndex expects a tool.
+ *
+ * @example
+ * ```ts
+ * import { FunctionTool } from "llamaindex";
+ * import createVorim from "@vorim/sdk";
+ * import { wrapTool } from "@vorim/sdk/integrations/llamaindex";
+ *
+ * const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+ *
+ * const searchTool = FunctionTool.from(
+ *   async ({ query }: { query: string }) => `Results for: ${query}`,
+ *   { name: "search", description: "Search documents", parameters: { ... } }
+ * );
+ *
+ * const guarded = wrapTool(searchTool, {
+ *   vorim,
+ *   agentId: "agid_acme_a1b2c3d4",
+ *   permissionMap: { search: "agent:read" },
+ * });
+ *
+ * // Use with any LlamaIndex agent
+ * const agent = new OpenAIAgent({ tools: [guarded] });
+ * ```
+ */
+declare function wrapTool<T extends LlamaIndexTool>(tool: T, config: VorimLlamaIndexConfig): T;
+/**
+ * Wraps an array of LlamaIndex tools with Vorim permission + audit.
+ */
+declare function wrapTools<T extends LlamaIndexTool>(tools: T[], config: VorimLlamaIndexConfig): T[];
+interface CreateVorimLlamaIndexAgentConfig extends VorimLlamaIndexConfig {
+    /** Display name for the agent. */
+    name: string;
+    /** Agent capabilities. */
+    capabilities: string[];
+    /** Initial permission scopes. */
+    scopes: PermissionScope[];
+    /** Optional description. */
+    description?: string;
+}
+/**
+ * Registers a new agent with Vorim and returns wrapped tools ready for
+ * use with any LlamaIndex agent (OpenAIAgent, ReActAgent, etc.).
+ *
+ * @example
+ * ```ts
+ * import { OpenAIAgent, FunctionTool } from "llamaindex";
+ * import createVorim from "@vorim/sdk";
+ * import { createVorimAgent } from "@vorim/sdk/integrations/llamaindex";
+ *
+ * const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+ *
+ * const searchTool = FunctionTool.from(...);
+ * const writeTool = FunctionTool.from(...);
+ *
+ * const { agentId, tools } = await createVorimAgent({
+ *   vorim,
+ *   name: "research-agent",
+ *   capabilities: ["search", "write"],
+ *   scopes: ["agent:read", "agent:write", "agent:execute"],
+ *   tools: [searchTool, writeTool],
+ *   permissionMap: {
+ *     search: "agent:read",
+ *     write: "agent:write",
+ *   },
+ * });
+ *
+ * // Create LlamaIndex agent with Vorim-wrapped tools
+ * const agent = new OpenAIAgent({ tools });
+ * const response = await agent.chat({ message: "Research AI trends" });
+ * ```
+ */
+declare function createVorimAgent<T extends LlamaIndexTool>(config: CreateVorimLlamaIndexAgentConfig & {
+    tools: T[];
+}): Promise<{
+    /** The Vorim agent_id. */
+    agentId: string;
+    /** Full registration result. */
+    registration: AgentRegistrationResult;
+    /** Tools wrapped with Vorim permission checks + audit. */
+    tools: T[];
+    /** The private key (store securely — shown once). */
+    privateKey: string;
+}>;
+/**
+ * Emit a manual audit event for a LlamaIndex agent action that isn't
+ * captured by the tool wrapper (e.g. RAG retrieval, chat responses).
+ */
+declare function emitLlamaIndexEvent(vorim: VorimSDK, agentId: string, event: {
+    action: string;
+    resource?: string;
+    result: 'success' | 'denied' | 'error';
+    latencyMs?: number;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<void>;
+
+export { type CreateVorimLlamaIndexAgentConfig, type VorimLlamaIndexConfig, createVorimAgent, emitLlamaIndexEvent, wrapTool, wrapTools };

package/dist/integrations/llamaindex.js

@@ -0,0 +1,134 @@
+// src/integrations/llamaindex.ts
+function wrapTool(tool, config) {
+  const {
+    vorim,
+    agentId,
+    permissionMap = {},
+    defaultPermission = "agent:execute",
+    asyncAudit = true
+  } = config;
+  const originalCall = tool.call.bind(tool);
+  const toolName = tool.metadata.name;
+  const scope = permissionMap[toolName] ?? defaultPermission;
+  const wrapped = Object.create(Object.getPrototypeOf(tool), {
+    ...Object.getOwnPropertyDescriptors(tool),
+    call: {
+      value: async function vorimGuardedCall(input) {
+        const { allowed, reason } = await vorim.check(agentId, scope);
+        if (!allowed) {
+          const event2 = {
+            agent_id: agentId,
+            event_type: "tool_call",
+            action: toolName,
+            resource: truncate(JSON.stringify(input), 500),
+            permission: scope,
+            result: "denied",
+            metadata: { reason, framework: "llamaindex" }
+          };
+          emitAudit(vorim, event2, asyncAudit);
+          throw new Error(
+            `Vorim: permission denied for "${toolName}" \u2014 scope "${scope}"${reason ? `: ${reason}` : ""}`
+          );
+        }
+        const start = Date.now();
+        let result;
+        try {
+          result = await originalCall(input);
+        } catch (err) {
+          const event2 = {
+            agent_id: agentId,
+            event_type: "tool_call",
+            action: toolName,
+            resource: truncate(JSON.stringify(input), 500),
+            permission: scope,
+            result: "error",
+            latency_ms: Date.now() - start,
+            error_code: err instanceof Error ? err.name : "UNKNOWN",
+            metadata: {
+              error: err instanceof Error ? err.message : String(err),
+              framework: "llamaindex"
+            }
+          };
+          emitAudit(vorim, event2, asyncAudit);
+          throw err;
+        }
+        const event = {
+          agent_id: agentId,
+          event_type: "tool_call",
+          action: toolName,
+          resource: truncate(JSON.stringify(input), 500),
+          permission: scope,
+          result: "success",
+          latency_ms: Date.now() - start,
+          metadata: { framework: "llamaindex" }
+        };
+        emitAudit(vorim, event, asyncAudit);
+        return result;
+      },
+      writable: true,
+      configurable: true,
+      enumerable: true
+    }
+  });
+  return wrapped;
+}
+function wrapTools(tools, config) {
+  return tools.map((t) => wrapTool(t, config));
+}
+async function createVorimAgent(config) {
+  const { vorim, name, capabilities, scopes, description, tools: rawTools, permissionMap, defaultPermission, asyncAudit } = config;
+  const registration = await vorim.register({
+    name,
+    description,
+    capabilities,
+    scopes
+  });
+  const agentId = registration.agent.agent_id;
+  const toolConfig = { vorim, agentId, permissionMap, defaultPermission, asyncAudit };
+  const tools = wrapTools(rawTools, toolConfig);
+  return {
+    /** The Vorim agent_id. */
+    agentId,
+    /** Full registration result. */
+    registration,
+    /** Tools wrapped with Vorim permission checks + audit. */
+    tools,
+    /** The private key (store securely — shown once). */
+    privateKey: registration.private_key
+  };
+}
+async function emitLlamaIndexEvent(vorim, agentId, event) {
+  await vorim.emit({
+    agent_id: agentId,
+    event_type: "api_request",
+    action: event.action,
+    resource: event.resource,
+    result: event.result,
+    latency_ms: event.latencyMs,
+    error_code: event.error ? "LLAMAINDEX_ERROR" : void 0,
+    metadata: {
+      framework: "llamaindex",
+      ...event.error ? { error: event.error } : {},
+      ...event.metadata
+    }
+  });
+}
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max) + "\u2026" : str;
+}
+function emitAudit(vorim, event, async) {
+  if (async) {
+    vorim.emit(event).catch(() => {
+    });
+  } else {
+    vorim.emit(event).catch(() => {
+    });
+  }
+}
+export {
+  createVorimAgent,
+  emitLlamaIndexEvent,
+  wrapTool,
+  wrapTools
+};
+//# sourceMappingURL=llamaindex.js.map

package/dist/integrations/llamaindex.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/llamaindex.ts"],"sourcesContent":["// ============================================================================\n// VORIM SDK — LlamaIndex TS Integration\n// Wraps LlamaIndex tools with Vorim permission checks + audit trails.\n// Provides a tool wrapper and agent registration factory.\n//\n// Peer dependency: llamaindex >=0.4.0 (or @llamaindex/core)\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { PermissionScope, AuditEventInput } from '../types.js';\n\n// ─── Re-declared LlamaIndex types (peer dependency — not bundled) ─────────\n// These mirror the actual interfaces from @llamaindex/core/llms and\n// @llamaindex/core/tools so consumers don't need to wrangle imports.\n\n/** Matches @llamaindex/core ToolMetadata */\ninterface ToolMetadata<P extends Record<string, unknown> = Record<string, unknown>> {\n  name: string;\n  description: string;\n  parameters?: P;\n}\n\n/**\n * Matches @llamaindex/core BaseTool.\n * In LlamaIndex, `call` is optional on BaseTool but required on BaseToolWithCall.\n */\ninterface LlamaIndexTool<Input = any> {\n  metadata: ToolMetadata;\n  call: (input: Input) => any | Promise<any>;\n}\n\n// ─── Configuration ────────────────────────────────────────────────────────\n\nexport interface VorimLlamaIndexConfig {\n  /** Vorim SDK instance. */\n  vorim: VorimSDK;\n  /** The Vorim agent_id to associate. */\n  agentId: string;\n  /** Map tool names → Vorim permission scopes. */\n  permissionMap?: Record<string, PermissionScope>;\n  /** Default permission scope for unmapped tools. @default 'agent:execute' */\n  defaultPermission?: PermissionScope;\n  /** Whether to emit audit events asynchronously (fire-and-forget). @default true */\n  asyncAudit?: boolean;\n}\n\n// ─── Tool Wrapper ─────────────────────────────────────────────────────────\n\n/**\n * Wraps a LlamaIndex tool (`BaseTool` / `BaseToolWithCall` / `FunctionTool`)\n * with Vorim permission checks before execution and audit event emission after.\n *\n * The wrapper implements the same `BaseTool` interface so it's a drop-in\n * replacement anywhere LlamaIndex expects a tool.\n *\n * @example\n * ```ts\n * import { FunctionTool } from \"llamaindex\";\n * import createVorim from \"@vorim/sdk\";\n * import { wrapTool } from \"@vorim/sdk/integrations/llamaindex\";\n *\n * const vorim = createVorim({ apiKey: \"agid_sk_live_...\" });\n *\n * const searchTool = FunctionTool.from(\n *   async ({ query }: { query: string }) => `Results for: ${query}`,\n *   { name: \"search\", description: \"Search documents\", parameters: { ... } }\n * );\n *\n * const guarded = wrapTool(searchTool, {\n *   vorim,\n *   agentId: \"agid_acme_a1b2c3d4\",\n *   permissionMap: { search: \"agent:read\" },\n * });\n *\n * // Use with any LlamaIndex agent\n * const agent = new OpenAIAgent({ tools: [guarded] });\n * ```\n */\nexport function wrapTool<T extends LlamaIndexTool>(\n  tool: T,\n  config: VorimLlamaIndexConfig,\n): T {\n  const {\n    vorim, agentId,\n    permissionMap = {},\n    defaultPermission = 'agent:execute',\n    asyncAudit = true,\n  } = config;\n\n  const originalCall = tool.call.bind(tool);\n  const toolName = tool.metadata.name;\n  const scope = permissionMap[toolName] ?? defaultPermission;\n\n  // Create a new object that preserves the tool's prototype chain\n  // and all properties, but overrides `call`\n  const wrapped = Object.create(Object.getPrototypeOf(tool), {\n    ...Object.getOwnPropertyDescriptors(tool),\n    call: {\n      value: async function vorimGuardedCall(input: any): Promise<any> {\n        // 1. Permission check\n        const { allowed, reason } = await vorim.check(agentId, scope);\n\n        if (!allowed) {\n          const event: AuditEventInput = {\n            agent_id: agentId,\n            event_type: 'tool_call',\n            action: toolName,\n            resource: truncate(JSON.stringify(input), 500),\n            permission: scope,\n            result: 'denied',\n            metadata: { reason, framework: 'llamaindex' },\n          };\n          emitAudit(vorim, event, asyncAudit);\n          throw new Error(\n            `Vorim: permission denied for \"${toolName}\" — scope \"${scope}\"${reason ? `: ${reason}` : ''}`,\n          );\n        }\n\n        // 2. Execute the original tool\n        const start = Date.now();\n        let result: any;\n        try {\n          result = await originalCall(input);\n        } catch (err) {\n          const event: AuditEventInput = {\n            agent_id: agentId,\n            event_type: 'tool_call',\n            action: toolName,\n            resource: truncate(JSON.stringify(input), 500),\n            permission: scope,\n            result: 'error',\n            latency_ms: Date.now() - start,\n            error_code: err instanceof Error ? err.name : 'UNKNOWN',\n            metadata: {\n              error: err instanceof Error ? err.message : String(err),\n              framework: 'llamaindex',\n            },\n          };\n          emitAudit(vorim, event, asyncAudit);\n          throw err;\n        }\n\n        // 3. Audit success\n        const event: AuditEventInput = {\n          agent_id: agentId,\n          event_type: 'tool_call',\n          action: toolName,\n          resource: truncate(JSON.stringify(input), 500),\n          permission: scope,\n          result: 'success',\n          latency_ms: Date.now() - start,\n          metadata: { framework: 'llamaindex' },\n        };\n        emitAudit(vorim, event, asyncAudit);\n\n        return result;\n      },\n      writable: true,\n      configurable: true,\n      enumerable: true,\n    },\n  }) as T;\n\n  return wrapped;\n}\n\n/**\n * Wraps an array of LlamaIndex tools with Vorim permission + audit.\n */\nexport function wrapTools<T extends LlamaIndexTool>(\n  tools: T[],\n  config: VorimLlamaIndexConfig,\n): T[] {\n  return tools.map(t => wrapTool(t, config));\n}\n\n// ─── Agent Factory ────────────────────────────────────────────────────────\n\nexport interface CreateVorimLlamaIndexAgentConfig extends VorimLlamaIndexConfig {\n  /** Display name for the agent. */\n  name: string;\n  /** Agent capabilities. */\n  capabilities: string[];\n  /** Initial permission scopes. */\n  scopes: PermissionScope[];\n  /** Optional description. */\n  description?: string;\n}\n\n/**\n * Registers a new agent with Vorim and returns wrapped tools ready for\n * use with any LlamaIndex agent (OpenAIAgent, ReActAgent, etc.).\n *\n * @example\n * ```ts\n * import { OpenAIAgent, FunctionTool } from \"llamaindex\";\n * import createVorim from \"@vorim/sdk\";\n * import { createVorimAgent } from \"@vorim/sdk/integrations/llamaindex\";\n *\n * const vorim = createVorim({ apiKey: \"agid_sk_live_...\" });\n *\n * const searchTool = FunctionTool.from(...);\n * const writeTool = FunctionTool.from(...);\n *\n * const { agentId, tools } = await createVorimAgent({\n *   vorim,\n *   name: \"research-agent\",\n *   capabilities: [\"search\", \"write\"],\n *   scopes: [\"agent:read\", \"agent:write\", \"agent:execute\"],\n *   tools: [searchTool, writeTool],\n *   permissionMap: {\n *     search: \"agent:read\",\n *     write: \"agent:write\",\n *   },\n * });\n *\n * // Create LlamaIndex agent with Vorim-wrapped tools\n * const agent = new OpenAIAgent({ tools });\n * const response = await agent.chat({ message: \"Research AI trends\" });\n * ```\n */\nexport async function createVorimAgent<T extends LlamaIndexTool>(\n  config: CreateVorimLlamaIndexAgentConfig & { tools: T[] },\n) {\n  const { vorim, name, capabilities, scopes, description, tools: rawTools, permissionMap, defaultPermission, asyncAudit } = config;\n\n  // Register agent with Vorim\n  const registration = await vorim.register({\n    name,\n    description,\n    capabilities,\n    scopes,\n  });\n\n  const agentId = registration.agent.agent_id;\n  const toolConfig: VorimLlamaIndexConfig = { vorim, agentId, permissionMap, defaultPermission, asyncAudit };\n\n  // Wrap tools with permission checks\n  const tools = wrapTools(rawTools, toolConfig);\n\n  return {\n    /** The Vorim agent_id. */\n    agentId,\n    /** Full registration result. */\n    registration,\n    /** Tools wrapped with Vorim permission checks + audit. */\n    tools,\n    /** The private key (store securely — shown once). */\n    privateKey: registration.private_key,\n  };\n}\n\n// ─── Audit Helpers ────────────────────────────────────────────────────────\n\n/**\n * Emit a manual audit event for a LlamaIndex agent action that isn't\n * captured by the tool wrapper (e.g. RAG retrieval, chat responses).\n */\nexport async function emitLlamaIndexEvent(\n  vorim: VorimSDK,\n  agentId: string,\n  event: {\n    action: string;\n    resource?: string;\n    result: 'success' | 'denied' | 'error';\n    latencyMs?: number;\n    error?: string;\n    metadata?: Record<string, unknown>;\n  },\n): Promise<void> {\n  await vorim.emit({\n    agent_id: agentId,\n    event_type: 'api_request',\n    action: event.action,\n    resource: event.resource,\n    result: event.result,\n    latency_ms: event.latencyMs,\n    error_code: event.error ? 'LLAMAINDEX_ERROR' : undefined,\n    metadata: {\n      framework: 'llamaindex',\n      ...(event.error ? { error: event.error } : {}),\n      ...event.metadata,\n    },\n  });\n}\n\n// ─── Internal helpers ─────────────────────────────────────────────────────\n\nfunction truncate(str: string, max: number): string {\n  return str.length > max ? str.slice(0, max) + '…' : str;\n}\n\nfunction emitAudit(vorim: VorimSDK, event: AuditEventInput, async: boolean): void {\n  if (async) {\n    vorim.emit(event).catch(() => {});\n  } else {\n    vorim.emit(event).catch(() => {});\n  }\n}\n"],"mappings":"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","names":["event"]}