@vorim/sdk 1.0.1 → 2.0.0

package/dist/integrations/openai.cjs

@@ -0,0 +1,208 @@
+"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/openai.ts
+var openai_exports = {};
+__export(openai_exports, {
+  VorimToolRegistry: () => VorimToolRegistry,
+  createVorimOpenAIAgent: () => createVorimOpenAIAgent,
+  runAgentLoop: () => runAgentLoop
+});
+module.exports = __toCommonJS(openai_exports);
+var VorimToolRegistry = class {
+  vorim;
+  agentId;
+  defaultPermission;
+  asyncAudit;
+  tools = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.vorim = config.vorim;
+    this.agentId = config.agentId;
+    this.defaultPermission = config.defaultPermission ?? "agent:execute";
+    this.asyncAudit = config.asyncAudit ?? true;
+  }
+  /** Register a tool. */
+  add(definition) {
+    this.tools.set(definition.name, definition);
+    return this;
+  }
+  /** Register multiple tools. */
+  addAll(definitions) {
+    for (const def of definitions) this.add(def);
+    return this;
+  }
+  /** Convert registered tools to OpenAI's ChatCompletionTool format. */
+  toOpenAITools() {
+    return [...this.tools.values()].map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+        ...t.strict != null ? { strict: t.strict } : {}
+      }
+    }));
+  }
+  /**
+   * Execute tool calls from an OpenAI chat completion response.
+   * Each call is checked against Vorim permissions and audited.
+   * Returns an array of tool messages ready to append to the conversation.
+   */
+  async executeToolCalls(toolCalls) {
+    const results = await Promise.all(
+      toolCalls.map((tc) => this.executeSingleCall(tc))
+    );
+    return results;
+  }
+  async executeSingleCall(toolCall) {
+    const { id, function: fn } = toolCall;
+    const definition = this.tools.get(fn.name);
+    if (!definition) {
+      return {
+        role: "tool",
+        tool_call_id: id,
+        content: JSON.stringify({ error: `Unknown tool: ${fn.name}` })
+      };
+    }
+    const scope = definition.permission ?? this.defaultPermission;
+    let args;
+    try {
+      args = JSON.parse(fn.arguments);
+    } catch {
+      return {
+        role: "tool",
+        tool_call_id: id,
+        content: JSON.stringify({ error: `Invalid JSON arguments for ${fn.name}` })
+      };
+    }
+    const { allowed, reason } = await this.vorim.check(this.agentId, scope);
+    if (!allowed) {
+      const event = {
+        agent_id: this.agentId,
+        event_type: "tool_call",
+        action: fn.name,
+        resource: truncate(fn.arguments, 500),
+        permission: scope,
+        result: "denied",
+        metadata: { reason, framework: "openai" }
+      };
+      this.emitAudit(event);
+      return {
+        role: "tool",
+        tool_call_id: id,
+        content: JSON.stringify({ error: `Permission denied: ${scope}${reason ? ` \u2014 ${reason}` : ""}` })
+      };
+    }
+    const start = Date.now();
+    try {
+      const result = await definition.execute(args);
+      const content = typeof result === "string" ? result : JSON.stringify(result);
+      const event = {
+        agent_id: this.agentId,
+        event_type: "tool_call",
+        action: fn.name,
+        resource: truncate(fn.arguments, 500),
+        permission: scope,
+        result: "success",
+        latency_ms: Date.now() - start,
+        metadata: { framework: "openai" }
+      };
+      this.emitAudit(event);
+      return { role: "tool", tool_call_id: id, content };
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const event = {
+        agent_id: this.agentId,
+        event_type: "tool_call",
+        action: fn.name,
+        resource: truncate(fn.arguments, 500),
+        permission: scope,
+        result: "error",
+        latency_ms: Date.now() - start,
+        error_code: err instanceof Error ? err.name : "UNKNOWN",
+        metadata: { error: errMsg, framework: "openai" }
+      };
+      this.emitAudit(event);
+      return {
+        role: "tool",
+        tool_call_id: id,
+        content: JSON.stringify({ error: errMsg })
+      };
+    }
+  }
+  emitAudit(event) {
+    if (this.asyncAudit) {
+      this.vorim.emit(event).catch(() => {
+      });
+    } else {
+      this.vorim.emit(event).catch(() => {
+      });
+    }
+  }
+};
+async function runAgentLoop(config) {
+  const { openai, model = "gpt-4o", systemPrompt, maxIterations = 10, registry, userMessage } = config;
+  const messages = [];
+  if (systemPrompt) messages.push({ role: "system", content: systemPrompt });
+  messages.push({ role: "user", content: userMessage });
+  const tools = registry.toOpenAITools();
+  for (let i = 0; i < maxIterations; i++) {
+    const response = await openai.chat.completions.create({
+      model,
+      messages,
+      ...tools.length > 0 ? { tools } : {}
+    });
+    const choice = response.choices[0];
+    messages.push(choice.message);
+    if (choice.finish_reason === "stop" || !choice.message.tool_calls?.length) {
+      return choice.message.content ?? "";
+    }
+    const toolMessages = await registry.executeToolCalls(choice.message.tool_calls);
+    messages.push(...toolMessages);
+  }
+  return messages[messages.length - 1]?.content ?? "";
+}
+async function createVorimOpenAIAgent(config) {
+  const { vorim, name, description, capabilities, scopes, tools } = config;
+  const registration = await vorim.register({
+    name,
+    description,
+    capabilities,
+    scopes
+  });
+  const agentId = registration.agent.agent_id;
+  const registry = new VorimToolRegistry({ vorim, agentId });
+  registry.addAll(tools);
+  return {
+    agentId,
+    registration,
+    registry,
+    privateKey: registration.private_key
+  };
+}
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max) + "\u2026" : str;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VorimToolRegistry,
+  createVorimOpenAIAgent,
+  runAgentLoop
+});
+//# sourceMappingURL=openai.cjs.map

