@vorim/sdk 3.7.5 → 3.7.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/_runtime-gate-DOJUKJBu.d.cts +23 -0
- package/dist/_runtime-gate-DOJUKJBu.d.ts +23 -0
- package/dist/index.cjs +5 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +5 -3
- package/dist/index.js.map +1 -1
- package/dist/integrations/anthropic.cjs +4 -1
- package/dist/integrations/anthropic.cjs.map +1 -1
- package/dist/integrations/anthropic.d.cts +8 -1
- package/dist/integrations/anthropic.d.ts +8 -1
- package/dist/integrations/anthropic.js +4 -1
- package/dist/integrations/anthropic.js.map +1 -1
- package/dist/integrations/crewai.cjs +56 -2
- package/dist/integrations/crewai.cjs.map +1 -1
- package/dist/integrations/crewai.d.cts +22 -2
- package/dist/integrations/crewai.d.ts +22 -2
- package/dist/integrations/crewai.js +54 -2
- package/dist/integrations/crewai.js.map +1 -1
- package/dist/integrations/langchain.cjs +99 -8
- package/dist/integrations/langchain.cjs.map +1 -1
- package/dist/integrations/langchain.d.cts +23 -0
- package/dist/integrations/langchain.d.ts +23 -0
- package/dist/integrations/langchain.js +99 -8
- package/dist/integrations/langchain.js.map +1 -1
- package/dist/integrations/langgraph.cjs +78 -6
- package/dist/integrations/langgraph.cjs.map +1 -1
- package/dist/integrations/langgraph.d.cts +1 -0
- package/dist/integrations/langgraph.d.ts +1 -0
- package/dist/integrations/langgraph.js +78 -6
- package/dist/integrations/langgraph.js.map +1 -1
- package/dist/integrations/llamaindex.cjs +96 -8
- package/dist/integrations/llamaindex.cjs.map +1 -1
- package/dist/integrations/llamaindex.d.cts +23 -0
- package/dist/integrations/llamaindex.d.ts +23 -0
- package/dist/integrations/llamaindex.js +96 -8
- package/dist/integrations/llamaindex.js.map +1 -1
- package/dist/integrations/openai.cjs +4 -1
- package/dist/integrations/openai.cjs.map +1 -1
- package/dist/integrations/openai.d.cts +8 -1
- package/dist/integrations/openai.d.ts +8 -1
- package/dist/integrations/openai.js +4 -1
- package/dist/integrations/openai.js.map +1 -1
- package/dist/integrations/vercel-ai.cjs +2 -1
- package/dist/integrations/vercel-ai.cjs.map +1 -1
- package/dist/integrations/vercel-ai.d.cts +7 -1
- package/dist/integrations/vercel-ai.d.ts +7 -1
- package/dist/integrations/vercel-ai.js +2 -1
- package/dist/integrations/vercel-ai.js.map +1 -1
- package/package.json +1 -1
- package/dist/_runtime-gate-DZQTkw4J.d.cts +0 -11
- package/dist/_runtime-gate-DZQTkw4J.d.ts +0 -11
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/replay.ts","../../src/integrations/langchain.ts","../../src/integrations/langgraph.ts"],"sourcesContent":["/**\n * Replayable agent decision evidence helpers.\n *\n * Canonical-form hashing for the VAIP -02 schema fields that the SDK\n * attaches to audit events. The hashes recorded in audit_events.tool_catalogue_hash\n * and audit_events.system_prompt_hash use these functions, so the bytes\n * an auditor or counterparty reconstructs must match what the SDK produced.\n *\n * These helpers are intentionally separate from the signing path. The\n * v0 canonical signature form (event_type|action|resource|input_hash|\n * output_hash|result) does NOT cover model_version, tool_catalogue_hash,\n * or system_prompt_hash. They will enter the canonical bytes in v1\n * (RFC 8785 JCS) in a follow-up release.\n *\n * Stable across SDK versions: the canonical-form version is documented\n * in CANONICAL_TOOL_CATALOGUE_VERSION. Future changes get a v2 etc;\n * never edit the existing v1 logic, or already-recorded hashes lose\n * their meaning.\n */\n\n// ─── Versioning ───────────────────────────────────────────────────────────\n\n/**\n * Canonical-form version for tool catalogue hashes produced by this SDK.\n * Recorded in tool_catalogue_canon_version on the event metadata (when\n * the metadata field is used) so verifiers know which hash recipe to\n * reproduce. Increment ONLY if the algorithm changes in a way that\n * would change the hash for the same logical catalogue.\n */\nexport const CANONICAL_TOOL_CATALOGUE_VERSION = 'v1' as const;\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Minimum shape a tool needs for catalogue hashing. The framework\n * integrations adapt their native tool objects to this shape before\n * calling hashToolCatalogue.\n */\nexport interface CatalogueTool {\n /** The name the model sees and calls. Required. */\n name: string;\n /** Human-readable description shown to the model. Optional; absent ↔ empty string. */\n description?: string;\n /**\n * JSON Schema describing the tool's input parameters. Optional;\n * absent ↔ empty object `{}`. The schema gets RFC 8785 JCS-canonicalised\n * before hashing so semantically-equivalent variations (key order,\n * whitespace) produce the same hash.\n */\n schema?: Record<string, unknown> | null;\n}\n\n// ─── RFC 8785 JCS subset ──────────────────────────────────────────────────\n\n/**\n * RFC 8785 JSON Canonicalization Scheme, sufficient subset for tool\n * catalogue values.\n *\n * Rules:\n * - Object keys sorted lexicographically by UTF-16 code units (which\n * is what JS string comparison does naturally).\n * - No whitespace between tokens.\n * - Numbers: integers as integers, finite floats per ECMAScript\n * Number.prototype.toString. JCS forbids NaN and Infinity.\n * - Strings: JSON-escape using minimal set per RFC 8259 § 7.\n * - null, true, false, arrays: as JSON.stringify produces them, since\n * JSON.stringify already produces the canonical form for these.\n *\n * Not vendoring a full library because tool schemas don't carry\n * non-integer numbers in practice and the JS spec for Number.toString\n * happens to coincide with JCS § 3.2.2.2 for the integer case.\n */\nexport function jcsCanonicalise(value: unknown): string {\n if (value === null) return 'null';\n if (value === true) return 'true';\n if (value === false) return 'false';\n\n if (typeof value === 'number') {\n if (!Number.isFinite(value)) {\n throw new Error('jcsCanonicalise: NaN and Infinity are not JCS-valid');\n }\n // Fail closed on magnitudes where JS .toString() and CPython diverge, so TS\n // and Python sign byte-identical bytes (or both reject). JS switches\n // integer-valued floats to exponent form at |x| >= 1e21 (Python expands to\n // full digits); in [1e-7, 1e-4) JS keeps decimals while Python repr() uses\n // exponent form. Keeping both engines in lockstep preserves cross-SDK\n // signature verifiability.\n const abs = Math.abs(value);\n // Reject ranges where JS Number.toString() and CPython diverge: |x| >= 1e21,\n // |x| < 1e-4, and integer-valued |x| > 2^53 (JS shortest-round-trip vs\n // Python exact int expansion — they only coincide for \"round\" values there).\n if (value !== 0 && (abs >= 1e21 || abs < 1e-4 || (Number.isInteger(value) && abs > 2 ** 53))) {\n throw new Error(\n `jcsCanonicalise: numbers in the ranges where JS and Python formatting ` +\n `diverge (|x| >= 1e21, |x| < 1e-4, or integer |x| > 2^53) are not ` +\n `supported in signed metadata. Use a string instead of ${value}.`,\n );\n }\n // For integers in safe range and ordinary decimals, .toString() matches JCS\n // (modern JS engines use the shortest round-trip representation).\n return value.toString();\n }\n\n if (typeof value === 'string') {\n return JSON.stringify(value);\n }\n\n if (Array.isArray(value)) {\n return '[' + value.map(jcsCanonicalise).join(',') + ']';\n }\n\n if (typeof value === 'object') {\n const obj = value as Record<string, unknown>;\n // Filter undefined-valued fields, matching @vorim/verify and\n // @vorim/shared-types. Without this the SDK throws on { a: 1, b: undefined }\n // while the verifier silently drops b — a cross-module canonical-form\n // divergence that would break signature verification on such events.\n const keys = Object.keys(obj).filter(k => obj[k] !== undefined).sort();\n const parts = keys.map(k => JSON.stringify(k) + ':' + jcsCanonicalise(obj[k]));\n return '{' + parts.join(',') + '}';\n }\n\n // undefined, function, symbol, bigint — not JSON-representable\n throw new Error(`jcsCanonicalise: unsupported value type: ${typeof value}`);\n}\n\n// ─── SHA-256 ──────────────────────────────────────────────────────────────\n\nasync function sha256Hex(input: string | Uint8Array): Promise<string> {\n const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input;\n\n // Node.js Web Crypto (Node 18+) supports digest. Browser Web Crypto does too.\n // Fall back to node:crypto if Web Crypto is unavailable.\n const subtle = (globalThis as any).crypto?.subtle;\n if (subtle) {\n const buf = await subtle.digest('SHA-256', bytes);\n return Array.from(new Uint8Array(buf))\n .map(b => b.toString(16).padStart(2, '0'))\n .join('');\n }\n\n // Node fallback\n const nodeCrypto = await import('node:crypto');\n return nodeCrypto.createHash('sha256').update(bytes).digest('hex');\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Hash a single tool definition. Returns `sha256:<hex>`.\n *\n * Canonical form (v1):\n * JCS-canonicalised JSON of `{name, description, schema}` where\n * absent fields substitute `description: \"\"` and `schema: {}`.\n */\nexport async function hashTool(tool: CatalogueTool): Promise<string> {\n const normalised = {\n name: tool.name,\n description: tool.description ?? '',\n schema: tool.schema ?? {},\n };\n const hex = await sha256Hex(jcsCanonicalise(normalised));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash an entire tool catalogue. Returns `sha256:<hex>`.\n *\n * Reordering tools does NOT change the hash (tool hashes sorted\n * lexicographically before concatenation). Adding, removing, or\n * modifying a tool DOES change the hash.\n *\n * Per-tool hashing first means a verifier comparing two catalogue\n * hashes that differ can also be given the per-tool hashes to\n * identify which specific tool changed.\n */\nexport async function hashToolCatalogue(tools: CatalogueTool[]): Promise<string> {\n if (tools.length === 0) {\n // Empty catalogue has a deterministic, stable hash distinct from \"no field\"\n return `sha256:${await sha256Hex('[]')}`;\n }\n const perTool = await Promise.all(tools.map(hashTool));\n perTool.sort();\n const hex = await sha256Hex(perTool.join(''));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash a system prompt. Returns `sha256:<hex>`.\n *\n * The prompt is UTF-8 encoded and hashed verbatim — no normalisation.\n * If a caller wants to ignore whitespace or comment differences, they\n * should normalise before calling. The intent here is deterministic\n * reproducibility, not semantic equivalence.\n */\nexport async function hashSystemPrompt(prompt: string): Promise<string> {\n const hex = await sha256Hex(prompt);\n return `sha256:${hex}`;\n}\n\n/**\n * Convenience: hash the previous event's canonical bytes for use in\n * the prev_event_hash field of hash-chained ingest. Caller provides\n * the canonical bytes (use canonicalPayloadV0 from the main module).\n */\nexport async function hashPreviousEvent(canonicalBytes: string): Promise<string> {\n const hex = await sha256Hex(canonicalBytes);\n return `sha256:${hex}`;\n}\n\n// ─── Replay context — framework integration helper ────────────────────────\n\n/**\n * Raw inputs the integration captures from the framework. Set by the\n * integration's config; turned into hashes by {@link prepareReplayContext}.\n */\nexport interface ReplayInputs {\n /** Stable identifier for the model. E.g. `\"anthropic:claude-opus-4-8\"`. */\n modelVersion?: string;\n /** Tools available to the agent at call time. Hashed via {@link hashToolCatalogue}. */\n tools?: CatalogueTool[];\n /** System prompt active at call time. Hashed via {@link hashSystemPrompt}. */\n systemPrompt?: string;\n}\n\n/**\n * Pre-computed hashes ready to attach to audit events. The three keys\n * match the audit_events column names.\n */\nexport interface ReplayContext {\n model_version?: string;\n tool_catalogue_hash?: string;\n system_prompt_hash?: string;\n}\n\n/**\n * Compute replay context once from raw inputs. Use at integration\n * setup time so each emit can attach the hashes without re-hashing.\n *\n * Returns an object suitable for spreading into an AuditEventInput:\n * `await vorim.emit({ ...event, ...replayContext })`\n *\n * If a field is absent in the inputs, it is absent in the result\n * (not the empty string). That keeps the event lean.\n */\nexport async function prepareReplayContext(\n inputs: ReplayInputs,\n): Promise<ReplayContext> {\n const ctx: ReplayContext = {};\n if (inputs.modelVersion) ctx.model_version = inputs.modelVersion;\n if (inputs.tools) ctx.tool_catalogue_hash = await hashToolCatalogue(inputs.tools);\n if (inputs.systemPrompt) ctx.system_prompt_hash = await hashSystemPrompt(inputs.systemPrompt);\n return ctx;\n}\n","// ============================================================================\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';\nimport {\n prepareReplayContext,\n type ReplayInputs,\n type ReplayContext,\n type CatalogueTool,\n} from '../replay.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 * Framework name recorded on each audit event's metadata. Defaults to\n * 'langchain'. The LangGraph wrapper sets this to 'langgraph' so the audit\n * trail names the graph correctly while reusing this tool-wrapping logic.\n * @default 'langchain'\n */\n framework?: string;\n /**\n * Replayable agent decision evidence (VAIP -02). When provided, the\n * hashes of the model version, tool catalogue, and system prompt are\n * attached to every emitted audit event so an auditor can later\n * reproduce the agent's decision context.\n *\n * Hashes are computed once on first emit and cached for subsequent\n * emits in this config's lifetime.\n *\n * These fields are NOT covered by the v0 canonical signature form;\n * advisory only until v1 (RFC 8785 JCS) lands.\n */\n replay?: ReplayInputs;\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, replay, framework = 'langchain' } = config;\n\n const originalCall = tool._call.bind(tool);\n const getReplayCtx = makeReplayContextGetter(replay);\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 — fail closed on a transport error rather than\n // crashing the host tool loop (matches the Python fail-closed gate).\n let allowed: boolean;\n let reason: string | undefined;\n try {\n ({ allowed, reason } = await vorim.check(agentId, scope));\n } catch {\n allowed = false;\n reason = 'permission check unavailable (failed closed)';\n }\n const replayCtx = await getReplayCtx();\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 },\n ...replayCtx,\n };\n await 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 },\n ...replayCtx,\n };\n await 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 },\n ...replayCtx,\n };\n await emitAudit(vorim, event, asyncAudit);\n\n return result;\n };\n\n return tool;\n}\n\n/**\n * Lazy-cached replay context getter. The hashes are computed once on\n * first call and reused for subsequent calls in this closure's lifetime.\n * Returns an empty object when no `replay` config was provided so the\n * spread is a no-op.\n */\nfunction makeReplayContextGetter(replay: ReplayInputs | undefined): () => Promise<ReplayContext> {\n if (!replay) return async () => ({});\n let cached: Promise<ReplayContext> | null = null;\n return () => {\n if (!cached) cached = prepareReplayContext(replay);\n return cached;\n };\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 private getReplayCtx: () => Promise<ReplayContext>;\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 /**\n * @param vorim Vorim SDK instance.\n * @param agentId The Vorim agent_id whose actions this callback audits.\n * @param replay Optional replayable-evidence inputs. Same shape as\n * {@link VorimLangChainConfig.replay}; hashes are\n * computed once and attached to every audit event.\n */\n constructor(vorim: VorimSDK, agentId: string, replay?: ReplayInputs) {\n this.vorim = vorim;\n this.agentId = agentId;\n this.getReplayCtx = makeReplayContextGetter(replay);\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 const replayCtx = await this.getReplayCtx();\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 ...replayCtx,\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 const replayCtx = await this.getReplayCtx();\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 ...replayCtx,\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, replay } = 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\n // If the caller passed `replay.tools`, use those. Otherwise derive a\n // tool catalogue from the rawTools we're about to wrap so the\n // replayable-evidence story works automatically.\n const derivedReplay: ReplayInputs | undefined = replay\n ? { ...replay, tools: replay.tools ?? await deriveCatalogueFromLangChainTools(rawTools) }\n : { tools: await deriveCatalogueFromLangChainTools(rawTools) };\n\n const agentConfig: VorimLangChainConfig = {\n vorim, agentId, permissionMap, defaultPermission, asyncAudit, replay: derivedReplay,\n };\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, derivedReplay);\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): Promise<void> | void {\n if (async) {\n vorim.emit(event).catch(() => {});\n return;\n }\n // asyncAudit=false: return the awaitable so callers can ensure the audit\n // event is persisted before the process exits.\n return vorim.emit(event).then(() => undefined).catch(() => undefined);\n}\n\n/**\n * Convert LangChain tools to the catalogue shape used by hashToolCatalogue.\n *\n * LangChain JS tool schemas are usually a Zod schema. `JSON.stringify(zod)`\n * serialises the internal `_def` (or `{}`), which does NOT match the FULL\n * JSON Schema envelope the Python SDK produces via pydantic\n * `model_json_schema()`. That mismatch makes the same logical tool hash to a\n * different `tool_catalogue_hash` across SDKs, breaking cross-SDK replay\n * verification. To match Python we convert a Zod schema to JSON Schema first\n * (via the optional, hoisted `zod-to-json-schema`; the SDK stays zero-dep, so\n * if it isn't resolvable at runtime we fall back to the plain shape).\n */\nasync function deriveCatalogueFromLangChainTools(tools: LangChainTool[]): Promise<CatalogueTool[]> {\n // Resolve the optional converter once. Guarded so a missing module (the\n // zero-dep SDK case) degrades gracefully instead of throwing.\n type ZodToJsonSchemaFn = (schema: unknown) => Record<string, unknown>;\n let zodToJsonSchema: ZodToJsonSchemaFn | null = null;\n try {\n // Specifier built indirectly so TS doesn't try to resolve the optional\n // module's types at compile time (the SDK declares no dependency on it).\n const mod: any = await import(/* @vite-ignore */ ('zod-to-json' + '-schema'));\n zodToJsonSchema = (mod.zodToJsonSchema ?? mod.default) as ZodToJsonSchemaFn;\n } catch {\n zodToJsonSchema = null;\n }\n\n const isZodSchema = (v: unknown): boolean =>\n !!v && typeof v === 'object' && '_def' in (v as Record<string, unknown>);\n\n return tools.map(t => {\n let schema: Record<string, unknown> | null = null;\n const raw = t.schema as unknown;\n if (raw && typeof raw === 'object') {\n if (isZodSchema(raw) && zodToJsonSchema) {\n // Zod -> full JSON Schema envelope (matches Python model_json_schema()).\n try {\n schema = zodToJsonSchema(raw);\n } catch {\n schema = null;\n }\n } else {\n // Already plain JSON-serialisable JSON Schema, use it; else null.\n try {\n schema = JSON.parse(JSON.stringify(raw));\n } catch {\n schema = null;\n }\n }\n }\n return {\n name: t.name,\n description: t.description ?? '',\n schema,\n };\n });\n}\n","// ============================================================================\n// VORIM SDK — LangGraph Integration\n// LangGraph builds stateful agent graphs out of LangChain tools. The right\n// place to enforce identity, permissions, and audit is the tool boundary —\n// every time a node executes a tool, it passes through a Vorim gate and emits\n// a signed audit event. This module reuses the LangChain tool wrappers (a\n// LangGraph tool IS a LangChain tool) and tags events with framework\n// \"langgraph\" so your audit trail names the graph correctly.\n//\n// Peer dependency: @langchain/core >=0.3.0 (and @langchain/langgraph to build\n// the graph itself — Vorim does not need it directly).\n//\n// Usage:\n// import { ToolNode } from '@langchain/langgraph/prebuilt';\n// import createVorim from '@vorim/sdk';\n// import { wrapGraphTools } from '@vorim/sdk/integrations/langgraph';\n//\n// const vorim = createVorim({ apiKey: 'agid_sk_live_...' });\n// const guarded = wrapGraphTools([searchTool, writeTool], {\n// vorim, agentId: 'agid_acme_a1b2c3d4',\n// permissionMap: { writeTool: 'agent:write' },\n// });\n// const toolNode = new ToolNode(guarded); // drop into your StateGraph\n// ============================================================================\n\nimport { wrapTool, wrapTools, type VorimLangChainConfig } from './langchain.js';\n\n/** Config for the LangGraph wrappers (same shape as the LangChain config). */\nexport type VorimLangGraphConfig = VorimLangChainConfig;\n\n/**\n * Wrap a single tool used inside a LangGraph node. Each execution is gated by\n * a Vorim permission (or runtime-control) check and recorded in the signed\n * audit trail under framework \"langgraph\". A denied call throws so the graph\n * records the tool error.\n */\nexport function wrapGraphTool<T>(tool: T, config: VorimLangGraphConfig): T {\n return wrapTool(tool as any, withFramework(config)) as T;\n}\n\n/**\n * Wrap the array of tools you hand to a ToolNode / prebuilt ReAct agent.\n * Returns the same tools, each guarded.\n */\nexport function wrapGraphTools<T>(tools: T[], config: VorimLangGraphConfig): T[] {\n return wrapTools(tools as any[], withFramework(config)) as T[];\n}\n\n// Tag audit events as \"langgraph\" (the shared wrapper defaults to\n// 'langchain') so the audit trail names graph runs correctly, without\n// mutating the caller's config object.\nfunction withFramework(config: VorimLangGraphConfig): VorimLangGraphConfig {\n return { ...config, framework: config.framework ?? 'langgraph' };\n}\n"],"mappings":"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","names":["event"]}
|
|
1
|
+
{"version":3,"sources":["../../src/integrations/_runtime-gate.ts","../../src/replay.ts","../../src/integrations/langchain.ts","../../src/integrations/langgraph.ts"],"sourcesContent":["// ============================================================================\n// VORIM SDK — Shared runtime-gate helper for framework integrations\n//\n// All tool-wrapping integrations (Vercel, OpenAI, Anthropic, …) turn a\n// `beforeAction` runtime decision into a simple { allowed, reason, decisionId }\n// the wrapper can act on. The subtlety is the `escalate` verdict: it is NOT a\n// denial — it means a human must approve the action. Folding it into\n// `allowed=false` silently breaks every human-in-the-loop flow; folding it into\n// `allowed=true` is a fail-open security hole. So this helper resolves the\n// escalation explicitly, driven by the caller's `onEscalation` preference.\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { RuntimeDecision, PermissionScope } from '../types.js';\n\n/**\n * How a framework integration should treat a runtime `escalate` verdict.\n * - `wait` — block and poll {@link VorimSDK.waitForDecisionResolution} until a\n * human approves/denies (or the timeout elapses → deny). The correct\n * default for human-in-the-loop: an escalation means \"ask a human\".\n * - `deny` — treat escalate as a denial (fail closed without waiting).\n * - `allow` — treat escalate as allowed (fail OPEN — only for trusted/dev use).\n */\nexport type EscalationPolicy = 'wait' | 'deny' | 'allow';\n\n/**\n * How a framework integration should treat a transport-failure `fallback`\n * decision (the control plane was unreachable and the SDK's\n * `runtimeFailOpen` produced a synthetic `decision: 'fallback'`,\n * `isFallback: true`).\n * - `deny` — fail closed: a control-plane outage denies the tool call.\n * The correct default for a SECURITY gate the caller opted into\n * via `useRuntimeControl: true`.\n * - `allow` — fail open: let the action proceed when the policy plane is\n * down (matches the raw SDK `runtimeFailOpen` behaviour).\n */\nexport type TransportFailurePolicy = 'deny' | 'allow';\n\nexport interface RuntimeGateOptions {\n /** What to do on an `escalate` verdict. @default 'wait' */\n onEscalation?: EscalationPolicy;\n /** Timeout (ms) for `onEscalation: 'wait'`. @default 300000 (5 min) */\n escalationTimeoutMs?: number;\n /**\n * What to do when the control plane is unreachable and `beforeAction`\n * returns a synthetic `fallback` decision. @default 'deny'\n *\n * The gate fails CLOSED on a policy-plane outage by default: a user who\n * turned on `useRuntimeControl: true` wants live deny/escalate\n * enforcement, so an outage should not silently auto-allow. Set to\n * `'allow'` to keep the old fail-open behaviour.\n */\n onTransportFailure?: TransportFailurePolicy;\n}\n\nexport interface GateResult {\n allowed: boolean;\n reason?: string;\n decisionId?: string;\n}\n\n/**\n * True for verdicts that permit the action to proceed. `escalate` is handled\n * separately. `fallback` is NOT treated as an allow here — a transport-failure\n * fallback is resolved explicitly via `onTransportFailure` so a control-plane\n * outage can't silently auto-allow inside a security gate.\n */\nfunction isAllowVerdict(decision: RuntimeDecision['decision']): boolean {\n return decision === 'allow' || decision === 'modify';\n}\n\n/**\n * Run a `beforeAction` runtime decision and collapse it to a {@link GateResult},\n * resolving `escalate` per {@link RuntimeGateOptions.onEscalation}.\n *\n * Requires (for `onEscalation: 'wait'`) an API key with the `runtime:decide`\n * scope — the same scope `beforeAction` itself uses.\n */\nexport async function runtimeGate(\n vorim: VorimSDK,\n agentId: string,\n actionTarget: string,\n scope: PermissionScope,\n payload: Record<string, unknown> | undefined,\n opts: RuntimeGateOptions = {},\n): Promise<GateResult> {\n const onEscalation = opts.onEscalation ?? 'wait';\n const onTransportFailure = opts.onTransportFailure ?? 'deny';\n const d = await vorim.beforeAction(\n { agentId, actionType: 'tool_call', actionTarget, requiredScope: scope, payload },\n { throwOnDeny: false },\n );\n\n // Control-plane outage: beforeAction returned a synthetic fallback\n // (isFallback). Govern it by onTransportFailure (default 'deny') rather\n // than auto-allowing — the caller turned on runtime control for live\n // enforcement, so an outage should fail closed unless they opt out.\n if (d.isFallback || d.decision === 'fallback') {\n if (onTransportFailure === 'allow') {\n return { allowed: true, reason: d.reason ?? 'control plane unreachable (fail-open)', decisionId: d.decisionId || undefined };\n }\n return { allowed: false, reason: d.reason ?? 'control plane unreachable (failed closed)', decisionId: d.decisionId || undefined };\n }\n\n if (d.decision !== 'escalate') {\n return { allowed: isAllowVerdict(d.decision), reason: d.reason, decisionId: d.decisionId || undefined };\n }\n\n // escalate ── a human must decide.\n if (onEscalation === 'allow') {\n return { allowed: true, reason: d.reason ?? 'escalated (auto-allowed)', decisionId: d.decisionId || undefined };\n }\n if (onEscalation === 'deny') {\n return { allowed: false, reason: d.reason ?? 'escalated (auto-denied — awaiting human)', decisionId: d.decisionId || undefined };\n }\n // 'wait' — poll for the human decision. On timeout, fail closed (deny).\n if (!d.decisionId) {\n return { allowed: false, reason: 'escalated but no decisionId to poll', decisionId: undefined };\n }\n try {\n const resolved = await vorim.waitForDecisionResolution(d.decisionId, { timeoutMs: opts.escalationTimeoutMs });\n return { allowed: isAllowVerdict(resolved.decision), reason: resolved.reason, decisionId: resolved.decisionId || d.decisionId };\n } catch {\n // ESCALATION_TIMEOUT (or any poll error) → fail closed.\n return { allowed: false, reason: 'escalation not resolved before timeout', decisionId: d.decisionId };\n }\n}\n","/**\n * Replayable agent decision evidence helpers.\n *\n * Canonical-form hashing for the VAIP -02 schema fields that the SDK\n * attaches to audit events. The hashes recorded in audit_events.tool_catalogue_hash\n * and audit_events.system_prompt_hash use these functions, so the bytes\n * an auditor or counterparty reconstructs must match what the SDK produced.\n *\n * These helpers are intentionally separate from the signing path. The\n * v0 canonical signature form (event_type|action|resource|input_hash|\n * output_hash|result) does NOT cover model_version, tool_catalogue_hash,\n * or system_prompt_hash. They will enter the canonical bytes in v1\n * (RFC 8785 JCS) in a follow-up release.\n *\n * Stable across SDK versions: the canonical-form version is documented\n * in CANONICAL_TOOL_CATALOGUE_VERSION. Future changes get a v2 etc;\n * never edit the existing v1 logic, or already-recorded hashes lose\n * their meaning.\n */\n\n// ─── Versioning ───────────────────────────────────────────────────────────\n\n/**\n * Canonical-form version for tool catalogue hashes produced by this SDK.\n * Recorded in tool_catalogue_canon_version on the event metadata (when\n * the metadata field is used) so verifiers know which hash recipe to\n * reproduce. Increment ONLY if the algorithm changes in a way that\n * would change the hash for the same logical catalogue.\n */\nexport const CANONICAL_TOOL_CATALOGUE_VERSION = 'v1' as const;\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Minimum shape a tool needs for catalogue hashing. The framework\n * integrations adapt their native tool objects to this shape before\n * calling hashToolCatalogue.\n */\nexport interface CatalogueTool {\n /** The name the model sees and calls. Required. */\n name: string;\n /** Human-readable description shown to the model. Optional; absent ↔ empty string. */\n description?: string;\n /**\n * JSON Schema describing the tool's input parameters. Optional;\n * absent ↔ empty object `{}`. The schema gets RFC 8785 JCS-canonicalised\n * before hashing so semantically-equivalent variations (key order,\n * whitespace) produce the same hash.\n */\n schema?: Record<string, unknown> | null;\n}\n\n// ─── RFC 8785 JCS subset ──────────────────────────────────────────────────\n\n/**\n * RFC 8785 JSON Canonicalization Scheme, sufficient subset for tool\n * catalogue values.\n *\n * Rules:\n * - Object keys sorted lexicographically by UTF-16 code units (which\n * is what JS string comparison does naturally).\n * - No whitespace between tokens.\n * - Numbers: integers as integers, finite floats per ECMAScript\n * Number.prototype.toString. JCS forbids NaN and Infinity.\n * - Strings: JSON-escape using minimal set per RFC 8259 § 7.\n * - null, true, false, arrays: as JSON.stringify produces them, since\n * JSON.stringify already produces the canonical form for these.\n *\n * Not vendoring a full library because tool schemas don't carry\n * non-integer numbers in practice and the JS spec for Number.toString\n * happens to coincide with JCS § 3.2.2.2 for the integer case.\n */\nexport function jcsCanonicalise(value: unknown): string {\n if (value === null) return 'null';\n if (value === true) return 'true';\n if (value === false) return 'false';\n\n if (typeof value === 'number') {\n if (!Number.isFinite(value)) {\n throw new Error('jcsCanonicalise: NaN and Infinity are not JCS-valid');\n }\n // Fail closed on magnitudes where JS .toString() and CPython diverge, so TS\n // and Python sign byte-identical bytes (or both reject). JS switches\n // integer-valued floats to exponent form at |x| >= 1e21 (Python expands to\n // full digits); in [1e-7, 1e-4) JS keeps decimals while Python repr() uses\n // exponent form. Keeping both engines in lockstep preserves cross-SDK\n // signature verifiability.\n const abs = Math.abs(value);\n // Reject ranges where JS Number.toString() and CPython diverge: |x| >= 1e21,\n // |x| < 1e-4, and integer-valued |x| > 2^53 (JS shortest-round-trip vs\n // Python exact int expansion — they only coincide for \"round\" values there).\n if (value !== 0 && (abs >= 1e21 || abs < 1e-4 || (Number.isInteger(value) && abs > 2 ** 53))) {\n throw new Error(\n `jcsCanonicalise: numbers in the ranges where JS and Python formatting ` +\n `diverge (|x| >= 1e21, |x| < 1e-4, or integer |x| > 2^53) are not ` +\n `supported in signed metadata. Use a string instead of ${value}.`,\n );\n }\n // For integers in safe range and ordinary decimals, .toString() matches JCS\n // (modern JS engines use the shortest round-trip representation).\n return value.toString();\n }\n\n if (typeof value === 'string') {\n return JSON.stringify(value);\n }\n\n if (Array.isArray(value)) {\n return '[' + value.map(jcsCanonicalise).join(',') + ']';\n }\n\n if (typeof value === 'object') {\n const obj = value as Record<string, unknown>;\n // Filter undefined-valued fields, matching @vorim/verify and\n // @vorim/shared-types. Without this the SDK throws on { a: 1, b: undefined }\n // while the verifier silently drops b — a cross-module canonical-form\n // divergence that would break signature verification on such events.\n const keys = Object.keys(obj).filter(k => obj[k] !== undefined).sort();\n const parts = keys.map(k => JSON.stringify(k) + ':' + jcsCanonicalise(obj[k]));\n return '{' + parts.join(',') + '}';\n }\n\n // undefined, function, symbol, bigint — not JSON-representable\n throw new Error(`jcsCanonicalise: unsupported value type: ${typeof value}`);\n}\n\n// ─── SHA-256 ──────────────────────────────────────────────────────────────\n\nasync function sha256Hex(input: string | Uint8Array): Promise<string> {\n const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input;\n\n // Node.js Web Crypto (Node 18+) supports digest. Browser Web Crypto does too.\n // Fall back to node:crypto if Web Crypto is unavailable.\n const subtle = (globalThis as any).crypto?.subtle;\n if (subtle) {\n const buf = await subtle.digest('SHA-256', bytes);\n return Array.from(new Uint8Array(buf))\n .map(b => b.toString(16).padStart(2, '0'))\n .join('');\n }\n\n // Node fallback\n const nodeCrypto = await import('node:crypto');\n return nodeCrypto.createHash('sha256').update(bytes).digest('hex');\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Hash a single tool definition. Returns `sha256:<hex>`.\n *\n * Canonical form (v1):\n * JCS-canonicalised JSON of `{name, description, schema}` where\n * absent fields substitute `description: \"\"` and `schema: {}`.\n */\nexport async function hashTool(tool: CatalogueTool): Promise<string> {\n const normalised = {\n name: tool.name,\n description: tool.description ?? '',\n schema: tool.schema ?? {},\n };\n const hex = await sha256Hex(jcsCanonicalise(normalised));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash an entire tool catalogue. Returns `sha256:<hex>`.\n *\n * Reordering tools does NOT change the hash (tool hashes sorted\n * lexicographically before concatenation). Adding, removing, or\n * modifying a tool DOES change the hash.\n *\n * Per-tool hashing first means a verifier comparing two catalogue\n * hashes that differ can also be given the per-tool hashes to\n * identify which specific tool changed.\n */\nexport async function hashToolCatalogue(tools: CatalogueTool[]): Promise<string> {\n if (tools.length === 0) {\n // Empty catalogue has a deterministic, stable hash distinct from \"no field\"\n return `sha256:${await sha256Hex('[]')}`;\n }\n const perTool = await Promise.all(tools.map(hashTool));\n perTool.sort();\n const hex = await sha256Hex(perTool.join(''));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash a system prompt. Returns `sha256:<hex>`.\n *\n * The prompt is UTF-8 encoded and hashed verbatim — no normalisation.\n * If a caller wants to ignore whitespace or comment differences, they\n * should normalise before calling. The intent here is deterministic\n * reproducibility, not semantic equivalence.\n */\nexport async function hashSystemPrompt(prompt: string): Promise<string> {\n const hex = await sha256Hex(prompt);\n return `sha256:${hex}`;\n}\n\n/**\n * Convenience: hash the previous event's canonical bytes for use in\n * the prev_event_hash field of hash-chained ingest. Caller provides\n * the canonical bytes (use canonicalPayloadV0 from the main module).\n */\nexport async function hashPreviousEvent(canonicalBytes: string): Promise<string> {\n const hex = await sha256Hex(canonicalBytes);\n return `sha256:${hex}`;\n}\n\n// ─── Replay context — framework integration helper ────────────────────────\n\n/**\n * Raw inputs the integration captures from the framework. Set by the\n * integration's config; turned into hashes by {@link prepareReplayContext}.\n */\nexport interface ReplayInputs {\n /** Stable identifier for the model. E.g. `\"anthropic:claude-opus-4-8\"`. */\n modelVersion?: string;\n /** Tools available to the agent at call time. Hashed via {@link hashToolCatalogue}. */\n tools?: CatalogueTool[];\n /** System prompt active at call time. Hashed via {@link hashSystemPrompt}. */\n systemPrompt?: string;\n}\n\n/**\n * Pre-computed hashes ready to attach to audit events. The three keys\n * match the audit_events column names.\n */\nexport interface ReplayContext {\n model_version?: string;\n tool_catalogue_hash?: string;\n system_prompt_hash?: string;\n}\n\n/**\n * Compute replay context once from raw inputs. Use at integration\n * setup time so each emit can attach the hashes without re-hashing.\n *\n * Returns an object suitable for spreading into an AuditEventInput:\n * `await vorim.emit({ ...event, ...replayContext })`\n *\n * If a field is absent in the inputs, it is absent in the result\n * (not the empty string). That keeps the event lean.\n */\nexport async function prepareReplayContext(\n inputs: ReplayInputs,\n): Promise<ReplayContext> {\n const ctx: ReplayContext = {};\n if (inputs.modelVersion) ctx.model_version = inputs.modelVersion;\n if (inputs.tools) ctx.tool_catalogue_hash = await hashToolCatalogue(inputs.tools);\n if (inputs.systemPrompt) ctx.system_prompt_hash = await hashSystemPrompt(inputs.systemPrompt);\n return ctx;\n}\n","// ============================================================================\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';\nimport { runtimeGate, type EscalationPolicy, type TransportFailurePolicy } from './_runtime-gate.js';\nimport {\n prepareReplayContext,\n type ReplayInputs,\n type ReplayContext,\n type CatalogueTool,\n} from '../replay.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 * Use the full runtime-control decision API (`beforeAction`) instead of the\n * lightweight permission check. When true, every tool call is evaluated\n * against live policy rules (allow/deny/escalate) and the returned\n * `decisionId` is linked onto each audit event's `decision_id`. Requires the\n * runtime_control plan feature (Growth+). @default false\n */\n useRuntimeControl?: boolean;\n /**\n * What to do when a runtime decision returns `escalate`. Only applies when\n * `useRuntimeControl` is true. `'wait'` (default) blocks and polls until a\n * human approves/denies or the timeout elapses (→ deny); `'deny'` fails\n * closed; `'allow'` proceeds (fail open — trusted use only). @default 'wait'\n */\n onEscalation?: EscalationPolicy;\n /** Timeout (ms) for `onEscalation: 'wait'`. @default 300000 */\n escalationTimeoutMs?: number;\n /**\n * Policy when the runtime gate can't reach the control plane. `'deny'` fails\n * closed (secure default); `'allow'` fails open. @default 'deny'\n */\n onTransportFailure?: TransportFailurePolicy;\n /**\n * Framework name recorded on each audit event's metadata. Defaults to\n * 'langchain'. The LangGraph wrapper sets this to 'langgraph' so the audit\n * trail names the graph correctly while reusing this tool-wrapping logic.\n * @default 'langchain'\n */\n framework?: string;\n /**\n * Replayable agent decision evidence (VAIP -02). When provided, the\n * hashes of the model version, tool catalogue, and system prompt are\n * attached to every emitted audit event so an auditor can later\n * reproduce the agent's decision context.\n *\n * Hashes are computed once on first emit and cached for subsequent\n * emits in this config's lifetime.\n *\n * These fields are NOT covered by the v0 canonical signature form;\n * advisory only until v1 (RFC 8785 JCS) lands.\n */\n replay?: ReplayInputs;\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, replay, framework = 'langchain',\n useRuntimeControl = false, onEscalation, escalationTimeoutMs, onTransportFailure } = config;\n\n const originalCall = tool._call.bind(tool);\n const getReplayCtx = makeReplayContextGetter(replay);\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. Gate the tool call. With useRuntimeControl, run the full runtime\n // decision (beforeAction) and link its decisionId onto audit events;\n // otherwise use the lightweight permission check. Both fail closed on a\n // transport error rather than crashing the host tool loop (matches the\n // Python fail-closed gate and the openai/anthropic integrations).\n let allowed: boolean;\n let reason: string | undefined;\n let decisionId: string | undefined;\n if (useRuntimeControl) {\n try {\n const gateRes = await runtimeGate(vorim, agentId, tool.name, scope,\n arg as Record<string, unknown> | undefined,\n { onEscalation, escalationTimeoutMs, onTransportFailure });\n allowed = gateRes.allowed;\n reason = gateRes.reason;\n decisionId = gateRes.decisionId;\n } catch {\n allowed = false;\n reason = 'runtime gate unavailable (failed closed)';\n }\n } else {\n try {\n ({ allowed, reason } = await vorim.check(agentId, scope));\n } catch {\n allowed = false;\n reason = 'permission check unavailable (failed closed)';\n }\n }\n const replayCtx = await getReplayCtx();\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 ...(decisionId ? { decision_id: decisionId } : {}),\n metadata: { reason, framework },\n ...replayCtx,\n };\n await 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 ...(decisionId ? { decision_id: decisionId } : {}),\n metadata: { error: err instanceof Error ? err.message : String(err), framework },\n ...replayCtx,\n };\n await 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 ...(decisionId ? { decision_id: decisionId } : {}),\n metadata: { framework },\n ...replayCtx,\n };\n await emitAudit(vorim, event, asyncAudit);\n\n return result;\n };\n\n return tool;\n}\n\n/**\n * Lazy-cached replay context getter. The hashes are computed once on\n * first call and reused for subsequent calls in this closure's lifetime.\n * Returns an empty object when no `replay` config was provided so the\n * spread is a no-op.\n */\nfunction makeReplayContextGetter(replay: ReplayInputs | undefined): () => Promise<ReplayContext> {\n if (!replay) return async () => ({});\n let cached: Promise<ReplayContext> | null = null;\n return () => {\n if (!cached) cached = prepareReplayContext(replay);\n return cached;\n };\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 private getReplayCtx: () => Promise<ReplayContext>;\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 /**\n * @param vorim Vorim SDK instance.\n * @param agentId The Vorim agent_id whose actions this callback audits.\n * @param replay Optional replayable-evidence inputs. Same shape as\n * {@link VorimLangChainConfig.replay}; hashes are\n * computed once and attached to every audit event.\n */\n constructor(vorim: VorimSDK, agentId: string, replay?: ReplayInputs) {\n this.vorim = vorim;\n this.agentId = agentId;\n this.getReplayCtx = makeReplayContextGetter(replay);\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 const replayCtx = await this.getReplayCtx();\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 ...replayCtx,\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 const replayCtx = await this.getReplayCtx();\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 ...replayCtx,\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, replay,\n useRuntimeControl, onEscalation, escalationTimeoutMs, onTransportFailure } = 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\n // If the caller passed `replay.tools`, use those. Otherwise derive a\n // tool catalogue from the rawTools we're about to wrap so the\n // replayable-evidence story works automatically.\n const derivedReplay: ReplayInputs | undefined = replay\n ? { ...replay, tools: replay.tools ?? await deriveCatalogueFromLangChainTools(rawTools) }\n : { tools: await deriveCatalogueFromLangChainTools(rawTools) };\n\n const agentConfig: VorimLangChainConfig = {\n vorim, agentId, permissionMap, defaultPermission, asyncAudit, replay: derivedReplay,\n useRuntimeControl, onEscalation, escalationTimeoutMs, onTransportFailure,\n };\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, derivedReplay);\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): Promise<void> | void {\n if (async) {\n vorim.emit(event).catch(() => {});\n return;\n }\n // asyncAudit=false: return the awaitable so callers can ensure the audit\n // event is persisted before the process exits.\n return vorim.emit(event).then(() => undefined).catch(() => undefined);\n}\n\n/**\n * Convert LangChain tools to the catalogue shape used by hashToolCatalogue.\n *\n * LangChain JS tool schemas are usually a Zod schema. `JSON.stringify(zod)`\n * serialises the internal `_def` (or `{}`), which does NOT match the FULL\n * JSON Schema envelope the Python SDK produces via pydantic\n * `model_json_schema()`. That mismatch makes the same logical tool hash to a\n * different `tool_catalogue_hash` across SDKs, breaking cross-SDK replay\n * verification. To match Python we convert a Zod schema to JSON Schema first\n * (via the optional, hoisted `zod-to-json-schema`; the SDK stays zero-dep, so\n * if it isn't resolvable at runtime we fall back to the plain shape).\n */\nasync function deriveCatalogueFromLangChainTools(tools: LangChainTool[]): Promise<CatalogueTool[]> {\n // Resolve the optional converter once. Guarded so a missing module (the\n // zero-dep SDK case) degrades gracefully instead of throwing.\n type ZodToJsonSchemaFn = (schema: unknown) => Record<string, unknown>;\n let zodToJsonSchema: ZodToJsonSchemaFn | null = null;\n try {\n // Specifier built indirectly so TS doesn't try to resolve the optional\n // module's types at compile time (the SDK declares no dependency on it).\n const mod: any = await import(/* @vite-ignore */ ('zod-to-json' + '-schema'));\n zodToJsonSchema = (mod.zodToJsonSchema ?? mod.default) as ZodToJsonSchemaFn;\n } catch {\n zodToJsonSchema = null;\n }\n\n const isZodSchema = (v: unknown): boolean =>\n !!v && typeof v === 'object' && '_def' in (v as Record<string, unknown>);\n\n return tools.map(t => {\n let schema: Record<string, unknown> | null = null;\n const raw = t.schema as unknown;\n if (raw && typeof raw === 'object') {\n if (isZodSchema(raw) && zodToJsonSchema) {\n // Zod -> full JSON Schema envelope (matches Python model_json_schema()).\n try {\n schema = zodToJsonSchema(raw);\n } catch {\n schema = null;\n }\n } else {\n // Already plain JSON-serialisable JSON Schema, use it; else null.\n try {\n schema = JSON.parse(JSON.stringify(raw));\n } catch {\n schema = null;\n }\n }\n }\n return {\n name: t.name,\n description: t.description ?? '',\n schema,\n };\n });\n}\n","// ============================================================================\n// VORIM SDK — LangGraph Integration\n// LangGraph builds stateful agent graphs out of LangChain tools. The right\n// place to enforce identity, permissions, and audit is the tool boundary —\n// every time a node executes a tool, it passes through a Vorim gate and emits\n// a signed audit event. This module reuses the LangChain tool wrappers (a\n// LangGraph tool IS a LangChain tool) and tags events with framework\n// \"langgraph\" so your audit trail names the graph correctly.\n//\n// Peer dependency: @langchain/core >=0.3.0 (and @langchain/langgraph to build\n// the graph itself — Vorim does not need it directly).\n//\n// Usage:\n// import { ToolNode } from '@langchain/langgraph/prebuilt';\n// import createVorim from '@vorim/sdk';\n// import { wrapGraphTools } from '@vorim/sdk/integrations/langgraph';\n//\n// const vorim = createVorim({ apiKey: 'agid_sk_live_...' });\n// const guarded = wrapGraphTools([searchTool, writeTool], {\n// vorim, agentId: 'agid_acme_a1b2c3d4',\n// permissionMap: { writeTool: 'agent:write' },\n// });\n// const toolNode = new ToolNode(guarded); // drop into your StateGraph\n// ============================================================================\n\nimport { wrapTool, wrapTools, type VorimLangChainConfig } from './langchain.js';\n\n/** Config for the LangGraph wrappers (same shape as the LangChain config). */\nexport type VorimLangGraphConfig = VorimLangChainConfig;\n\n/**\n * Wrap a single tool used inside a LangGraph node. Each execution is gated by\n * a Vorim permission (or runtime-control) check and recorded in the signed\n * audit trail under framework \"langgraph\". A denied call throws so the graph\n * records the tool error.\n */\nexport function wrapGraphTool<T>(tool: T, config: VorimLangGraphConfig): T {\n return wrapTool(tool as any, withFramework(config)) as T;\n}\n\n/**\n * Wrap the array of tools you hand to a ToolNode / prebuilt ReAct agent.\n * Returns the same tools, each guarded.\n */\nexport function wrapGraphTools<T>(tools: T[], config: VorimLangGraphConfig): T[] {\n return wrapTools(tools as any[], withFramework(config)) as T[];\n}\n\n// Tag audit events as \"langgraph\" (the shared wrapper defaults to\n// 'langchain') so the audit trail names graph runs correctly, without\n// mutating the caller's config object.\nfunction withFramework(config: VorimLangGraphConfig): VorimLangGraphConfig {\n return { ...config, framework: config.framework ?? 'langgraph' };\n}\n"],"mappings":"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","names":["event"]}
|
|
@@ -37,6 +37,43 @@ __export(llamaindex_exports, {
|
|
|
37
37
|
});
|
|
38
38
|
module.exports = __toCommonJS(llamaindex_exports);
|
|
39
39
|
|
|
40
|
+
// src/integrations/_runtime-gate.ts
|
|
41
|
+
function isAllowVerdict(decision) {
|
|
42
|
+
return decision === "allow" || decision === "modify";
|
|
43
|
+
}
|
|
44
|
+
async function runtimeGate(vorim, agentId, actionTarget, scope, payload, opts = {}) {
|
|
45
|
+
const onEscalation = opts.onEscalation ?? "wait";
|
|
46
|
+
const onTransportFailure = opts.onTransportFailure ?? "deny";
|
|
47
|
+
const d = await vorim.beforeAction(
|
|
48
|
+
{ agentId, actionType: "tool_call", actionTarget, requiredScope: scope, payload },
|
|
49
|
+
{ throwOnDeny: false }
|
|
50
|
+
);
|
|
51
|
+
if (d.isFallback || d.decision === "fallback") {
|
|
52
|
+
if (onTransportFailure === "allow") {
|
|
53
|
+
return { allowed: true, reason: d.reason ?? "control plane unreachable (fail-open)", decisionId: d.decisionId || void 0 };
|
|
54
|
+
}
|
|
55
|
+
return { allowed: false, reason: d.reason ?? "control plane unreachable (failed closed)", decisionId: d.decisionId || void 0 };
|
|
56
|
+
}
|
|
57
|
+
if (d.decision !== "escalate") {
|
|
58
|
+
return { allowed: isAllowVerdict(d.decision), reason: d.reason, decisionId: d.decisionId || void 0 };
|
|
59
|
+
}
|
|
60
|
+
if (onEscalation === "allow") {
|
|
61
|
+
return { allowed: true, reason: d.reason ?? "escalated (auto-allowed)", decisionId: d.decisionId || void 0 };
|
|
62
|
+
}
|
|
63
|
+
if (onEscalation === "deny") {
|
|
64
|
+
return { allowed: false, reason: d.reason ?? "escalated (auto-denied \u2014 awaiting human)", decisionId: d.decisionId || void 0 };
|
|
65
|
+
}
|
|
66
|
+
if (!d.decisionId) {
|
|
67
|
+
return { allowed: false, reason: "escalated but no decisionId to poll", decisionId: void 0 };
|
|
68
|
+
}
|
|
69
|
+
try {
|
|
70
|
+
const resolved = await vorim.waitForDecisionResolution(d.decisionId, { timeoutMs: opts.escalationTimeoutMs });
|
|
71
|
+
return { allowed: isAllowVerdict(resolved.decision), reason: resolved.reason, decisionId: resolved.decisionId || d.decisionId };
|
|
72
|
+
} catch {
|
|
73
|
+
return { allowed: false, reason: "escalation not resolved before timeout", decisionId: d.decisionId };
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
40
77
|
// src/replay.ts
|
|
41
78
|
function jcsCanonicalise(value) {
|
|
42
79
|
if (value === null) return "null";
|
|
@@ -116,7 +153,11 @@ function wrapTool(tool, config) {
|
|
|
116
153
|
permissionMap = {},
|
|
117
154
|
defaultPermission = "agent:execute",
|
|
118
155
|
asyncAudit = true,
|
|
119
|
-
replay
|
|
156
|
+
replay,
|
|
157
|
+
useRuntimeControl = false,
|
|
158
|
+
onEscalation,
|
|
159
|
+
escalationTimeoutMs,
|
|
160
|
+
onTransportFailure
|
|
120
161
|
} = config;
|
|
121
162
|
const originalCall = tool.call.bind(tool);
|
|
122
163
|
const toolName = tool.metadata.name;
|
|
@@ -128,11 +169,31 @@ function wrapTool(tool, config) {
|
|
|
128
169
|
value: async function vorimGuardedCall(input) {
|
|
129
170
|
let allowed;
|
|
130
171
|
let reason;
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
172
|
+
let decisionId;
|
|
173
|
+
if (useRuntimeControl) {
|
|
174
|
+
try {
|
|
175
|
+
const gateRes = await runtimeGate(
|
|
176
|
+
vorim,
|
|
177
|
+
agentId,
|
|
178
|
+
toolName,
|
|
179
|
+
scope,
|
|
180
|
+
input,
|
|
181
|
+
{ onEscalation, escalationTimeoutMs, onTransportFailure }
|
|
182
|
+
);
|
|
183
|
+
allowed = gateRes.allowed;
|
|
184
|
+
reason = gateRes.reason;
|
|
185
|
+
decisionId = gateRes.decisionId;
|
|
186
|
+
} catch {
|
|
187
|
+
allowed = false;
|
|
188
|
+
reason = "runtime gate unavailable (failed closed)";
|
|
189
|
+
}
|
|
190
|
+
} else {
|
|
191
|
+
try {
|
|
192
|
+
({ allowed, reason } = await vorim.check(agentId, scope));
|
|
193
|
+
} catch {
|
|
194
|
+
allowed = false;
|
|
195
|
+
reason = "permission check unavailable (failed closed)";
|
|
196
|
+
}
|
|
136
197
|
}
|
|
137
198
|
const replayCtx = await getReplayCtx();
|
|
138
199
|
if (!allowed) {
|
|
@@ -143,6 +204,7 @@ function wrapTool(tool, config) {
|
|
|
143
204
|
resource: truncate(JSON.stringify(input), 500),
|
|
144
205
|
permission: scope,
|
|
145
206
|
result: "denied",
|
|
207
|
+
...decisionId ? { decision_id: decisionId } : {},
|
|
146
208
|
metadata: { reason, framework: "llamaindex" },
|
|
147
209
|
...replayCtx
|
|
148
210
|
};
|
|
@@ -165,6 +227,7 @@ function wrapTool(tool, config) {
|
|
|
165
227
|
result: "error",
|
|
166
228
|
latency_ms: Date.now() - start,
|
|
167
229
|
error_code: err instanceof Error ? err.name : "UNKNOWN",
|
|
230
|
+
...decisionId ? { decision_id: decisionId } : {},
|
|
168
231
|
metadata: {
|
|
169
232
|
error: err instanceof Error ? err.message : String(err),
|
|
170
233
|
framework: "llamaindex"
|
|
@@ -182,6 +245,7 @@ function wrapTool(tool, config) {
|
|
|
182
245
|
permission: scope,
|
|
183
246
|
result: "success",
|
|
184
247
|
latency_ms: Date.now() - start,
|
|
248
|
+
...decisionId ? { decision_id: decisionId } : {},
|
|
185
249
|
metadata: { framework: "llamaindex" },
|
|
186
250
|
...replayCtx
|
|
187
251
|
};
|
|
@@ -199,7 +263,21 @@ function wrapTools(tools, config) {
|
|
|
199
263
|
return tools.map((t) => wrapTool(t, config));
|
|
200
264
|
}
|
|
201
265
|
async function createVorimAgent(config) {
|
|
202
|
-
const {
|
|
266
|
+
const {
|
|
267
|
+
vorim,
|
|
268
|
+
name,
|
|
269
|
+
capabilities,
|
|
270
|
+
scopes,
|
|
271
|
+
description,
|
|
272
|
+
tools: rawTools,
|
|
273
|
+
permissionMap,
|
|
274
|
+
defaultPermission,
|
|
275
|
+
asyncAudit,
|
|
276
|
+
useRuntimeControl,
|
|
277
|
+
onEscalation,
|
|
278
|
+
escalationTimeoutMs,
|
|
279
|
+
onTransportFailure
|
|
280
|
+
} = config;
|
|
203
281
|
const registration = await vorim.register({
|
|
204
282
|
name,
|
|
205
283
|
description,
|
|
@@ -207,7 +285,17 @@ async function createVorimAgent(config) {
|
|
|
207
285
|
scopes
|
|
208
286
|
});
|
|
209
287
|
const agentId = registration.agent.agent_id;
|
|
210
|
-
const toolConfig = {
|
|
288
|
+
const toolConfig = {
|
|
289
|
+
vorim,
|
|
290
|
+
agentId,
|
|
291
|
+
permissionMap,
|
|
292
|
+
defaultPermission,
|
|
293
|
+
asyncAudit,
|
|
294
|
+
useRuntimeControl,
|
|
295
|
+
onEscalation,
|
|
296
|
+
escalationTimeoutMs,
|
|
297
|
+
onTransportFailure
|
|
298
|
+
};
|
|
211
299
|
const tools = wrapTools(rawTools, toolConfig);
|
|
212
300
|
return {
|
|
213
301
|
/** The Vorim agent_id. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/integrations/llamaindex.ts","../../src/replay.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';\nimport {\n prepareReplayContext,\n type ReplayInputs,\n type ReplayContext,\n type CatalogueTool,\n} from '../replay.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 * Replayable agent decision evidence (VAIP -02). Hashes attached to\n * every audit event the wrapper emits. Not covered by v0 canonical\n * signature form.\n */\n replay?: ReplayInputs;\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 replay,\n } = config;\n\n const originalCall = tool.call.bind(tool);\n const toolName = tool.metadata.name;\n const scope = permissionMap[toolName] ?? defaultPermission;\n const getReplayCtx = makeReplayContextGetter(replay);\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 — fail closed on a transport error rather than\n // crashing the host tool loop (matches the Python fail-closed gate).\n let allowed: boolean;\n let reason: string | undefined;\n try {\n ({ allowed, reason } = await vorim.check(agentId, scope));\n } catch {\n allowed = false;\n reason = 'permission check unavailable (failed closed)';\n }\n const replayCtx = await getReplayCtx();\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 ...replayCtx,\n };\n await 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 ...replayCtx,\n };\n await 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 ...replayCtx,\n };\n await 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): Promise<void> | void {\n if (async) {\n vorim.emit(event).catch(() => {});\n return;\n }\n // asyncAudit=false: return the awaitable so callers can ensure the audit\n // event is persisted before the process exits.\n return vorim.emit(event).then(() => undefined).catch(() => undefined);\n}\n\n/**\n * Lazy-cached replay context getter. Hashes computed once on first\n * call, reused thereafter. Returns empty object when no replay config\n * was given, so the spread is a no-op.\n */\nfunction makeReplayContextGetter(replay: ReplayInputs | undefined): () => Promise<ReplayContext> {\n if (!replay) return async () => ({});\n let cached: Promise<ReplayContext> | null = null;\n return () => {\n if (!cached) cached = prepareReplayContext(replay);\n return cached;\n };\n}\n","/**\n * Replayable agent decision evidence helpers.\n *\n * Canonical-form hashing for the VAIP -02 schema fields that the SDK\n * attaches to audit events. The hashes recorded in audit_events.tool_catalogue_hash\n * and audit_events.system_prompt_hash use these functions, so the bytes\n * an auditor or counterparty reconstructs must match what the SDK produced.\n *\n * These helpers are intentionally separate from the signing path. The\n * v0 canonical signature form (event_type|action|resource|input_hash|\n * output_hash|result) does NOT cover model_version, tool_catalogue_hash,\n * or system_prompt_hash. They will enter the canonical bytes in v1\n * (RFC 8785 JCS) in a follow-up release.\n *\n * Stable across SDK versions: the canonical-form version is documented\n * in CANONICAL_TOOL_CATALOGUE_VERSION. Future changes get a v2 etc;\n * never edit the existing v1 logic, or already-recorded hashes lose\n * their meaning.\n */\n\n// ─── Versioning ───────────────────────────────────────────────────────────\n\n/**\n * Canonical-form version for tool catalogue hashes produced by this SDK.\n * Recorded in tool_catalogue_canon_version on the event metadata (when\n * the metadata field is used) so verifiers know which hash recipe to\n * reproduce. Increment ONLY if the algorithm changes in a way that\n * would change the hash for the same logical catalogue.\n */\nexport const CANONICAL_TOOL_CATALOGUE_VERSION = 'v1' as const;\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Minimum shape a tool needs for catalogue hashing. The framework\n * integrations adapt their native tool objects to this shape before\n * calling hashToolCatalogue.\n */\nexport interface CatalogueTool {\n /** The name the model sees and calls. Required. */\n name: string;\n /** Human-readable description shown to the model. Optional; absent ↔ empty string. */\n description?: string;\n /**\n * JSON Schema describing the tool's input parameters. Optional;\n * absent ↔ empty object `{}`. The schema gets RFC 8785 JCS-canonicalised\n * before hashing so semantically-equivalent variations (key order,\n * whitespace) produce the same hash.\n */\n schema?: Record<string, unknown> | null;\n}\n\n// ─── RFC 8785 JCS subset ──────────────────────────────────────────────────\n\n/**\n * RFC 8785 JSON Canonicalization Scheme, sufficient subset for tool\n * catalogue values.\n *\n * Rules:\n * - Object keys sorted lexicographically by UTF-16 code units (which\n * is what JS string comparison does naturally).\n * - No whitespace between tokens.\n * - Numbers: integers as integers, finite floats per ECMAScript\n * Number.prototype.toString. JCS forbids NaN and Infinity.\n * - Strings: JSON-escape using minimal set per RFC 8259 § 7.\n * - null, true, false, arrays: as JSON.stringify produces them, since\n * JSON.stringify already produces the canonical form for these.\n *\n * Not vendoring a full library because tool schemas don't carry\n * non-integer numbers in practice and the JS spec for Number.toString\n * happens to coincide with JCS § 3.2.2.2 for the integer case.\n */\nexport function jcsCanonicalise(value: unknown): string {\n if (value === null) return 'null';\n if (value === true) return 'true';\n if (value === false) return 'false';\n\n if (typeof value === 'number') {\n if (!Number.isFinite(value)) {\n throw new Error('jcsCanonicalise: NaN and Infinity are not JCS-valid');\n }\n // Fail closed on magnitudes where JS .toString() and CPython diverge, so TS\n // and Python sign byte-identical bytes (or both reject). JS switches\n // integer-valued floats to exponent form at |x| >= 1e21 (Python expands to\n // full digits); in [1e-7, 1e-4) JS keeps decimals while Python repr() uses\n // exponent form. Keeping both engines in lockstep preserves cross-SDK\n // signature verifiability.\n const abs = Math.abs(value);\n // Reject ranges where JS Number.toString() and CPython diverge: |x| >= 1e21,\n // |x| < 1e-4, and integer-valued |x| > 2^53 (JS shortest-round-trip vs\n // Python exact int expansion — they only coincide for \"round\" values there).\n if (value !== 0 && (abs >= 1e21 || abs < 1e-4 || (Number.isInteger(value) && abs > 2 ** 53))) {\n throw new Error(\n `jcsCanonicalise: numbers in the ranges where JS and Python formatting ` +\n `diverge (|x| >= 1e21, |x| < 1e-4, or integer |x| > 2^53) are not ` +\n `supported in signed metadata. Use a string instead of ${value}.`,\n );\n }\n // For integers in safe range and ordinary decimals, .toString() matches JCS\n // (modern JS engines use the shortest round-trip representation).\n return value.toString();\n }\n\n if (typeof value === 'string') {\n return JSON.stringify(value);\n }\n\n if (Array.isArray(value)) {\n return '[' + value.map(jcsCanonicalise).join(',') + ']';\n }\n\n if (typeof value === 'object') {\n const obj = value as Record<string, unknown>;\n // Filter undefined-valued fields, matching @vorim/verify and\n // @vorim/shared-types. Without this the SDK throws on { a: 1, b: undefined }\n // while the verifier silently drops b — a cross-module canonical-form\n // divergence that would break signature verification on such events.\n const keys = Object.keys(obj).filter(k => obj[k] !== undefined).sort();\n const parts = keys.map(k => JSON.stringify(k) + ':' + jcsCanonicalise(obj[k]));\n return '{' + parts.join(',') + '}';\n }\n\n // undefined, function, symbol, bigint — not JSON-representable\n throw new Error(`jcsCanonicalise: unsupported value type: ${typeof value}`);\n}\n\n// ─── SHA-256 ──────────────────────────────────────────────────────────────\n\nasync function sha256Hex(input: string | Uint8Array): Promise<string> {\n const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input;\n\n // Node.js Web Crypto (Node 18+) supports digest. Browser Web Crypto does too.\n // Fall back to node:crypto if Web Crypto is unavailable.\n const subtle = (globalThis as any).crypto?.subtle;\n if (subtle) {\n const buf = await subtle.digest('SHA-256', bytes);\n return Array.from(new Uint8Array(buf))\n .map(b => b.toString(16).padStart(2, '0'))\n .join('');\n }\n\n // Node fallback\n const nodeCrypto = await import('node:crypto');\n return nodeCrypto.createHash('sha256').update(bytes).digest('hex');\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Hash a single tool definition. Returns `sha256:<hex>`.\n *\n * Canonical form (v1):\n * JCS-canonicalised JSON of `{name, description, schema}` where\n * absent fields substitute `description: \"\"` and `schema: {}`.\n */\nexport async function hashTool(tool: CatalogueTool): Promise<string> {\n const normalised = {\n name: tool.name,\n description: tool.description ?? '',\n schema: tool.schema ?? {},\n };\n const hex = await sha256Hex(jcsCanonicalise(normalised));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash an entire tool catalogue. Returns `sha256:<hex>`.\n *\n * Reordering tools does NOT change the hash (tool hashes sorted\n * lexicographically before concatenation). Adding, removing, or\n * modifying a tool DOES change the hash.\n *\n * Per-tool hashing first means a verifier comparing two catalogue\n * hashes that differ can also be given the per-tool hashes to\n * identify which specific tool changed.\n */\nexport async function hashToolCatalogue(tools: CatalogueTool[]): Promise<string> {\n if (tools.length === 0) {\n // Empty catalogue has a deterministic, stable hash distinct from \"no field\"\n return `sha256:${await sha256Hex('[]')}`;\n }\n const perTool = await Promise.all(tools.map(hashTool));\n perTool.sort();\n const hex = await sha256Hex(perTool.join(''));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash a system prompt. Returns `sha256:<hex>`.\n *\n * The prompt is UTF-8 encoded and hashed verbatim — no normalisation.\n * If a caller wants to ignore whitespace or comment differences, they\n * should normalise before calling. The intent here is deterministic\n * reproducibility, not semantic equivalence.\n */\nexport async function hashSystemPrompt(prompt: string): Promise<string> {\n const hex = await sha256Hex(prompt);\n return `sha256:${hex}`;\n}\n\n/**\n * Convenience: hash the previous event's canonical bytes for use in\n * the prev_event_hash field of hash-chained ingest. Caller provides\n * the canonical bytes (use canonicalPayloadV0 from the main module).\n */\nexport async function hashPreviousEvent(canonicalBytes: string): Promise<string> {\n const hex = await sha256Hex(canonicalBytes);\n return `sha256:${hex}`;\n}\n\n// ─── Replay context — framework integration helper ────────────────────────\n\n/**\n * Raw inputs the integration captures from the framework. Set by the\n * integration's config; turned into hashes by {@link prepareReplayContext}.\n */\nexport interface ReplayInputs {\n /** Stable identifier for the model. E.g. `\"anthropic:claude-opus-4-8\"`. */\n modelVersion?: string;\n /** Tools available to the agent at call time. Hashed via {@link hashToolCatalogue}. */\n tools?: CatalogueTool[];\n /** System prompt active at call time. Hashed via {@link hashSystemPrompt}. */\n systemPrompt?: string;\n}\n\n/**\n * Pre-computed hashes ready to attach to audit events. The three keys\n * match the audit_events column names.\n */\nexport interface ReplayContext {\n model_version?: string;\n tool_catalogue_hash?: string;\n system_prompt_hash?: string;\n}\n\n/**\n * Compute replay context once from raw inputs. Use at integration\n * setup time so each emit can attach the hashes without re-hashing.\n *\n * Returns an object suitable for spreading into an AuditEventInput:\n * `await vorim.emit({ ...event, ...replayContext })`\n *\n * If a field is absent in the inputs, it is absent in the result\n * (not the empty string). That keeps the event lean.\n */\nexport async function prepareReplayContext(\n inputs: ReplayInputs,\n): Promise<ReplayContext> {\n const ctx: ReplayContext = {};\n if (inputs.modelVersion) ctx.model_version = inputs.modelVersion;\n if (inputs.tools) ctx.tool_catalogue_hash = await hashToolCatalogue(inputs.tools);\n if (inputs.systemPrompt) ctx.system_prompt_hash = await hashSystemPrompt(inputs.systemPrompt);\n return ctx;\n}\n"],"mappings":"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","names":["event"]}
|
|
1
|
+
{"version":3,"sources":["../../src/integrations/llamaindex.ts","../../src/integrations/_runtime-gate.ts","../../src/replay.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';\nimport { runtimeGate, type EscalationPolicy, type TransportFailurePolicy } from './_runtime-gate.js';\nimport {\n prepareReplayContext,\n type ReplayInputs,\n type ReplayContext,\n type CatalogueTool,\n} from '../replay.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 * Use the full runtime-control decision API (`beforeAction`) instead of the\n * lightweight permission check. When true, each tool call is evaluated against\n * live policy rules (allow/deny/escalate) and the returned `decisionId` is\n * linked onto each audit event's `decision_id`. Requires the runtime_control\n * plan feature (Growth+). @default false\n */\n useRuntimeControl?: boolean;\n /**\n * What to do when a runtime decision returns `escalate`. Only applies when\n * `useRuntimeControl` is true. `'wait'` (default) blocks/polls until approved\n * or timeout (→ deny); `'deny'` fails closed; `'allow'` proceeds (fail open).\n * @default 'wait'\n */\n onEscalation?: EscalationPolicy;\n /** Timeout (ms) for `onEscalation: 'wait'`. @default 300000 */\n escalationTimeoutMs?: number;\n /**\n * Policy when the runtime gate can't reach the control plane. `'deny'` fails\n * closed (secure default); `'allow'` fails open. @default 'deny'\n */\n onTransportFailure?: TransportFailurePolicy;\n /**\n * Replayable agent decision evidence (VAIP -02). Hashes attached to\n * every audit event the wrapper emits. Not covered by v0 canonical\n * signature form.\n */\n replay?: ReplayInputs;\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 replay,\n useRuntimeControl = false, onEscalation, escalationTimeoutMs, onTransportFailure,\n } = config;\n\n const originalCall = tool.call.bind(tool);\n const toolName = tool.metadata.name;\n const scope = permissionMap[toolName] ?? defaultPermission;\n const getReplayCtx = makeReplayContextGetter(replay);\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. Gate the tool call. With useRuntimeControl, run the full runtime\n // decision (beforeAction) and link its decisionId onto audit events;\n // otherwise use the lightweight permission check. Both fail closed on a\n // transport error rather than crashing the host tool loop.\n let allowed: boolean;\n let reason: string | undefined;\n let decisionId: string | undefined;\n if (useRuntimeControl) {\n try {\n const gateRes = await runtimeGate(vorim, agentId, toolName, scope,\n input as Record<string, unknown> | undefined,\n { onEscalation, escalationTimeoutMs, onTransportFailure });\n allowed = gateRes.allowed;\n reason = gateRes.reason;\n decisionId = gateRes.decisionId;\n } catch {\n allowed = false;\n reason = 'runtime gate unavailable (failed closed)';\n }\n } else {\n try {\n ({ allowed, reason } = await vorim.check(agentId, scope));\n } catch {\n allowed = false;\n reason = 'permission check unavailable (failed closed)';\n }\n }\n const replayCtx = await getReplayCtx();\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 ...(decisionId ? { decision_id: decisionId } : {}),\n metadata: { reason, framework: 'llamaindex' },\n ...replayCtx,\n };\n await 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 ...(decisionId ? { decision_id: decisionId } : {}),\n metadata: {\n error: err instanceof Error ? err.message : String(err),\n framework: 'llamaindex',\n },\n ...replayCtx,\n };\n await 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 ...(decisionId ? { decision_id: decisionId } : {}),\n metadata: { framework: 'llamaindex' },\n ...replayCtx,\n };\n await 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,\n useRuntimeControl, onEscalation, escalationTimeoutMs, onTransportFailure } = 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 useRuntimeControl, onEscalation, escalationTimeoutMs, onTransportFailure };\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): Promise<void> | void {\n if (async) {\n vorim.emit(event).catch(() => {});\n return;\n }\n // asyncAudit=false: return the awaitable so callers can ensure the audit\n // event is persisted before the process exits.\n return vorim.emit(event).then(() => undefined).catch(() => undefined);\n}\n\n/**\n * Lazy-cached replay context getter. Hashes computed once on first\n * call, reused thereafter. Returns empty object when no replay config\n * was given, so the spread is a no-op.\n */\nfunction makeReplayContextGetter(replay: ReplayInputs | undefined): () => Promise<ReplayContext> {\n if (!replay) return async () => ({});\n let cached: Promise<ReplayContext> | null = null;\n return () => {\n if (!cached) cached = prepareReplayContext(replay);\n return cached;\n };\n}\n","// ============================================================================\n// VORIM SDK — Shared runtime-gate helper for framework integrations\n//\n// All tool-wrapping integrations (Vercel, OpenAI, Anthropic, …) turn a\n// `beforeAction` runtime decision into a simple { allowed, reason, decisionId }\n// the wrapper can act on. The subtlety is the `escalate` verdict: it is NOT a\n// denial — it means a human must approve the action. Folding it into\n// `allowed=false` silently breaks every human-in-the-loop flow; folding it into\n// `allowed=true` is a fail-open security hole. So this helper resolves the\n// escalation explicitly, driven by the caller's `onEscalation` preference.\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { RuntimeDecision, PermissionScope } from '../types.js';\n\n/**\n * How a framework integration should treat a runtime `escalate` verdict.\n * - `wait` — block and poll {@link VorimSDK.waitForDecisionResolution} until a\n * human approves/denies (or the timeout elapses → deny). The correct\n * default for human-in-the-loop: an escalation means \"ask a human\".\n * - `deny` — treat escalate as a denial (fail closed without waiting).\n * - `allow` — treat escalate as allowed (fail OPEN — only for trusted/dev use).\n */\nexport type EscalationPolicy = 'wait' | 'deny' | 'allow';\n\n/**\n * How a framework integration should treat a transport-failure `fallback`\n * decision (the control plane was unreachable and the SDK's\n * `runtimeFailOpen` produced a synthetic `decision: 'fallback'`,\n * `isFallback: true`).\n * - `deny` — fail closed: a control-plane outage denies the tool call.\n * The correct default for a SECURITY gate the caller opted into\n * via `useRuntimeControl: true`.\n * - `allow` — fail open: let the action proceed when the policy plane is\n * down (matches the raw SDK `runtimeFailOpen` behaviour).\n */\nexport type TransportFailurePolicy = 'deny' | 'allow';\n\nexport interface RuntimeGateOptions {\n /** What to do on an `escalate` verdict. @default 'wait' */\n onEscalation?: EscalationPolicy;\n /** Timeout (ms) for `onEscalation: 'wait'`. @default 300000 (5 min) */\n escalationTimeoutMs?: number;\n /**\n * What to do when the control plane is unreachable and `beforeAction`\n * returns a synthetic `fallback` decision. @default 'deny'\n *\n * The gate fails CLOSED on a policy-plane outage by default: a user who\n * turned on `useRuntimeControl: true` wants live deny/escalate\n * enforcement, so an outage should not silently auto-allow. Set to\n * `'allow'` to keep the old fail-open behaviour.\n */\n onTransportFailure?: TransportFailurePolicy;\n}\n\nexport interface GateResult {\n allowed: boolean;\n reason?: string;\n decisionId?: string;\n}\n\n/**\n * True for verdicts that permit the action to proceed. `escalate` is handled\n * separately. `fallback` is NOT treated as an allow here — a transport-failure\n * fallback is resolved explicitly via `onTransportFailure` so a control-plane\n * outage can't silently auto-allow inside a security gate.\n */\nfunction isAllowVerdict(decision: RuntimeDecision['decision']): boolean {\n return decision === 'allow' || decision === 'modify';\n}\n\n/**\n * Run a `beforeAction` runtime decision and collapse it to a {@link GateResult},\n * resolving `escalate` per {@link RuntimeGateOptions.onEscalation}.\n *\n * Requires (for `onEscalation: 'wait'`) an API key with the `runtime:decide`\n * scope — the same scope `beforeAction` itself uses.\n */\nexport async function runtimeGate(\n vorim: VorimSDK,\n agentId: string,\n actionTarget: string,\n scope: PermissionScope,\n payload: Record<string, unknown> | undefined,\n opts: RuntimeGateOptions = {},\n): Promise<GateResult> {\n const onEscalation = opts.onEscalation ?? 'wait';\n const onTransportFailure = opts.onTransportFailure ?? 'deny';\n const d = await vorim.beforeAction(\n { agentId, actionType: 'tool_call', actionTarget, requiredScope: scope, payload },\n { throwOnDeny: false },\n );\n\n // Control-plane outage: beforeAction returned a synthetic fallback\n // (isFallback). Govern it by onTransportFailure (default 'deny') rather\n // than auto-allowing — the caller turned on runtime control for live\n // enforcement, so an outage should fail closed unless they opt out.\n if (d.isFallback || d.decision === 'fallback') {\n if (onTransportFailure === 'allow') {\n return { allowed: true, reason: d.reason ?? 'control plane unreachable (fail-open)', decisionId: d.decisionId || undefined };\n }\n return { allowed: false, reason: d.reason ?? 'control plane unreachable (failed closed)', decisionId: d.decisionId || undefined };\n }\n\n if (d.decision !== 'escalate') {\n return { allowed: isAllowVerdict(d.decision), reason: d.reason, decisionId: d.decisionId || undefined };\n }\n\n // escalate ── a human must decide.\n if (onEscalation === 'allow') {\n return { allowed: true, reason: d.reason ?? 'escalated (auto-allowed)', decisionId: d.decisionId || undefined };\n }\n if (onEscalation === 'deny') {\n return { allowed: false, reason: d.reason ?? 'escalated (auto-denied — awaiting human)', decisionId: d.decisionId || undefined };\n }\n // 'wait' — poll for the human decision. On timeout, fail closed (deny).\n if (!d.decisionId) {\n return { allowed: false, reason: 'escalated but no decisionId to poll', decisionId: undefined };\n }\n try {\n const resolved = await vorim.waitForDecisionResolution(d.decisionId, { timeoutMs: opts.escalationTimeoutMs });\n return { allowed: isAllowVerdict(resolved.decision), reason: resolved.reason, decisionId: resolved.decisionId || d.decisionId };\n } catch {\n // ESCALATION_TIMEOUT (or any poll error) → fail closed.\n return { allowed: false, reason: 'escalation not resolved before timeout', decisionId: d.decisionId };\n }\n}\n","/**\n * Replayable agent decision evidence helpers.\n *\n * Canonical-form hashing for the VAIP -02 schema fields that the SDK\n * attaches to audit events. The hashes recorded in audit_events.tool_catalogue_hash\n * and audit_events.system_prompt_hash use these functions, so the bytes\n * an auditor or counterparty reconstructs must match what the SDK produced.\n *\n * These helpers are intentionally separate from the signing path. The\n * v0 canonical signature form (event_type|action|resource|input_hash|\n * output_hash|result) does NOT cover model_version, tool_catalogue_hash,\n * or system_prompt_hash. They will enter the canonical bytes in v1\n * (RFC 8785 JCS) in a follow-up release.\n *\n * Stable across SDK versions: the canonical-form version is documented\n * in CANONICAL_TOOL_CATALOGUE_VERSION. Future changes get a v2 etc;\n * never edit the existing v1 logic, or already-recorded hashes lose\n * their meaning.\n */\n\n// ─── Versioning ───────────────────────────────────────────────────────────\n\n/**\n * Canonical-form version for tool catalogue hashes produced by this SDK.\n * Recorded in tool_catalogue_canon_version on the event metadata (when\n * the metadata field is used) so verifiers know which hash recipe to\n * reproduce. Increment ONLY if the algorithm changes in a way that\n * would change the hash for the same logical catalogue.\n */\nexport const CANONICAL_TOOL_CATALOGUE_VERSION = 'v1' as const;\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Minimum shape a tool needs for catalogue hashing. The framework\n * integrations adapt their native tool objects to this shape before\n * calling hashToolCatalogue.\n */\nexport interface CatalogueTool {\n /** The name the model sees and calls. Required. */\n name: string;\n /** Human-readable description shown to the model. Optional; absent ↔ empty string. */\n description?: string;\n /**\n * JSON Schema describing the tool's input parameters. Optional;\n * absent ↔ empty object `{}`. The schema gets RFC 8785 JCS-canonicalised\n * before hashing so semantically-equivalent variations (key order,\n * whitespace) produce the same hash.\n */\n schema?: Record<string, unknown> | null;\n}\n\n// ─── RFC 8785 JCS subset ──────────────────────────────────────────────────\n\n/**\n * RFC 8785 JSON Canonicalization Scheme, sufficient subset for tool\n * catalogue values.\n *\n * Rules:\n * - Object keys sorted lexicographically by UTF-16 code units (which\n * is what JS string comparison does naturally).\n * - No whitespace between tokens.\n * - Numbers: integers as integers, finite floats per ECMAScript\n * Number.prototype.toString. JCS forbids NaN and Infinity.\n * - Strings: JSON-escape using minimal set per RFC 8259 § 7.\n * - null, true, false, arrays: as JSON.stringify produces them, since\n * JSON.stringify already produces the canonical form for these.\n *\n * Not vendoring a full library because tool schemas don't carry\n * non-integer numbers in practice and the JS spec for Number.toString\n * happens to coincide with JCS § 3.2.2.2 for the integer case.\n */\nexport function jcsCanonicalise(value: unknown): string {\n if (value === null) return 'null';\n if (value === true) return 'true';\n if (value === false) return 'false';\n\n if (typeof value === 'number') {\n if (!Number.isFinite(value)) {\n throw new Error('jcsCanonicalise: NaN and Infinity are not JCS-valid');\n }\n // Fail closed on magnitudes where JS .toString() and CPython diverge, so TS\n // and Python sign byte-identical bytes (or both reject). JS switches\n // integer-valued floats to exponent form at |x| >= 1e21 (Python expands to\n // full digits); in [1e-7, 1e-4) JS keeps decimals while Python repr() uses\n // exponent form. Keeping both engines in lockstep preserves cross-SDK\n // signature verifiability.\n const abs = Math.abs(value);\n // Reject ranges where JS Number.toString() and CPython diverge: |x| >= 1e21,\n // |x| < 1e-4, and integer-valued |x| > 2^53 (JS shortest-round-trip vs\n // Python exact int expansion — they only coincide for \"round\" values there).\n if (value !== 0 && (abs >= 1e21 || abs < 1e-4 || (Number.isInteger(value) && abs > 2 ** 53))) {\n throw new Error(\n `jcsCanonicalise: numbers in the ranges where JS and Python formatting ` +\n `diverge (|x| >= 1e21, |x| < 1e-4, or integer |x| > 2^53) are not ` +\n `supported in signed metadata. Use a string instead of ${value}.`,\n );\n }\n // For integers in safe range and ordinary decimals, .toString() matches JCS\n // (modern JS engines use the shortest round-trip representation).\n return value.toString();\n }\n\n if (typeof value === 'string') {\n return JSON.stringify(value);\n }\n\n if (Array.isArray(value)) {\n return '[' + value.map(jcsCanonicalise).join(',') + ']';\n }\n\n if (typeof value === 'object') {\n const obj = value as Record<string, unknown>;\n // Filter undefined-valued fields, matching @vorim/verify and\n // @vorim/shared-types. Without this the SDK throws on { a: 1, b: undefined }\n // while the verifier silently drops b — a cross-module canonical-form\n // divergence that would break signature verification on such events.\n const keys = Object.keys(obj).filter(k => obj[k] !== undefined).sort();\n const parts = keys.map(k => JSON.stringify(k) + ':' + jcsCanonicalise(obj[k]));\n return '{' + parts.join(',') + '}';\n }\n\n // undefined, function, symbol, bigint — not JSON-representable\n throw new Error(`jcsCanonicalise: unsupported value type: ${typeof value}`);\n}\n\n// ─── SHA-256 ──────────────────────────────────────────────────────────────\n\nasync function sha256Hex(input: string | Uint8Array): Promise<string> {\n const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input;\n\n // Node.js Web Crypto (Node 18+) supports digest. Browser Web Crypto does too.\n // Fall back to node:crypto if Web Crypto is unavailable.\n const subtle = (globalThis as any).crypto?.subtle;\n if (subtle) {\n const buf = await subtle.digest('SHA-256', bytes);\n return Array.from(new Uint8Array(buf))\n .map(b => b.toString(16).padStart(2, '0'))\n .join('');\n }\n\n // Node fallback\n const nodeCrypto = await import('node:crypto');\n return nodeCrypto.createHash('sha256').update(bytes).digest('hex');\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Hash a single tool definition. Returns `sha256:<hex>`.\n *\n * Canonical form (v1):\n * JCS-canonicalised JSON of `{name, description, schema}` where\n * absent fields substitute `description: \"\"` and `schema: {}`.\n */\nexport async function hashTool(tool: CatalogueTool): Promise<string> {\n const normalised = {\n name: tool.name,\n description: tool.description ?? '',\n schema: tool.schema ?? {},\n };\n const hex = await sha256Hex(jcsCanonicalise(normalised));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash an entire tool catalogue. Returns `sha256:<hex>`.\n *\n * Reordering tools does NOT change the hash (tool hashes sorted\n * lexicographically before concatenation). Adding, removing, or\n * modifying a tool DOES change the hash.\n *\n * Per-tool hashing first means a verifier comparing two catalogue\n * hashes that differ can also be given the per-tool hashes to\n * identify which specific tool changed.\n */\nexport async function hashToolCatalogue(tools: CatalogueTool[]): Promise<string> {\n if (tools.length === 0) {\n // Empty catalogue has a deterministic, stable hash distinct from \"no field\"\n return `sha256:${await sha256Hex('[]')}`;\n }\n const perTool = await Promise.all(tools.map(hashTool));\n perTool.sort();\n const hex = await sha256Hex(perTool.join(''));\n return `sha256:${hex}`;\n}\n\n/**\n * Hash a system prompt. Returns `sha256:<hex>`.\n *\n * The prompt is UTF-8 encoded and hashed verbatim — no normalisation.\n * If a caller wants to ignore whitespace or comment differences, they\n * should normalise before calling. The intent here is deterministic\n * reproducibility, not semantic equivalence.\n */\nexport async function hashSystemPrompt(prompt: string): Promise<string> {\n const hex = await sha256Hex(prompt);\n return `sha256:${hex}`;\n}\n\n/**\n * Convenience: hash the previous event's canonical bytes for use in\n * the prev_event_hash field of hash-chained ingest. Caller provides\n * the canonical bytes (use canonicalPayloadV0 from the main module).\n */\nexport async function hashPreviousEvent(canonicalBytes: string): Promise<string> {\n const hex = await sha256Hex(canonicalBytes);\n return `sha256:${hex}`;\n}\n\n// ─── Replay context — framework integration helper ────────────────────────\n\n/**\n * Raw inputs the integration captures from the framework. Set by the\n * integration's config; turned into hashes by {@link prepareReplayContext}.\n */\nexport interface ReplayInputs {\n /** Stable identifier for the model. E.g. `\"anthropic:claude-opus-4-8\"`. */\n modelVersion?: string;\n /** Tools available to the agent at call time. Hashed via {@link hashToolCatalogue}. */\n tools?: CatalogueTool[];\n /** System prompt active at call time. Hashed via {@link hashSystemPrompt}. */\n systemPrompt?: string;\n}\n\n/**\n * Pre-computed hashes ready to attach to audit events. The three keys\n * match the audit_events column names.\n */\nexport interface ReplayContext {\n model_version?: string;\n tool_catalogue_hash?: string;\n system_prompt_hash?: string;\n}\n\n/**\n * Compute replay context once from raw inputs. Use at integration\n * setup time so each emit can attach the hashes without re-hashing.\n *\n * Returns an object suitable for spreading into an AuditEventInput:\n * `await vorim.emit({ ...event, ...replayContext })`\n *\n * If a field is absent in the inputs, it is absent in the result\n * (not the empty string). That keeps the event lean.\n */\nexport async function prepareReplayContext(\n inputs: ReplayInputs,\n): Promise<ReplayContext> {\n const ctx: ReplayContext = {};\n if (inputs.modelVersion) ctx.model_version = inputs.modelVersion;\n if (inputs.tools) ctx.tool_catalogue_hash = await hashToolCatalogue(inputs.tools);\n if (inputs.systemPrompt) ctx.system_prompt_hash = await hashSystemPrompt(inputs.systemPrompt);\n return ctx;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmEA,SAAS,eAAe,UAAgD;AACtE,SAAO,aAAa,WAAW,aAAa;AAC9C;AASA,eAAsB,YACpB,OACA,SACA,cACA,OACA,SACA,OAA2B,CAAC,GACP;AACrB,QAAM,eAAe,KAAK,gBAAgB;AAC1C,QAAM,qBAAqB,KAAK,sBAAsB;AACtD,QAAM,IAAI,MAAM,MAAM;AAAA,IACpB,EAAE,SAAS,YAAY,aAAa,cAAc,eAAe,OAAO,QAAQ;AAAA,IAChF,EAAE,aAAa,MAAM;AAAA,EACvB;AAMA,MAAI,EAAE,cAAc,EAAE,aAAa,YAAY;AAC7C,QAAI,uBAAuB,SAAS;AAClC,aAAO,EAAE,SAAS,MAAM,QAAQ,EAAE,UAAU,yCAAyC,YAAY,EAAE,cAAc,OAAU;AAAA,IAC7H;AACA,WAAO,EAAE,SAAS,OAAO,QAAQ,EAAE,UAAU,6CAA6C,YAAY,EAAE,cAAc,OAAU;AAAA,EAClI;AAEA,MAAI,EAAE,aAAa,YAAY;AAC7B,WAAO,EAAE,SAAS,eAAe,EAAE,QAAQ,GAAG,QAAQ,EAAE,QAAQ,YAAY,EAAE,cAAc,OAAU;AAAA,EACxG;AAGA,MAAI,iBAAiB,SAAS;AAC5B,WAAO,EAAE,SAAS,MAAM,QAAQ,EAAE,UAAU,4BAA4B,YAAY,EAAE,cAAc,OAAU;AAAA,EAChH;AACA,MAAI,iBAAiB,QAAQ;AAC3B,WAAO,EAAE,SAAS,OAAO,QAAQ,EAAE,UAAU,iDAA4C,YAAY,EAAE,cAAc,OAAU;AAAA,EACjI;AAEA,MAAI,CAAC,EAAE,YAAY;AACjB,WAAO,EAAE,SAAS,OAAO,QAAQ,uCAAuC,YAAY,OAAU;AAAA,EAChG;AACA,MAAI;AACF,UAAM,WAAW,MAAM,MAAM,0BAA0B,EAAE,YAAY,EAAE,WAAW,KAAK,oBAAoB,CAAC;AAC5G,WAAO,EAAE,SAAS,eAAe,SAAS,QAAQ,GAAG,QAAQ,SAAS,QAAQ,YAAY,SAAS,cAAc,EAAE,WAAW;AAAA,EAChI,QAAQ;AAEN,WAAO,EAAE,SAAS,OAAO,QAAQ,0CAA0C,YAAY,EAAE,WAAW;AAAA,EACtG;AACF;;;ACtDO,SAAS,gBAAgB,OAAwB;AACtD,MAAI,UAAU,KAAM,QAAO;AAC3B,MAAI,UAAU,KAAM,QAAO;AAC3B,MAAI,UAAU,MAAO,QAAO;AAE5B,MAAI,OAAO,UAAU,UAAU;AAC7B,QAAI,CAAC,OAAO,SAAS,KAAK,GAAG;AAC3B,YAAM,IAAI,MAAM,qDAAqD;AAAA,IACvE;AAOA,UAAM,MAAM,KAAK,IAAI,KAAK;AAI1B,QAAI,UAAU,MAAM,OAAO,QAAQ,MAAM,QAAS,OAAO,UAAU,KAAK,KAAK,MAAM,KAAK,KAAM;AAC5F,YAAM,IAAI;AAAA,QACR,gMAEyD,KAAK;AAAA,MAChE;AAAA,IACF;AAGA,WAAO,MAAM,SAAS;AAAA,EACxB;AAEA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B;AAEA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,MAAM,MAAM,IAAI,eAAe,EAAE,KAAK,GAAG,IAAI;AAAA,EACtD;AAEA,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,MAAM;AAKZ,UAAM,OAAO,OAAO,KAAK,GAAG,EAAE,OAAO,OAAK,IAAI,CAAC,MAAM,MAAS,EAAE,KAAK;AACrE,UAAM,QAAQ,KAAK,IAAI,OAAK,KAAK,UAAU,CAAC,IAAI,MAAM,gBAAgB,IAAI,CAAC,CAAC,CAAC;AAC7E,WAAO,MAAM,MAAM,KAAK,GAAG,IAAI;AAAA,EACjC;AAGA,QAAM,IAAI,MAAM,4CAA4C,OAAO,KAAK,EAAE;AAC5E;AAIA,eAAe,UAAU,OAA6C;AACpE,QAAM,QAAQ,OAAO,UAAU,WAAW,IAAI,YAAY,EAAE,OAAO,KAAK,IAAI;AAI5E,QAAM,SAAU,WAAmB,QAAQ;AAC3C,MAAI,QAAQ;AACV,UAAM,MAAM,MAAM,OAAO,OAAO,WAAW,KAAK;AAChD,WAAO,MAAM,KAAK,IAAI,WAAW,GAAG,CAAC,EAClC,IAAI,OAAK,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EACxC,KAAK,EAAE;AAAA,EACZ;AAGA,QAAM,aAAa,MAAM,OAAO,QAAa;AAC7C,SAAO,WAAW,WAAW,QAAQ,EAAE,OAAO,KAAK,EAAE,OAAO,KAAK;AACnE;AAWA,eAAsB,SAAS,MAAsC;AACnE,QAAM,aAAa;AAAA,IACjB,MAAM,KAAK;AAAA,IACX,aAAa,KAAK,eAAe;AAAA,IACjC,QAAQ,KAAK,UAAU,CAAC;AAAA,EAC1B;AACA,QAAM,MAAM,MAAM,UAAU,gBAAgB,UAAU,CAAC;AACvD,SAAO,UAAU,GAAG;AACtB;AAaA,eAAsB,kBAAkB,OAAyC;AAC/E,MAAI,MAAM,WAAW,GAAG;AAEtB,WAAO,UAAU,MAAM,UAAU,IAAI,CAAC;AAAA,EACxC;AACA,QAAM,UAAU,MAAM,QAAQ,IAAI,MAAM,IAAI,QAAQ,CAAC;AACrD,UAAQ,KAAK;AACb,QAAM,MAAM,MAAM,UAAU,QAAQ,KAAK,EAAE,CAAC;AAC5C,SAAO,UAAU,GAAG;AACtB;AAUA,eAAsB,iBAAiB,QAAiC;AACtE,QAAM,MAAM,MAAM,UAAU,MAAM;AAClC,SAAO,UAAU,GAAG;AACtB;AA+CA,eAAsB,qBACpB,QACwB;AACxB,QAAM,MAAqB,CAAC;AAC5B,MAAI,OAAO,aAAc,KAAI,gBAAgB,OAAO;AACpD,MAAI,OAAO,MAAO,KAAI,sBAAsB,MAAM,kBAAkB,OAAO,KAAK;AAChF,MAAI,OAAO,aAAc,KAAI,qBAAqB,MAAM,iBAAiB,OAAO,YAAY;AAC5F,SAAO;AACT;;;AF5IO,SAAS,SACd,MACA,QACG;AACH,QAAM;AAAA,IACJ;AAAA,IAAO;AAAA,IACP,gBAAgB,CAAC;AAAA,IACjB,oBAAoB;AAAA,IACpB,aAAa;AAAA,IACb;AAAA,IACA,oBAAoB;AAAA,IAAO;AAAA,IAAc;AAAA,IAAqB;AAAA,EAChE,IAAI;AAEJ,QAAM,eAAe,KAAK,KAAK,KAAK,IAAI;AACxC,QAAM,WAAW,KAAK,SAAS;AAC/B,QAAM,QAAQ,cAAc,QAAQ,KAAK;AACzC,QAAM,eAAe,wBAAwB,MAAM;AAInD,QAAM,UAAU,OAAO,OAAO,OAAO,eAAe,IAAI,GAAG;AAAA,IACzD,GAAG,OAAO,0BAA0B,IAAI;AAAA,IACxC,MAAM;AAAA,MACJ,OAAO,eAAe,iBAAiB,OAA0B;AAK/D,YAAI;AACJ,YAAI;AACJ,YAAI;AACJ,YAAI,mBAAmB;AACrB,cAAI;AACF,kBAAM,UAAU,MAAM;AAAA,cAAY;AAAA,cAAO;AAAA,cAAS;AAAA,cAAU;AAAA,cAC1D;AAAA,cACA,EAAE,cAAc,qBAAqB,mBAAmB;AAAA,YAAC;AAC3D,sBAAU,QAAQ;AAClB,qBAAS,QAAQ;AACjB,yBAAa,QAAQ;AAAA,UACvB,QAAQ;AACN,sBAAU;AACV,qBAAS;AAAA,UACX;AAAA,QACF,OAAO;AACL,cAAI;AACF,aAAC,EAAE,SAAS,OAAO,IAAI,MAAM,MAAM,MAAM,SAAS,KAAK;AAAA,UACzD,QAAQ;AACN,sBAAU;AACV,qBAAS;AAAA,UACX;AAAA,QACF;AACA,cAAM,YAAY,MAAM,aAAa;AAErC,YAAI,CAAC,SAAS;AACZ,gBAAMA,SAAyB;AAAA,YAC7B,UAAU;AAAA,YACV,YAAY;AAAA,YACZ,QAAQ;AAAA,YACR,UAAU,SAAS,KAAK,UAAU,KAAK,GAAG,GAAG;AAAA,YAC7C,YAAY;AAAA,YACZ,QAAQ;AAAA,YACR,GAAI,aAAa,EAAE,aAAa,WAAW,IAAI,CAAC;AAAA,YAChD,UAAU,EAAE,QAAQ,WAAW,aAAa;AAAA,YAC5C,GAAG;AAAA,UACL;AACA,gBAAM,UAAU,OAAOA,QAAO,UAAU;AACxC,gBAAM,IAAI;AAAA,YACR,iCAAiC,QAAQ,mBAAc,KAAK,IAAI,SAAS,KAAK,MAAM,KAAK,EAAE;AAAA,UAC7F;AAAA,QACF;AAGA,cAAM,QAAQ,KAAK,IAAI;AACvB,YAAI;AACJ,YAAI;AACF,mBAAS,MAAM,aAAa,KAAK;AAAA,QACnC,SAAS,KAAK;AACZ,gBAAMA,SAAyB;AAAA,YAC7B,UAAU;AAAA,YACV,YAAY;AAAA,YACZ,QAAQ;AAAA,YACR,UAAU,SAAS,KAAK,UAAU,KAAK,GAAG,GAAG;AAAA,YAC7C,YAAY;AAAA,YACZ,QAAQ;AAAA,YACR,YAAY,KAAK,IAAI,IAAI;AAAA,YACzB,YAAY,eAAe,QAAQ,IAAI,OAAO;AAAA,YAC9C,GAAI,aAAa,EAAE,aAAa,WAAW,IAAI,CAAC;AAAA,YAChD,UAAU;AAAA,cACR,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,cACtD,WAAW;AAAA,YACb;AAAA,YACA,GAAG;AAAA,UACL;AACA,gBAAM,UAAU,OAAOA,QAAO,UAAU;AACxC,gBAAM;AAAA,QACR;AAGA,cAAM,QAAyB;AAAA,UAC7B,UAAU;AAAA,UACV,YAAY;AAAA,UACZ,QAAQ;AAAA,UACR,UAAU,SAAS,KAAK,UAAU,KAAK,GAAG,GAAG;AAAA,UAC7C,YAAY;AAAA,UACZ,QAAQ;AAAA,UACR,YAAY,KAAK,IAAI,IAAI;AAAA,UACzB,GAAI,aAAa,EAAE,aAAa,WAAW,IAAI,CAAC;AAAA,UAChD,UAAU,EAAE,WAAW,aAAa;AAAA,UACpC,GAAG;AAAA,QACL;AACA,cAAM,UAAU,OAAO,OAAO,UAAU;AAExC,eAAO;AAAA,MACT;AAAA,MACA,UAAU;AAAA,MACV,cAAc;AAAA,MACd,YAAY;AAAA,IACd;AAAA,EACF,CAAC;AAED,SAAO;AACT;AAKO,SAAS,UACd,OACA,QACK;AACL,SAAO,MAAM,IAAI,OAAK,SAAS,GAAG,MAAM,CAAC;AAC3C;AA+CA,eAAsB,iBACpB,QACA;AACA,QAAM;AAAA,IAAE;AAAA,IAAO;AAAA,IAAM;AAAA,IAAc;AAAA,IAAQ;AAAA,IAAa,OAAO;AAAA,IAAU;AAAA,IAAe;AAAA,IAAmB;AAAA,IACzG;AAAA,IAAmB;AAAA,IAAc;AAAA,IAAqB;AAAA,EAAmB,IAAI;AAG/E,QAAM,eAAe,MAAM,MAAM,SAAS;AAAA,IACxC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,UAAU,aAAa,MAAM;AACnC,QAAM,aAAoC;AAAA,IAAE;AAAA,IAAO;AAAA,IAAS;AAAA,IAAe;AAAA,IAAmB;AAAA,IAC5F;AAAA,IAAmB;AAAA,IAAc;AAAA,IAAqB;AAAA,EAAmB;AAG3E,QAAM,QAAQ,UAAU,UAAU,UAAU;AAE5C,SAAO;AAAA;AAAA,IAEL;AAAA;AAAA,IAEA;AAAA;AAAA,IAEA;AAAA;AAAA,IAEA,YAAY,aAAa;AAAA,EAC3B;AACF;AAQA,eAAsB,oBACpB,OACA,SACA,OAQe;AACf,QAAM,MAAM,KAAK;AAAA,IACf,UAAU;AAAA,IACV,YAAY;AAAA,IACZ,QAAQ,MAAM;AAAA,IACd,UAAU,MAAM;AAAA,IAChB,QAAQ,MAAM;AAAA,IACd,YAAY,MAAM;AAAA,IAClB,YAAY,MAAM,QAAQ,qBAAqB;AAAA,IAC/C,UAAU;AAAA,MACR,WAAW;AAAA,MACX,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,MAAM,IAAI,CAAC;AAAA,MAC5C,GAAG,MAAM;AAAA,IACX;AAAA,EACF,CAAC;AACH;AAIA,SAAS,SAAS,KAAa,KAAqB;AAClD,SAAO,IAAI,SAAS,MAAM,IAAI,MAAM,GAAG,GAAG,IAAI,WAAM;AACtD;AAEA,SAAS,UAAU,OAAiB,OAAwB,OAAsC;AAChG,MAAI,OAAO;AACT,UAAM,KAAK,KAAK,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAChC;AAAA,EACF;AAGA,SAAO,MAAM,KAAK,KAAK,EAAE,KAAK,MAAM,MAAS,EAAE,MAAM,MAAM,MAAS;AACtE;AAOA,SAAS,wBAAwB,QAAgE;AAC/F,MAAI,CAAC,OAAQ,QAAO,aAAa,CAAC;AAClC,MAAI,SAAwC;AAC5C,SAAO,MAAM;AACX,QAAI,CAAC,OAAQ,UAAS,qBAAqB,MAAM;AACjD,WAAO;AAAA,EACT;AACF;","names":["event"]}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { P as PermissionScope, A as AgentRegistrationResult } from '../types-B22WnXEW.cjs';
|
|
2
2
|
import { VorimSDK, ReplayInputs } from '../index.cjs';
|
|
3
|
+
import { E as EscalationPolicy, T as TransportFailurePolicy } from '../_runtime-gate-DOJUKJBu.cjs';
|
|
3
4
|
|
|
4
5
|
/** Matches @llamaindex/core ToolMetadata */
|
|
5
6
|
interface ToolMetadata<P extends Record<string, unknown> = Record<string, unknown>> {
|
|
@@ -26,6 +27,28 @@ interface VorimLlamaIndexConfig {
|
|
|
26
27
|
defaultPermission?: PermissionScope;
|
|
27
28
|
/** Whether to emit audit events asynchronously (fire-and-forget). @default true */
|
|
28
29
|
asyncAudit?: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Use the full runtime-control decision API (`beforeAction`) instead of the
|
|
32
|
+
* lightweight permission check. When true, each tool call is evaluated against
|
|
33
|
+
* live policy rules (allow/deny/escalate) and the returned `decisionId` is
|
|
34
|
+
* linked onto each audit event's `decision_id`. Requires the runtime_control
|
|
35
|
+
* plan feature (Growth+). @default false
|
|
36
|
+
*/
|
|
37
|
+
useRuntimeControl?: boolean;
|
|
38
|
+
/**
|
|
39
|
+
* What to do when a runtime decision returns `escalate`. Only applies when
|
|
40
|
+
* `useRuntimeControl` is true. `'wait'` (default) blocks/polls until approved
|
|
41
|
+
* or timeout (→ deny); `'deny'` fails closed; `'allow'` proceeds (fail open).
|
|
42
|
+
* @default 'wait'
|
|
43
|
+
*/
|
|
44
|
+
onEscalation?: EscalationPolicy;
|
|
45
|
+
/** Timeout (ms) for `onEscalation: 'wait'`. @default 300000 */
|
|
46
|
+
escalationTimeoutMs?: number;
|
|
47
|
+
/**
|
|
48
|
+
* Policy when the runtime gate can't reach the control plane. `'deny'` fails
|
|
49
|
+
* closed (secure default); `'allow'` fails open. @default 'deny'
|
|
50
|
+
*/
|
|
51
|
+
onTransportFailure?: TransportFailurePolicy;
|
|
29
52
|
/**
|
|
30
53
|
* Replayable agent decision evidence (VAIP -02). Hashes attached to
|
|
31
54
|
* every audit event the wrapper emits. Not covered by v0 canonical
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { P as PermissionScope, A as AgentRegistrationResult } from '../types-B22WnXEW.js';
|
|
2
2
|
import { VorimSDK, ReplayInputs } from '../index.js';
|
|
3
|
+
import { E as EscalationPolicy, T as TransportFailurePolicy } from '../_runtime-gate-DOJUKJBu.js';
|
|
3
4
|
|
|
4
5
|
/** Matches @llamaindex/core ToolMetadata */
|
|
5
6
|
interface ToolMetadata<P extends Record<string, unknown> = Record<string, unknown>> {
|
|
@@ -26,6 +27,28 @@ interface VorimLlamaIndexConfig {
|
|
|
26
27
|
defaultPermission?: PermissionScope;
|
|
27
28
|
/** Whether to emit audit events asynchronously (fire-and-forget). @default true */
|
|
28
29
|
asyncAudit?: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Use the full runtime-control decision API (`beforeAction`) instead of the
|
|
32
|
+
* lightweight permission check. When true, each tool call is evaluated against
|
|
33
|
+
* live policy rules (allow/deny/escalate) and the returned `decisionId` is
|
|
34
|
+
* linked onto each audit event's `decision_id`. Requires the runtime_control
|
|
35
|
+
* plan feature (Growth+). @default false
|
|
36
|
+
*/
|
|
37
|
+
useRuntimeControl?: boolean;
|
|
38
|
+
/**
|
|
39
|
+
* What to do when a runtime decision returns `escalate`. Only applies when
|
|
40
|
+
* `useRuntimeControl` is true. `'wait'` (default) blocks/polls until approved
|
|
41
|
+
* or timeout (→ deny); `'deny'` fails closed; `'allow'` proceeds (fail open).
|
|
42
|
+
* @default 'wait'
|
|
43
|
+
*/
|
|
44
|
+
onEscalation?: EscalationPolicy;
|
|
45
|
+
/** Timeout (ms) for `onEscalation: 'wait'`. @default 300000 */
|
|
46
|
+
escalationTimeoutMs?: number;
|
|
47
|
+
/**
|
|
48
|
+
* Policy when the runtime gate can't reach the control plane. `'deny'` fails
|
|
49
|
+
* closed (secure default); `'allow'` fails open. @default 'deny'
|
|
50
|
+
*/
|
|
51
|
+
onTransportFailure?: TransportFailurePolicy;
|
|
29
52
|
/**
|
|
30
53
|
* Replayable agent decision evidence (VAIP -02). Hashes attached to
|
|
31
54
|
* every audit event the wrapper emits. Not covered by v0 canonical
|