arkna-sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,948 @@
+"use strict";
+/**
+ * ARKNA SDK Client
+ *
+ * Core client for the ARKNA AI Trust Gateway.
+ * Zero runtime dependencies — uses Node 18+ built-in fetch.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArknaClient = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const enforcement_1 = require("./enforcement");
+const license_1 = require("./license");
+/** Default request timeout (30s) */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Tools cache TTL (5 minutes) */
+const TOOLS_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Read .arkna/.env from current or parent directories.
+ * Returns parsed key-value pairs, or empty object if not found.
+ */
+function readArknaEnv(startDir) {
+    let dir = startDir || process.cwd();
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        const envPath = path.join(dir, '.arkna', '.env');
+        try {
+            const content = fs.readFileSync(envPath, 'utf-8');
+            const vars = {};
+            for (const line of content.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#'))
+                    continue;
+                const eqIdx = trimmed.indexOf('=');
+                if (eqIdx === -1)
+                    continue;
+                const key = trimmed.substring(0, eqIdx).trim();
+                let value = trimmed.substring(eqIdx + 1).trim();
+                // Strip surrounding quotes
+                if ((value.startsWith('"') && value.endsWith('"')) ||
+                    (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                vars[key] = value;
+            }
+            return vars;
+        }
+        catch {
+            // File not found — walk up
+        }
+        dir = path.dirname(dir);
+    }
+    return {};
+}
+/** Status codes that are safe to retry (transient server/rate-limit errors) */
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+class ArknaClient {
+    token;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    retryDelayMs;
+    agentId;
+    // Tools cache
+    toolsCache = null;
+    toolsCacheTime = 0;
+    // Enforcement guard (mandatory when governance.json exists)
+    enforcementGuard = null;
+    // Secret for nonce-based enforcement proof (generated per session)
+    enforcementSecret = '';
+    // Last nonce received from server (for enforcement proof)
+    lastNonce = null;
+    // Compiled license manager (V3: agent-side evaluation + stamp generation)
+    licenseManager = new license_1.LicenseManager();
+    licenseFetched = false;
+    constructor(config) {
+        // Resolution priority: explicit > .arkna/.env > env vars
+        const arknaEnv = readArknaEnv();
+        this.token = config?.token
+            || arknaEnv['ARKNA_TOKEN']
+            || process.env['ARKNA_TOKEN']
+            || '';
+        const rawUrl = config?.gatewayUrl
+            || arknaEnv['ARKNA_URL']
+            || process.env['ARKNA_URL']
+            || '';
+        // Normalize: strip trailing /api or /api/gateway and ensure /api/gateway
+        this.baseUrl = normalizeGatewayUrl(rawUrl);
+        this.agentId = config?.agentId
+            || arknaEnv['ARKNA_AGENT_ID']
+            || process.env['ARKNA_AGENT_ID']
+            || undefined;
+        this.timeoutMs = config?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = config?.maxRetries ?? 3;
+        this.retryDelayMs = config?.retryDelayMs ?? 500;
+        if (!this.token) {
+            throw new Error('ARKNA token not found. Set ARKNA_TOKEN env var, pass { token } to constructor, or run `arkna connect`.');
+        }
+        if (!this.baseUrl) {
+            throw new Error('ARKNA gateway URL not found. Set ARKNA_URL env var, pass { gatewayUrl } to constructor, or run `arkna connect`.');
+        }
+        // Enable enforcement — mandatory when governance contract exists.
+        // Patches fetch/http to intercept direct API calls to governed domains.
+        // Generates an enforcement secret used for nonce-based proof on heartbeats.
+        this.enforcementSecret = crypto.randomBytes(32).toString('hex');
+        try {
+            this.enforcementGuard = (0, enforcement_1.enableEnforcement)(this, {
+                mode: config?.enforcementMode,
+            });
+        }
+        catch {
+            // No governance.json found — enforcement not active.
+            // Compliance checker will detect this via missing heartbeat metadata.
+        }
+    }
+    /** Whether HTTP enforcement is active (governed domain interception) */
+    get enforcementActive() {
+        return this.enforcementGuard !== null && this.enforcementGuard.contract !== null;
+    }
+    /** Number of intercepted direct API calls since client creation */
+    get interceptedCalls() {
+        return this.enforcementGuard?.interceptedCalls ?? 0;
+    }
+    // ────────────────────────────────────────────────────────────
+    // Tools
+    // ────────────────────────────────────────────────────────────
+    /** List available tools for this agent (cached 5 min). */
+    async tools(forceRefresh = false) {
+        if (!forceRefresh && this.toolsCache && Date.now() - this.toolsCacheTime < TOOLS_CACHE_TTL_MS) {
+            return this.toolsCache;
+        }
+        const resp = await this.request('GET', '/tools');
+        this.toolsCache = resp.tools;
+        this.toolsCacheTime = Date.now();
+        return resp.tools;
+    }
+    // ────────────────────────────────────────────────────────────
+    // Execute
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Execute a tool through the ARKNA governance gateway.
+     *
+     * @param toolName - Tool identifier (e.g. 'send_email', 'check_calendly_availability')
+     * @param parameters - Tool input parameters
+     * @param opts - Optional: custom requestId, dryRun mode
+     * @returns ActionResult with decision, result, and signed permit
+     */
+    async execute(toolName, parameters, opts) {
+        const requestId = opts?.requestId || `req_${crypto.randomUUID().replace(/-/g, '').substring(0, 12)}`;
+        const body = {
+            tool: toolName,
+            parameters,
+            request_id: requestId,
+        };
+        if (opts?.dryRun) {
+            body.dry_run = true;
+        }
+        // ── Compiled License Fast Path ──
+        // If we have a valid license and the action is covered, generate a stamp
+        // and send it with the request. Gateway validates in <1ms instead of 100-400ms.
+        if (!opts?.dryRun) {
+            await this.ensureLicense();
+            if (this.licenseManager.isLicensed(toolName, parameters)) {
+                const stamp = this.licenseManager.generateStamp(toolName, parameters);
+                if (stamp) {
+                    return this.requestRaw('POST', '/actions', body, { 'X-Arkna-Stamp': stamp });
+                }
+            }
+        }
+        // POST /actions returns 200 (ALLOW), 202 (NEEDS_APPROVAL), or 403 (DENY).
+        // All three are valid governance decisions — not errors.
+        return this.requestRaw('POST', '/actions', body);
+    }
+    // ────────────────────────────────────────────────────────────
+    // Heartbeat
+    // ────────────────────────────────────────────────────────────
+    /** Send a single heartbeat. Returns kill switch status.
+     * Automatically includes enforcement metadata and cryptographic proof
+     * that enforcement is genuinely active (nonce-based, server-verified).
+     * @param metadata - Optional metadata to include
+     * @param tools - Updated tool declarations (synced on each heartbeat)
+     */
+    async heartbeat(metadata, tools) {
+        // Auto-enrich with enforcement telemetry
+        const enriched = { ...metadata };
+        enriched.enforcement_active = this.enforcementActive;
+        enriched.intercepted_calls = this.interceptedCalls;
+        enriched.sdk_version = '0.1.0';
+        if (this.enforcementGuard?.contract) {
+            enriched.enforcement_mode = this.enforcementGuard.contract.enforcement_mode;
+            enriched.contract_version = this.enforcementGuard.contract.version;
+            // Send contract signature prefix so backend can verify contract integrity
+            enriched.contract_signature_prefix = this.enforcementGuard.contract.signature.substring(0, 16);
+        }
+        // Nonce-based enforcement proof: proves enforcement is genuinely running.
+        // Both sides use SHA256(secret) as the HMAC key so the backend can verify.
+        const secretHash = crypto.createHash('sha256').update(this.enforcementSecret).digest('hex');
+        if (this.lastNonce && this.enforcementActive) {
+            enriched.enforcement_proof = crypto
+                .createHmac('sha256', secretHash)
+                .update(this.lastNonce)
+                .digest('hex');
+            enriched.enforcement_proof_nonce = this.lastNonce;
+        }
+        // Send the secret hash on first heartbeat so backend can verify future proofs
+        if (!this.lastNonce) {
+            enriched.enforcement_secret_hash = secretHash;
+        }
+        const body = { metadata: enriched };
+        if (tools) {
+            body.tools = tools;
+        }
+        const result = await this.request('POST', '/heartbeat', body);
+        // Store nonce from server for next heartbeat proof
+        if (result.enforcement_nonce) {
+            this.lastNonce = result.enforcement_nonce;
+        }
+        return result;
+    }
+    /**
+     * Collect system telemetry (CPU, memory). Returns empty object on failure.
+     * Used by startHeartbeat when enriched=true. Safe on all platforms.
+     */
+    collectSystemTelemetry() {
+        try {
+            const os = require('os');
+            const loadAvg = os.loadavg();
+            const totalMem = os.totalmem();
+            const freeMem = os.freemem();
+            return {
+                system: {
+                    load_1m: Math.round(loadAvg[0] * 100) / 100,
+                    load_5m: Math.round(loadAvg[1] * 100) / 100,
+                    load_15m: Math.round(loadAvg[2] * 100) / 100,
+                    memory_used_pct: Math.round((1 - freeMem / totalMem) * 100),
+                    memory_total_mb: Math.round(totalMem / (1024 * 1024)),
+                    platform: os.platform(),
+                    uptime_hours: Math.round(os.uptime() / 3600 * 10) / 10,
+                },
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Start a background heartbeat interval.
+     * @param intervalMs - Interval in ms (default: 60000 = 1 min)
+     * @param options.enriched - Include system telemetry (CPU, memory) in heartbeats
+     * @returns Handle with stop() method
+     */
+    startHeartbeat(intervalMs = 60_000, options) {
+        const enriched = options?.enriched ?? false;
+        const sendHeartbeat = () => {
+            const extra = enriched ? this.collectSystemTelemetry() : {};
+            this.heartbeat(extra).catch(() => {
+                // Heartbeat failures are non-critical
+            });
+        };
+        const id = setInterval(sendHeartbeat, intervalMs);
+        // Send first heartbeat immediately
+        sendHeartbeat();
+        return {
+            stop: () => clearInterval(id),
+        };
+    }
+    // ────────────────────────────────────────────────────────────
+    // Registration
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Register this agent with the ARKNA gateway.
+     * @param name - Agent display name
+     * @param platform - Agent platform (e.g. 'crewai', 'langchain', 'custom')
+     * @param opts - Optional: description, capabilities, reply_url, tools
+     */
+    async register(name, platform, opts) {
+        const body = {
+            name,
+            platform,
+            description: opts?.description,
+            capabilities: opts?.capabilities,
+            reply_url: opts?.reply_url,
+            metadata: opts?.metadata,
+        };
+        if (opts?.tools) {
+            body.tools = opts.tools;
+        }
+        const result = await this.request('POST', '/register', body);
+        // Store agent ID from registration
+        if (result.agent?.id) {
+            this.agentId = result.agent.id;
+        }
+        return result;
+    }
+    // ────────────────────────────────────────────────────────────
+    // Declared Tools
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Declare this agent's native tools for ARKNA governance tracking.
+     * Convenience method that sends a heartbeat with a tools declaration.
+     * ARKNA auto-classifies read-only tools and queues others for admin approval.
+     */
+    async declareTools(tools) {
+        return this.heartbeat(undefined, tools);
+    }
+    // ────────────────────────────────────────────────────────────
+    // Governance
+    // ────────────────────────────────────────────────────────────
+    /** Fetch the full governance envelope (tools, policies, permissions, constitution). */
+    async governance() {
+        return this.request('GET', '/governance');
+    }
+    // ────────────────────────────────────────────────────────────
+    // Messages (SSE + Reply)
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Listen for visitor messages via SSE.
+     * Calls the callback for each message event.
+     * Returns an AbortController to stop listening.
+     */
+    onMessage(callback) {
+        const controller = new AbortController();
+        const listen = async () => {
+            try {
+                const resp = await fetch(`${this.baseUrl}/messages/stream`, {
+                    headers: {
+                        'X-Integration-Token': this.token,
+                    },
+                    signal: controller.signal,
+                });
+                if (!resp.ok || !resp.body) {
+                    throw new Error(`SSE connection failed: ${resp.status}`);
+                }
+                const reader = resp.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                let currentEvent = '';
+                let dataLines = [];
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop() || '';
+                    for (const line of lines) {
+                        if (line.startsWith('event:')) {
+                            currentEvent = line.substring(6).trim();
+                        }
+                        else if (line.startsWith('data:')) {
+                            // SSE spec: accumulate multiple data: lines
+                            dataLines.push(line.substring(5).trim());
+                        }
+                        else if (line === '') {
+                            // Empty line = end of event. Dispatch accumulated data.
+                            if (dataLines.length > 0) {
+                                const dataStr = dataLines.join('\n');
+                                try {
+                                    const data = JSON.parse(dataStr);
+                                    callback({ event: currentEvent || 'message', data });
+                                }
+                                catch {
+                                    // Skip malformed JSON
+                                }
+                            }
+                            currentEvent = '';
+                            dataLines = [];
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof Error && err.name === 'AbortError')
+                    return;
+                // Reconnect after 5s on error
+                if (!controller.signal.aborted) {
+                    setTimeout(listen, 5000);
+                }
+            }
+        };
+        listen();
+        return controller;
+    }
+    /**
+     * Reply to a visitor message.
+     * @param messageId - The message_id from the SSE event
+     * @param content - Reply text content
+     */
+    async reply(messageId, content) {
+        return this.request('POST', `/messages/${messageId}/reply`, { content });
+    }
+    // ────────────────────────────────────────────────────────────
+    // Action Status Polling
+    // ────────────────────────────────────────────────────────────
+    /** Poll for the result of a queued action (may return denied status). */
+    async getActionStatus(requestId) {
+        return this.requestRaw('GET', `/actions/${requestId}`);
+    }
+    // ────────────────────────────────────────────────────────────
+    // Agent Settings
+    // ────────────────────────────────────────────────────────────
+    /** Update agent settings (e.g. reply_url). */
+    async updateAgent(settings) {
+        return this.request('PATCH', '/agent', settings);
+    }
+    /** Push an agent manifest (self-description, capabilities, tools). */
+    async pushManifest(manifest) {
+        return this.request('POST', '/manifest', manifest);
+    }
+    // ────────────────────────────────────────────────────────────
+    // Standing Permits
+    // ────────────────────────────────────────────────────────────
+    /** List active standing permits for this agent. */
+    async standingPermits() {
+        return this.request('GET', '/standing-permits');
+    }
+    // ────────────────────────────────────────────────────────────
+    // Agent Context (Adaptive Governance)
+    // ────────────────────────────────────────────────────────────
+    /** Agent context — experience log, semantic graph, working context. */
+    context = {
+        /** Store an experience log entry. */
+        store: async (entry) => {
+            return this.request('POST', '/context', entry);
+        },
+        /** Recall experience log entries with optional filters. */
+        recall: async (opts) => {
+            const params = new URLSearchParams();
+            if (opts?.type)
+                params.set('type', opts.type);
+            if (opts?.session)
+                params.set('session', opts.session);
+            if (opts?.since)
+                params.set('since', opts.since);
+            if (opts?.limit)
+                params.set('limit', String(opts.limit));
+            if (opts?.offset)
+                params.set('offset', String(opts.offset));
+            const qs = params.toString();
+            const result = await this.request('GET', `/context/recall${qs ? `?${qs}` : ''}`);
+            return result.episodes;
+        },
+        /** Build working context (experience + semantic + shared). */
+        working: async (opts) => {
+            const params = new URLSearchParams();
+            if (opts?.query)
+                params.set('query', opts.query);
+            if (opts?.max_tokens)
+                params.set('max_tokens', String(opts.max_tokens));
+            if (opts?.include_shared === false)
+                params.set('include_shared', 'false');
+            const qs = params.toString();
+            return this.request('GET', `/context/working${qs ? `?${qs}` : ''}`);
+        },
+        /** Query the semantic knowledge graph. */
+        graph: async (opts) => {
+            const params = new URLSearchParams();
+            if (opts?.query)
+                params.set('query', opts.query);
+            if (opts?.node_type)
+                params.set('node_type', opts.node_type);
+            if (opts?.limit)
+                params.set('limit', String(opts.limit));
+            const qs = params.toString();
+            const result = await this.request('GET', `/context/graph${qs ? `?${qs}` : ''}`);
+            return result.nodes;
+        },
+        /** Share a semantic node with another agent. */
+        share: async (nodeId, targetAgentId) => {
+            await this.request('POST', '/context/share', { node_id: nodeId, target_agent_id: targetAgentId });
+        },
+    };
+    /** @deprecated Use client.context instead */
+    get memory() { return this.context; }
+    // ────────────────────────────────────────────────────────────
+    // Session Management
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Close a session explicitly.
+     * @param sessionId - The session ID to close
+     * @param status - 'completed' or 'abandoned'
+     * @returns CloseSessionResult with sessionId and status
+     */
+    async closeSession(sessionId, status) {
+        const result = await this.ingestionRequest('PATCH', `/sessions/${sessionId}`, { status });
+        return { sessionId: result.session_id, status: result.status };
+    }
+    // ────────────────────────────────────────────────────────────
+    // Step Recording
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Record multiple steps in a single batch request.
+     * @param runId - The run ID to record steps for
+     * @param steps - Array of step inputs (max 100)
+     * @returns StepBatchResult with step IDs, sequences, and hashes
+     */
+    async recordStepBatch(runId, steps) {
+        return this.ingestionRequest('POST', `/runs/${runId}/steps/batch`, { steps });
+    }
+    // ────────────────────────────────────────────────────────────
+    // Approval Polling
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Wait for a queued action to be approved or denied.
+     * Polls getActionStatus with exponential backoff until resolved or timeout.
+     *
+     * @param requestId - The request_id from an execute() that returned NEEDS_APPROVAL
+     * @param opts - Optional: timeoutMs (default 300000 = 5 min), pollIntervalMs (default 2000)
+     * @returns The final ActionResult once resolved
+     * @throws Error if timeout is reached
+     */
+    async waitForApproval(requestId, opts) {
+        const timeoutMs = opts?.timeoutMs ?? 300_000;
+        const basePollMs = opts?.pollIntervalMs ?? 2_000;
+        const start = Date.now();
+        let attempt = 0;
+        while (Date.now() - start < timeoutMs) {
+            const result = await this.getActionStatus(requestId);
+            // Resolved: executed or denied
+            if (result.status === 'executed' || result.status === 'denied') {
+                return result;
+            }
+            // Still queued — backoff with cap
+            attempt++;
+            const delay = Math.min(basePollMs * Math.pow(1.5, attempt), 30_000);
+            await this.sleep(delay);
+        }
+        throw new Error(`Approval timeout: action ${requestId} not resolved within ${timeoutMs}ms`);
+    }
+    // ────────────────────────────────────────────────────────────
+    // License Management
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Fetch the compiled license from the gateway. Called lazily on first execute.
+     * Non-fatal: if fetching fails, falls through to full pipeline.
+     */
+    async fetchLicense() {
+        try {
+            const resp = await this.request('GET', '/license');
+            if (resp.license && resp.stamp_secret) {
+                this.licenseManager.setLicense(resp.license, resp.stamp_secret);
+            }
+            this.licenseFetched = true;
+        }
+        catch {
+            // Non-fatal — agent continues without license (full pipeline)
+            this.licenseFetched = true;
+        }
+    }
+    /** Ensure we've attempted to fetch the license at least once. */
+    async ensureLicense() {
+        if (!this.licenseFetched) {
+            await this.fetchLicense();
+        }
+    }
+    // ────────────────────────────────────────────────────────────
+    // Internal HTTP Helpers
+    // ────────────────────────────────────────────────────────────
+    /** Whether a status code is safe to retry */
+    isRetryable(status) {
+        return RETRYABLE_STATUSES.has(status);
+    }
+    /** Calculate retry delay with exponential backoff + jitter, respecting Retry-After */
+    getRetryDelay(attempt, retryAfterHeader) {
+        // Respect Retry-After header if present
+        if (retryAfterHeader) {
+            const retryAfterSec = parseInt(retryAfterHeader, 10);
+            if (!isNaN(retryAfterSec) && retryAfterSec > 0) {
+                return retryAfterSec * 1000;
+            }
+        }
+        // Exponential backoff: base * 2^attempt + jitter
+        const exponential = this.retryDelayMs * Math.pow(2, attempt);
+        const jitter = Math.random() * this.retryDelayMs;
+        return exponential + jitter;
+    }
+    /** Sleep helper */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Standard request — throws on non-2xx responses.
+     * Used for tools, heartbeat, register, governance, etc.
+     * Retries on transient errors (429, 5xx) with exponential backoff.
+     */
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            'X-Integration-Token': this.token,
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const resp = await fetch(url, {
+                    method,
+                    headers,
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                const json = await resp.json();
+                if (!resp.ok) {
+                    const errMsg = json.error
+                        || json.message
+                        || `HTTP ${resp.status}`;
+                    const err = new Error(errMsg);
+                    err.status = resp.status;
+                    err.body = json;
+                    // Retry on transient errors
+                    if (this.isRetryable(resp.status) && attempt < this.maxRetries) {
+                        lastError = err;
+                        const delay = this.getRetryDelay(attempt, resp.headers.get('retry-after'));
+                        await this.sleep(delay);
+                        continue;
+                    }
+                    throw err;
+                }
+                return json;
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                // Retry on timeout/network errors
+                if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TypeError') && attempt < this.maxRetries) {
+                    lastError = err;
+                    const delay = this.getRetryDelay(attempt);
+                    await this.sleep(delay);
+                    continue;
+                }
+                // Rethrow retryable errors with status (from above) or non-retryable errors
+                throw err;
+            }
+        }
+        // Should not reach here, but safety net
+        throw lastError || new Error('Request failed after retries');
+    }
+    /**
+     * Raw request — returns parsed JSON for ANY response with a JSON body.
+     * Used for execute() where 200 (ALLOW), 202 (NEEDS_APPROVAL), and 403 (DENY)
+     * are all valid governance decisions, not errors.
+     * Only throws on network/timeout errors or non-JSON responses.
+     * Retries on transient errors but NEVER retries governance decisions.
+     */
+    async requestRaw(method, path, body, extraHeaders) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            'X-Integration-Token': this.token,
+            ...extraHeaders,
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const resp = await fetch(url, {
+                    method,
+                    headers,
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                const json = await resp.json();
+                // 200 (ALLOW), 202 (NEEDS_APPROVAL), 403 (DENY) are all valid decisions — never retry
+                if (resp.status === 200 || resp.status === 202 || resp.status === 403) {
+                    return json;
+                }
+                // Other errors (400, 401, 429, 500) are real errors
+                const errMsg = json.error
+                    || json.message
+                    || `HTTP ${resp.status}`;
+                const err = new Error(errMsg);
+                err.status = resp.status;
+                err.body = json;
+                // Retry on transient errors
+                if (this.isRetryable(resp.status) && attempt < this.maxRetries) {
+                    lastError = err;
+                    const delay = this.getRetryDelay(attempt, resp.headers.get('retry-after'));
+                    await this.sleep(delay);
+                    continue;
+                }
+                throw err;
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                // Retry on timeout/network errors
+                if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TypeError') && attempt < this.maxRetries) {
+                    lastError = err;
+                    const delay = this.getRetryDelay(attempt);
+                    await this.sleep(delay);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastError || new Error('Request failed after retries');
+    }
+    // ────────────────────────────────────────────────────────────
+    // Webhook Signature Verification
+    // ────────────────────────────────────────────────────────────
+    /**
+     * Verify an ARKNA webhook signature.
+     *
+     * @param body - Raw request body string
+     * @param signatureHeader - Value of X-Arkna-Signature header (e.g. "v1=abc123...")
+     * @param timestampHeader - Value of X-Arkna-Timestamp header (epoch seconds)
+     * @param secret - Your webhook_secret (from token creation response)
+     * @param toleranceSeconds - Max age of the request in seconds (default: 300 = 5 min)
+     * @returns true if signature is valid and timestamp is within tolerance
+     */
+    static verifyWebhookSignature(body, signatureHeader, timestampHeader, secret, toleranceSeconds = 300) {
+        // Check timestamp freshness (replay protection)
+        const ts = parseInt(timestampHeader, 10);
+        if (isNaN(ts))
+            return false;
+        const now = Math.floor(Date.now() / 1000);
+        if (Math.abs(now - ts) > toleranceSeconds)
+            return false;
+        // Compute expected signature
+        const payload = `${timestampHeader}.${body}`;
+        const expected = crypto
+            .createHmac('sha256', secret)
+            .update(payload)
+            .digest('hex');
+        // Extract signature value (strip "v1=" prefix)
+        const sig = signatureHeader.startsWith('v1=')
+            ? signatureHeader.slice(3)
+            : signatureHeader;
+        // Constant-time comparison
+        try {
+            return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig, 'hex'));
+        }
+        catch {
+            return false;
+        }
+    }
+    // ────────────────────────────────────────────────────────────
+    // Observability — Run/Step/Tool Capture
+    // ────────────────────────────────────────────────────────────
+    /** Get the ingestion API base URL (derived from gateway URL) */
+    get ingestionBaseUrl() {
+        // baseUrl ends with /api/gateway — strip /gateway for /api, then append /v1
+        return this.baseUrl.replace(/\/gateway$/, '/v1');
+    }
+    /**
+     * Convert camelCase keys to snake_case (shallow, one level deep).
+     * Leaves keys that are already snake_case unchanged.
+     */
+    static camelToSnake(obj) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (value === undefined)
+                continue;
+            const snakeKey = key.replace(/[A-Z]/g, (ch) => '_' + ch.toLowerCase());
+            result[snakeKey] = value;
+        }
+        return result;
+    }
+    /**
+     * Convert snake_case keys to camelCase (shallow, one level deep).
+     */
+    static snakeToCamel(obj) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const camelKey = key.replace(/_([a-z])/g, (_, ch) => ch.toUpperCase());
+            result[camelKey] = value;
+        }
+        return result;
+    }
+    /**
+     * Request to the ingestion API (/api/v1/...).
+     * Same retry/timeout logic as the gateway request method.
+     */
+    async ingestionRequest(method, path, body) {
+        const url = `${this.ingestionBaseUrl}${path}`;
+        const headers = {
+            'X-Integration-Token': this.token,
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const resp = await fetch(url, {
+                    method,
+                    headers,
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                const json = await resp.json();
+                if (!resp.ok) {
+                    const errMsg = json.error
+                        || json.message
+                        || `HTTP ${resp.status}`;
+                    const err = new Error(errMsg);
+                    err.status = resp.status;
+                    err.body = json;
+                    if (this.isRetryable(resp.status) && attempt < this.maxRetries) {
+                        lastError = err;
+                        const delay = this.getRetryDelay(attempt, resp.headers.get('retry-after'));
+                        await this.sleep(delay);
+                        continue;
+                    }
+                    throw err;
+                }
+                return json;
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TypeError') && attempt < this.maxRetries) {
+                    lastError = err;
+                    const delay = this.getRetryDelay(attempt);
+                    await this.sleep(delay);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastError || new Error('Request failed after retries');
+    }
+    /** Start a new agent run. Returns a handle with the run ID. */
+    async startRun(options = {}) {
+        const opts = { triggerType: 'api', ...options };
+        const body = ArknaClient.camelToSnake(opts);
+        const resp = await this.ingestionRequest('POST', '/runs', body);
+        return ArknaClient.snakeToCamel(resp);
+    }
+    /** Record a step within a run. */
+    async recordStep(runId, options) {
+        const body = ArknaClient.camelToSnake(options);
+        const resp = await this.ingestionRequest('POST', `/runs/${runId}/steps`, body);
+        return ArknaClient.snakeToCamel(resp);
+    }
+    /** Record a tool call within a run. */
+    async recordToolCall(runId, options) {
+        const opts = { status: 'success', ...options };
+        const body = ArknaClient.camelToSnake(opts);
+        const resp = await this.ingestionRequest('POST', `/runs/${runId}/tools`, body);
+        return ArknaClient.snakeToCamel(resp);
+    }
+    /** Complete or fail a run. */
+    async completeRun(runId, options) {
+        const body = ArknaClient.camelToSnake(options);
+        const resp = await this.ingestionRequest('PATCH', `/runs/${runId}`, body);
+        return ArknaClient.snakeToCamel(resp);
+    }
+    /** Capture a context snapshot for a run. */
+    async captureContext(runId, options) {
+        const body = ArknaClient.camelToSnake(options);
+        const resp = await this.ingestionRequest('POST', `/runs/${runId}/context`, body);
+        return ArknaClient.snakeToCamel(resp);
+    }
+    /** Create a new session to group related runs. */
+    async createSession(metadata) {
+        const body = metadata ? { metadata } : {};
+        const resp = await this.ingestionRequest('POST', '/sessions', body);
+        return ArknaClient.snakeToCamel(resp);
+    }
+    /**
+     * Convenience: trace a complete run with automatic lifecycle management.
+     * Starts a run, calls your function, records the result, completes the run.
+     */
+    async trace(name, fn, options) {
+        const run = await this.startRun({ triggerType: 'api', ...options, input: name });
+        try {
+            const result = await fn({
+                runId: run.runId,
+                step: (opts) => this.recordStep(run.runId, opts),
+                tool: (opts) => this.recordToolCall(run.runId, opts),
+            });
+            await this.completeRun(run.runId, {
+                status: 'completed',
+                output: typeof result === 'string' ? result : JSON.stringify(result),
+            });
+            return result;
+        }
+        catch (error) {
+            await this.completeRun(run.runId, {
+                status: 'failed',
+                errorType: error.name || 'Error',
+                errorMessage: error.message,
+            }).catch(() => { });
+            throw error;
+        }
+    }
+}
+exports.ArknaClient = ArknaClient;
+// ────────────────────────────────────────────────────────────
+// URL normalization
+// ────────────────────────────────────────────────────────────
+function normalizeGatewayUrl(raw) {
+    if (!raw)
+        return '';
+    let url = raw.replace(/\/+$/, '');
+    // If it already ends with /api/gateway, use as-is
+    if (url.endsWith('/api/gateway'))
+        return url;
+    // If it ends with /api, append /gateway
+    if (url.endsWith('/api'))
+        return url + '/gateway';
+    // Otherwise append /api/gateway
+    return url + '/api/gateway';
+}
+//# sourceMappingURL=client.js.map