package/dist/integrations/openai.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/openai.ts"],"sourcesContent":["// ============================================================================\n// VORIM SDK — OpenAI Integration\n// Wraps OpenAI function calling with Vorim permission checks, audit trails,\n// and agent identity. Works with the OpenAI Node.js SDK (chat completions\n// with tool use).\n//\n// Peer dependency: openai >=4.0.0\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { PermissionScope, AuditEventInput } from '../types.js';\n\n// ─── Re-declared OpenAI types (peer dependency — not bundled) ─────────────\n\ninterface ChatCompletionTool {\n  type: 'function';\n  function: {\n    name: string;\n    description?: string;\n    parameters?: Record<string, unknown>;\n    strict?: boolean;\n  };\n}\n\ninterface ToolCall {\n  id: string;\n  type: 'function';\n  function: {\n    name: string;\n    arguments: string;\n  };\n}\n\ninterface ToolMessage {\n  role: 'tool';\n  tool_call_id: string;\n  content: string;\n}\n\n// ─── Configuration ────────────────────────────────────────────────────────\n\nexport interface VorimToolDefinition<TArgs = Record<string, unknown>, TResult = unknown> {\n  /** Tool name (must match the function name sent to OpenAI). */\n  name: string;\n  /** Description shown to the LLM. */\n  description: string;\n  /** JSON Schema for the tool's parameters. */\n  parameters: Record<string, unknown>;\n  /** The function to execute when the tool is called. */\n  execute: (args: TArgs) => Promise<TResult>;\n  /** Vorim permission scope required. @default 'agent:execute' */\n  permission?: PermissionScope;\n  /** Whether to use strict mode for OpenAI structured outputs. */\n  strict?: boolean;\n}\n\nexport interface VorimOpenAIConfig {\n  /** Vorim SDK instance. */\n  vorim: VorimSDK;\n  /** The Vorim agent_id. */\n  agentId: string;\n  /** Default permission scope for tools without an explicit one. @default 'agent:execute' */\n  defaultPermission?: PermissionScope;\n  /** Whether to emit audit events asynchronously. @default true */\n  asyncAudit?: boolean;\n}\n\n// ─── Tool Registry ────────────────────────────────────────────────────────\n\n/**\n * Manages a set of tools with Vorim permission checks and audit logging.\n * Converts tools to OpenAI's `ChatCompletionTool` format and handles\n * execution of tool calls from the model's response.\n *\n * @example\n * ```ts\n * import OpenAI from \"openai\";\n * import createVorim from \"@vorim/sdk\";\n * import { VorimToolRegistry } from \"@vorim/sdk/integrations/openai\";\n *\n * const vorim = createVorim({ apiKey: \"agid_sk_live_...\" });\n * const openai = new OpenAI();\n *\n * const registry = new VorimToolRegistry({\n *   vorim,\n *   agentId: \"agid_acme_a1b2c3d4\",\n * });\n *\n * registry.add({\n *   name: \"search_docs\",\n *   description: \"Search internal documents\",\n *   parameters: {\n *     type: \"object\",\n *     properties: { query: { type: \"string\" } },\n *     required: [\"query\"],\n *   },\n *   execute: async ({ query }) => searchDocs(query),\n *   permission: \"agent:read\",\n * });\n *\n * // Use with OpenAI chat completions\n * const response = await openai.chat.completions.create({\n *   model: \"gpt-4o\",\n *   messages,\n *   tools: registry.toOpenAITools(),\n * });\n *\n * // Execute tool calls from the response\n * const toolMessages = await registry.executeToolCalls(\n *   response.choices[0].message.tool_calls ?? []\n * );\n * ```\n */\nexport class VorimToolRegistry {\n  private vorim: VorimSDK;\n  private agentId: string;\n  private defaultPermission: PermissionScope;\n  private asyncAudit: boolean;\n  private tools = new Map<string, VorimToolDefinition>();\n\n  constructor(config: VorimOpenAIConfig) {\n    this.vorim = config.vorim;\n    this.agentId = config.agentId;\n    this.defaultPermission = config.defaultPermission ?? 'agent:execute';\n    this.asyncAudit = config.asyncAudit ?? true;\n  }\n\n  /** Register a tool. */\n  add<TArgs, TResult>(definition: VorimToolDefinition<TArgs, TResult>): this {\n    this.tools.set(definition.name, definition as VorimToolDefinition);\n    return this;\n  }\n\n  /** Register multiple tools. */\n  addAll(definitions: VorimToolDefinition[]): this {\n    for (const def of definitions) this.add(def);\n    return this;\n  }\n\n  /** Convert registered tools to OpenAI's ChatCompletionTool format. */\n  toOpenAITools(): ChatCompletionTool[] {\n    return [...this.tools.values()].map(t => ({\n      type: 'function' as const,\n      function: {\n        name: t.name,\n        description: t.description,\n        parameters: t.parameters,\n        ...(t.strict != null ? { strict: t.strict } : {}),\n      },\n    }));\n  }\n\n  /**\n   * Execute tool calls from an OpenAI chat completion response.\n   * Each call is checked against Vorim permissions and audited.\n   * Returns an array of tool messages ready to append to the conversation.\n   */\n  async executeToolCalls(toolCalls: ToolCall[]): Promise<ToolMessage[]> {\n    const results = await Promise.all(\n      toolCalls.map(tc => this.executeSingleCall(tc)),\n    );\n    return results;\n  }\n\n  private async executeSingleCall(toolCall: ToolCall): Promise<ToolMessage> {\n    const { id, function: fn } = toolCall;\n    const definition = this.tools.get(fn.name);\n\n    if (!definition) {\n      return {\n        role: 'tool',\n        tool_call_id: id,\n        content: JSON.stringify({ error: `Unknown tool: ${fn.name}` }),\n      };\n    }\n\n    const scope = definition.permission ?? this.defaultPermission;\n    let args: unknown;\n    try {\n      args = JSON.parse(fn.arguments);\n    } catch {\n      return {\n        role: 'tool',\n        tool_call_id: id,\n        content: JSON.stringify({ error: `Invalid JSON arguments for ${fn.name}` }),\n      };\n    }\n\n    // 1. Permission check\n    const { allowed, reason } = await this.vorim.check(this.agentId, scope);\n\n    if (!allowed) {\n      const event: AuditEventInput = {\n        agent_id: this.agentId,\n        event_type: 'tool_call',\n        action: fn.name,\n        resource: truncate(fn.arguments, 500),\n        permission: scope,\n        result: 'denied',\n        metadata: { reason, framework: 'openai' },\n      };\n      this.emitAudit(event);\n      return {\n        role: 'tool',\n        tool_call_id: id,\n        content: JSON.stringify({ error: `Permission denied: ${scope}${reason ? ` — ${reason}` : ''}` }),\n      };\n    }\n\n    // 2. Execute\n    const start = Date.now();\n    try {\n      const result = await definition.execute(args as any);\n      const content = typeof result === 'string' ? result : JSON.stringify(result);\n\n      const event: AuditEventInput = {\n        agent_id: this.agentId,\n        event_type: 'tool_call',\n        action: fn.name,\n        resource: truncate(fn.arguments, 500),\n        permission: scope,\n        result: 'success',\n        latency_ms: Date.now() - start,\n        metadata: { framework: 'openai' },\n      };\n      this.emitAudit(event);\n\n      return { role: 'tool', tool_call_id: id, content };\n    } catch (err) {\n      const errMsg = err instanceof Error ? err.message : String(err);\n\n      const event: AuditEventInput = {\n        agent_id: this.agentId,\n        event_type: 'tool_call',\n        action: fn.name,\n        resource: truncate(fn.arguments, 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: errMsg, framework: 'openai' },\n      };\n      this.emitAudit(event);\n\n      return {\n        role: 'tool',\n        tool_call_id: id,\n        content: JSON.stringify({ error: errMsg }),\n      };\n    }\n  }\n\n  private emitAudit(event: AuditEventInput): void {\n    if (this.asyncAudit) {\n      this.vorim.emit(event).catch(() => {});\n    } else {\n      // Caller is already in an async context, but we don't await here\n      // in async mode. For sync audit, the executeToolCalls caller\n      // should await the full pipeline.\n      this.vorim.emit(event).catch(() => {});\n    }\n  }\n}\n\n// ─── Agent Loop ───────────────────────────────────────────────────────────\n\nexport interface VorimAgentLoopConfig extends VorimOpenAIConfig {\n  /** OpenAI client instance. */\n  openai: OpenAIClient;\n  /** Model to use. @default 'gpt-4o' */\n  model?: string;\n  /** System prompt for the agent. */\n  systemPrompt?: string;\n  /** Maximum iterations before stopping. @default 10 */\n  maxIterations?: number;\n}\n\n/** Minimal OpenAI client interface (avoids importing the full SDK). */\ninterface OpenAIClient {\n  chat: {\n    completions: {\n      create(params: any): Promise<any>;\n    };\n  };\n}\n\n/**\n * Runs a complete agent loop with OpenAI function calling, Vorim\n * permission enforcement, and audit logging.\n *\n * @example\n * ```ts\n * import OpenAI from \"openai\";\n * import createVorim from \"@vorim/sdk\";\n * import { runAgentLoop, VorimToolRegistry } from \"@vorim/sdk/integrations/openai\";\n *\n * const registry = new VorimToolRegistry({ vorim, agentId });\n * registry.add({ name: \"search\", ... });\n *\n * const response = await runAgentLoop({\n *   vorim,\n *   agentId,\n *   openai: new OpenAI(),\n *   model: \"gpt-4o\",\n *   systemPrompt: \"You are a helpful assistant.\",\n *   registry,\n *   userMessage: \"Find docs about onboarding\",\n * });\n * ```\n */\nexport async function runAgentLoop(\n  config: VorimAgentLoopConfig & {\n    registry: VorimToolRegistry;\n    userMessage: string;\n  },\n): Promise<string> {\n  const { openai, model = 'gpt-4o', systemPrompt, maxIterations = 10, registry, userMessage } = config;\n\n  const messages: any[] = [];\n  if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });\n  messages.push({ role: 'user', content: userMessage });\n\n  const tools = registry.toOpenAITools();\n\n  for (let i = 0; i < maxIterations; i++) {\n    const response = await openai.chat.completions.create({\n      model,\n      messages,\n      ...(tools.length > 0 ? { tools } : {}),\n    });\n\n    const choice = response.choices[0];\n    messages.push(choice.message);\n\n    // If the model is done (no tool calls), return the response\n    if (choice.finish_reason === 'stop' || !choice.message.tool_calls?.length) {\n      return choice.message.content ?? '';\n    }\n\n    // Execute tool calls and add results to messages\n    const toolMessages = await registry.executeToolCalls(choice.message.tool_calls);\n    messages.push(...toolMessages);\n  }\n\n  return messages[messages.length - 1]?.content ?? '';\n}\n\n// ─── Agent Registration Helper ───────────────────────────────────────────\n\n/**\n * Registers a new agent with Vorim and returns a ready-to-use tool registry.\n *\n * @example\n * ```ts\n * const { agentId, registry } = await createVorimOpenAIAgent({\n *   vorim,\n *   name: \"support-agent\",\n *   capabilities: [\"search\", \"email\"],\n *   scopes: [\"agent:read\", \"agent:execute\", \"agent:communicate\"],\n *   tools: [searchTool, emailTool],\n * });\n * ```\n */\nexport async function createVorimOpenAIAgent(config: {\n  vorim: VorimSDK;\n  name: string;\n  description?: string;\n  capabilities: string[];\n  scopes: PermissionScope[];\n  tools: VorimToolDefinition[];\n}) {\n  const { vorim, name, description, capabilities, scopes, tools } = config;\n\n  const registration = await vorim.register({\n    name,\n    description,\n    capabilities,\n    scopes,\n  });\n\n  const agentId = registration.agent.agent_id;\n\n  const registry = new VorimToolRegistry({ vorim, agentId });\n  registry.addAll(tools);\n\n  return {\n    agentId,\n    registration,\n    registry,\n    privateKey: registration.private_key,\n  };\n}\n\n// ─── Helpers ──────────────────────────────────────────────────────────────\n\nfunction truncate(str: string, max: number): string {\n  return str.length > max ? str.slice(0, max) + '…' : str;\n}\n"],"mappings":"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","names":[]}

package/dist/integrations/openai.d.cts

@@ -0,0 +1,189 @@
+import { VorimSDK, PermissionScope, AgentRegistrationResult } from '../index.cjs';
+
+interface ChatCompletionTool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+}
+interface VorimToolDefinition<TArgs = Record<string, unknown>, TResult = unknown> {
+    /** Tool name (must match the function name sent to OpenAI). */
+    name: string;
+    /** Description shown to the LLM. */
+    description: string;
+    /** JSON Schema for the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** The function to execute when the tool is called. */
+    execute: (args: TArgs) => Promise<TResult>;
+    /** Vorim permission scope required. @default 'agent:execute' */
+    permission?: PermissionScope;
+    /** Whether to use strict mode for OpenAI structured outputs. */
+    strict?: boolean;
+}
+interface VorimOpenAIConfig {
+    /** Vorim SDK instance. */
+    vorim: VorimSDK;
+    /** The Vorim agent_id. */
+    agentId: string;
+    /** Default permission scope for tools without an explicit one. @default 'agent:execute' */
+    defaultPermission?: PermissionScope;
+    /** Whether to emit audit events asynchronously. @default true */
+    asyncAudit?: boolean;
+}
+/**
+ * Manages a set of tools with Vorim permission checks and audit logging.
+ * Converts tools to OpenAI's `ChatCompletionTool` format and handles
+ * execution of tool calls from the model's response.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import createVorim from "@vorim/sdk";
+ * import { VorimToolRegistry } from "@vorim/sdk/integrations/openai";
+ *
+ * const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+ * const openai = new OpenAI();
+ *
+ * const registry = new VorimToolRegistry({
+ *   vorim,
+ *   agentId: "agid_acme_a1b2c3d4",
+ * });
+ *
+ * registry.add({
+ *   name: "search_docs",
+ *   description: "Search internal documents",
+ *   parameters: {
+ *     type: "object",
+ *     properties: { query: { type: "string" } },
+ *     required: ["query"],
+ *   },
+ *   execute: async ({ query }) => searchDocs(query),
+ *   permission: "agent:read",
+ * });
+ *
+ * // Use with OpenAI chat completions
+ * const response = await openai.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages,
+ *   tools: registry.toOpenAITools(),
+ * });
+ *
+ * // Execute tool calls from the response
+ * const toolMessages = await registry.executeToolCalls(
+ *   response.choices[0].message.tool_calls ?? []
+ * );
+ * ```
+ */
+declare class VorimToolRegistry {
+    private vorim;
+    private agentId;
+    private defaultPermission;
+    private asyncAudit;
+    private tools;
+    constructor(config: VorimOpenAIConfig);
+    /** Register a tool. */
+    add<TArgs, TResult>(definition: VorimToolDefinition<TArgs, TResult>): this;
+    /** Register multiple tools. */
+    addAll(definitions: VorimToolDefinition[]): this;
+    /** Convert registered tools to OpenAI's ChatCompletionTool format. */
+    toOpenAITools(): ChatCompletionTool[];
+    /**
+     * Execute tool calls from an OpenAI chat completion response.
+     * Each call is checked against Vorim permissions and audited.
+     * Returns an array of tool messages ready to append to the conversation.
+     */
+    executeToolCalls(toolCalls: ToolCall[]): Promise<ToolMessage[]>;
+    private executeSingleCall;
+    private emitAudit;
+}
+interface VorimAgentLoopConfig extends VorimOpenAIConfig {
+    /** OpenAI client instance. */
+    openai: OpenAIClient;
+    /** Model to use. @default 'gpt-4o' */
+    model?: string;
+    /** System prompt for the agent. */
+    systemPrompt?: string;
+    /** Maximum iterations before stopping. @default 10 */
+    maxIterations?: number;
+}
+/** Minimal OpenAI client interface (avoids importing the full SDK). */
+interface OpenAIClient {
+    chat: {
+        completions: {
+            create(params: any): Promise<any>;
+        };
+    };
+}
+/**
+ * Runs a complete agent loop with OpenAI function calling, Vorim
+ * permission enforcement, and audit logging.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import createVorim from "@vorim/sdk";
+ * import { runAgentLoop, VorimToolRegistry } from "@vorim/sdk/integrations/openai";
+ *
+ * const registry = new VorimToolRegistry({ vorim, agentId });
+ * registry.add({ name: "search", ... });
+ *
+ * const response = await runAgentLoop({
+ *   vorim,
+ *   agentId,
+ *   openai: new OpenAI(),
+ *   model: "gpt-4o",
+ *   systemPrompt: "You are a helpful assistant.",
+ *   registry,
+ *   userMessage: "Find docs about onboarding",
+ * });
+ * ```
+ */
+declare function runAgentLoop(config: VorimAgentLoopConfig & {
+    registry: VorimToolRegistry;
+    userMessage: string;
+}): Promise<string>;
+/**
+ * Registers a new agent with Vorim and returns a ready-to-use tool registry.
+ *
+ * @example
+ * ```ts
+ * const { agentId, registry } = await createVorimOpenAIAgent({
+ *   vorim,
+ *   name: "support-agent",
+ *   capabilities: ["search", "email"],
+ *   scopes: ["agent:read", "agent:execute", "agent:communicate"],
+ *   tools: [searchTool, emailTool],
+ * });
+ * ```
+ */
+declare function createVorimOpenAIAgent(config: {
+    vorim: VorimSDK;
+    name: string;
+    description?: string;
+    capabilities: string[];
+    scopes: PermissionScope[];
+    tools: VorimToolDefinition[];
+}): Promise<{
+    agentId: string;
+    registration: AgentRegistrationResult;
+    registry: VorimToolRegistry;
+    privateKey: string;
+}>;
+
+export { type VorimAgentLoopConfig, type VorimOpenAIConfig, type VorimToolDefinition, VorimToolRegistry, createVorimOpenAIAgent, runAgentLoop };

package/dist/integrations/openai.d.ts

@@ -0,0 +1,189 @@
+import { VorimSDK, PermissionScope, AgentRegistrationResult } from '../index.js';
+
+interface ChatCompletionTool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+}
+interface VorimToolDefinition<TArgs = Record<string, unknown>, TResult = unknown> {
+    /** Tool name (must match the function name sent to OpenAI). */
+    name: string;
+    /** Description shown to the LLM. */
+    description: string;
+    /** JSON Schema for the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** The function to execute when the tool is called. */
+    execute: (args: TArgs) => Promise<TResult>;
+    /** Vorim permission scope required. @default 'agent:execute' */
+    permission?: PermissionScope;
+    /** Whether to use strict mode for OpenAI structured outputs. */
+    strict?: boolean;
+}
+interface VorimOpenAIConfig {
+    /** Vorim SDK instance. */
+    vorim: VorimSDK;
+    /** The Vorim agent_id. */
+    agentId: string;
+    /** Default permission scope for tools without an explicit one. @default 'agent:execute' */
+    defaultPermission?: PermissionScope;
+    /** Whether to emit audit events asynchronously. @default true */
+    asyncAudit?: boolean;
+}
+/**
+ * Manages a set of tools with Vorim permission checks and audit logging.
+ * Converts tools to OpenAI's `ChatCompletionTool` format and handles
+ * execution of tool calls from the model's response.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import createVorim from "@vorim/sdk";
+ * import { VorimToolRegistry } from "@vorim/sdk/integrations/openai";
+ *
+ * const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+ * const openai = new OpenAI();
+ *
+ * const registry = new VorimToolRegistry({
+ *   vorim,
+ *   agentId: "agid_acme_a1b2c3d4",
+ * });
+ *
+ * registry.add({
+ *   name: "search_docs",
+ *   description: "Search internal documents",
+ *   parameters: {
+ *     type: "object",
+ *     properties: { query: { type: "string" } },
+ *     required: ["query"],
+ *   },
+ *   execute: async ({ query }) => searchDocs(query),
+ *   permission: "agent:read",
+ * });
+ *
+ * // Use with OpenAI chat completions
+ * const response = await openai.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages,
+ *   tools: registry.toOpenAITools(),
+ * });
+ *
+ * // Execute tool calls from the response
+ * const toolMessages = await registry.executeToolCalls(
+ *   response.choices[0].message.tool_calls ?? []
+ * );
+ * ```
+ */
+declare class VorimToolRegistry {
+    private vorim;
+    private agentId;
+    private defaultPermission;
+    private asyncAudit;
+    private tools;
+    constructor(config: VorimOpenAIConfig);
+    /** Register a tool. */
+    add<TArgs, TResult>(definition: VorimToolDefinition<TArgs, TResult>): this;
+    /** Register multiple tools. */
+    addAll(definitions: VorimToolDefinition[]): this;
+    /** Convert registered tools to OpenAI's ChatCompletionTool format. */
+    toOpenAITools(): ChatCompletionTool[];
+    /**
+     * Execute tool calls from an OpenAI chat completion response.
+     * Each call is checked against Vorim permissions and audited.
+     * Returns an array of tool messages ready to append to the conversation.
+     */
+    executeToolCalls(toolCalls: ToolCall[]): Promise<ToolMessage[]>;
+    private executeSingleCall;
+    private emitAudit;
+}
+interface VorimAgentLoopConfig extends VorimOpenAIConfig {
+    /** OpenAI client instance. */
+    openai: OpenAIClient;
+    /** Model to use. @default 'gpt-4o' */
+    model?: string;
+    /** System prompt for the agent. */
+    systemPrompt?: string;
+    /** Maximum iterations before stopping. @default 10 */
+    maxIterations?: number;
+}
+/** Minimal OpenAI client interface (avoids importing the full SDK). */
+interface OpenAIClient {
+    chat: {
+        completions: {
+            create(params: any): Promise<any>;
+        };
+    };
+}
+/**
+ * Runs a complete agent loop with OpenAI function calling, Vorim
+ * permission enforcement, and audit logging.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import createVorim from "@vorim/sdk";
+ * import { runAgentLoop, VorimToolRegistry } from "@vorim/sdk/integrations/openai";
+ *
+ * const registry = new VorimToolRegistry({ vorim, agentId });
+ * registry.add({ name: "search", ... });
+ *
+ * const response = await runAgentLoop({
+ *   vorim,
+ *   agentId,
+ *   openai: new OpenAI(),
+ *   model: "gpt-4o",
+ *   systemPrompt: "You are a helpful assistant.",
+ *   registry,
+ *   userMessage: "Find docs about onboarding",
+ * });
+ * ```
+ */
+declare function runAgentLoop(config: VorimAgentLoopConfig & {
+    registry: VorimToolRegistry;
+    userMessage: string;
+}): Promise<string>;
+/**
+ * Registers a new agent with Vorim and returns a ready-to-use tool registry.
+ *
+ * @example
+ * ```ts
+ * const { agentId, registry } = await createVorimOpenAIAgent({
+ *   vorim,
+ *   name: "support-agent",
+ *   capabilities: ["search", "email"],
+ *   scopes: ["agent:read", "agent:execute", "agent:communicate"],
+ *   tools: [searchTool, emailTool],
+ * });
+ * ```
+ */
+declare function createVorimOpenAIAgent(config: {
+    vorim: VorimSDK;
+    name: string;
+    description?: string;
+    capabilities: string[];
+    scopes: PermissionScope[];
+    tools: VorimToolDefinition[];
+}): Promise<{
+    agentId: string;
+    registration: AgentRegistrationResult;
+    registry: VorimToolRegistry;
+    privateKey: string;
+}>;
+
+export { type VorimAgentLoopConfig, type VorimOpenAIConfig, type VorimToolDefinition, VorimToolRegistry, createVorimOpenAIAgent, runAgentLoop };