arkna-sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,257 @@
+/**
+ * ARKNA SDK Client
+ *
+ * Core client for the ARKNA AI Trust Gateway.
+ * Zero runtime dependencies — uses Node 18+ built-in fetch.
+ */
+import type { ArknaConfig, ActionResult, ToolDefinition, HeartbeatResult, RegisterResult, GovernanceEnvelope, GatewayMessage, ExecuteOptions, HeartbeatHandle, DeclaredTool, StandingPermitSummary, ContextEntry, ExperienceEntry, RecallOptions, ContextBudgetOptions, GraphOptions, SemanticNode, WorkingMemoryContext, StartRunOptions, RunHandle, StepOptions, StepResult, ToolCallOptions, CompleteRunOptions, RunResult, CaptureContextOptions, SessionHandle, CloseSessionResult, StepInput, StepBatchResult } from './types';
+export declare class ArknaClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private agentId;
+    private toolsCache;
+    private toolsCacheTime;
+    private enforcementGuard;
+    private enforcementSecret;
+    private lastNonce;
+    private licenseManager;
+    private licenseFetched;
+    constructor(config?: ArknaConfig);
+    /** Whether HTTP enforcement is active (governed domain interception) */
+    get enforcementActive(): boolean;
+    /** Number of intercepted direct API calls since client creation */
+    get interceptedCalls(): number;
+    /** List available tools for this agent (cached 5 min). */
+    tools(forceRefresh?: boolean): Promise<ToolDefinition[]>;
+    /**
+     * 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
+     */
+    execute(toolName: string, parameters: Record<string, unknown>, opts?: ExecuteOptions): Promise<ActionResult>;
+    /** 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)
+     */
+    heartbeat(metadata?: Record<string, unknown>, tools?: DeclaredTool[]): Promise<HeartbeatResult>;
+    /**
+     * Collect system telemetry (CPU, memory). Returns empty object on failure.
+     * Used by startHeartbeat when enriched=true. Safe on all platforms.
+     */
+    private collectSystemTelemetry;
+    /**
+     * 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?: number, options?: {
+        enriched?: boolean;
+    }): HeartbeatHandle;
+    /**
+     * 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
+     */
+    register(name: string, platform: string, opts?: {
+        description?: string;
+        capabilities?: string[];
+        reply_url?: string;
+        metadata?: Record<string, unknown>;
+        tools?: DeclaredTool[];
+    }): Promise<RegisterResult>;
+    /**
+     * 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.
+     */
+    declareTools(tools: DeclaredTool[]): Promise<HeartbeatResult>;
+    /** Fetch the full governance envelope (tools, policies, permissions, constitution). */
+    governance(): Promise<GovernanceEnvelope>;
+    /**
+     * Listen for visitor messages via SSE.
+     * Calls the callback for each message event.
+     * Returns an AbortController to stop listening.
+     */
+    onMessage(callback: (msg: GatewayMessage) => void): AbortController;
+    /**
+     * Reply to a visitor message.
+     * @param messageId - The message_id from the SSE event
+     * @param content - Reply text content
+     */
+    reply(messageId: string, content: string): Promise<{
+        ok: boolean;
+        reply_id: string;
+    }>;
+    /** Poll for the result of a queued action (may return denied status). */
+    getActionStatus(requestId: string): Promise<ActionResult>;
+    /** Update agent settings (e.g. reply_url). */
+    updateAgent(settings: {
+        reply_url?: string | null;
+    }): Promise<{
+        ok: boolean;
+        agent_id: string;
+    }>;
+    /** Push an agent manifest (self-description, capabilities, tools). */
+    pushManifest(manifest: Record<string, unknown>): Promise<{
+        ok: boolean;
+        agent_id: string;
+        manifest_pushed_at: string;
+    }>;
+    /** List active standing permits for this agent. */
+    standingPermits(): Promise<{
+        agent_id: string;
+        standing_permits: StandingPermitSummary[];
+        count: number;
+    }>;
+    /** Agent context — experience log, semantic graph, working context. */
+    context: {
+        /** Store an experience log entry. */
+        store: (entry: ContextEntry) => Promise<{
+            id: string;
+            content_hash: string;
+        }>;
+        /** Recall experience log entries with optional filters. */
+        recall: (opts?: RecallOptions) => Promise<ExperienceEntry[]>;
+        /** Build working context (experience + semantic + shared). */
+        working: (opts?: ContextBudgetOptions) => Promise<WorkingMemoryContext>;
+        /** Query the semantic knowledge graph. */
+        graph: (opts?: GraphOptions) => Promise<SemanticNode[]>;
+        /** Share a semantic node with another agent. */
+        share: (nodeId: string, targetAgentId: string) => Promise<void>;
+    };
+    /** @deprecated Use client.context instead */
+    get memory(): {
+        /** Store an experience log entry. */
+        store: (entry: ContextEntry) => Promise<{
+            id: string;
+            content_hash: string;
+        }>;
+        /** Recall experience log entries with optional filters. */
+        recall: (opts?: RecallOptions) => Promise<ExperienceEntry[]>;
+        /** Build working context (experience + semantic + shared). */
+        working: (opts?: ContextBudgetOptions) => Promise<WorkingMemoryContext>;
+        /** Query the semantic knowledge graph. */
+        graph: (opts?: GraphOptions) => Promise<SemanticNode[]>;
+        /** Share a semantic node with another agent. */
+        share: (nodeId: string, targetAgentId: string) => Promise<void>;
+    };
+    /**
+     * Close a session explicitly.
+     * @param sessionId - The session ID to close
+     * @param status - 'completed' or 'abandoned'
+     * @returns CloseSessionResult with sessionId and status
+     */
+    closeSession(sessionId: string, status: 'completed' | 'abandoned'): Promise<CloseSessionResult>;
+    /**
+     * 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
+     */
+    recordStepBatch(runId: string, steps: StepInput[]): Promise<StepBatchResult>;
+    /**
+     * 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
+     */
+    waitForApproval(requestId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<ActionResult>;
+    /**
+     * Fetch the compiled license from the gateway. Called lazily on first execute.
+     * Non-fatal: if fetching fails, falls through to full pipeline.
+     */
+    fetchLicense(): Promise<void>;
+    /** Ensure we've attempted to fetch the license at least once. */
+    private ensureLicense;
+    /** Whether a status code is safe to retry */
+    private isRetryable;
+    /** Calculate retry delay with exponential backoff + jitter, respecting Retry-After */
+    private getRetryDelay;
+    /** Sleep helper */
+    private sleep;
+    /**
+     * Standard request — throws on non-2xx responses.
+     * Used for tools, heartbeat, register, governance, etc.
+     * Retries on transient errors (429, 5xx) with exponential backoff.
+     */
+    private request;
+    /**
+     * 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.
+     */
+    private requestRaw;
+    /**
+     * 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: string, signatureHeader: string, timestampHeader: string, secret: string, toleranceSeconds?: number): boolean;
+    /** Get the ingestion API base URL (derived from gateway URL) */
+    private get ingestionBaseUrl();
+    /**
+     * Convert camelCase keys to snake_case (shallow, one level deep).
+     * Leaves keys that are already snake_case unchanged.
+     */
+    private static camelToSnake;
+    /**
+     * Convert snake_case keys to camelCase (shallow, one level deep).
+     */
+    private static snakeToCamel;
+    /**
+     * Request to the ingestion API (/api/v1/...).
+     * Same retry/timeout logic as the gateway request method.
+     */
+    private ingestionRequest;
+    /** Start a new agent run. Returns a handle with the run ID. */
+    startRun(options?: StartRunOptions): Promise<RunHandle>;
+    /** Record a step within a run. */
+    recordStep(runId: string, options: StepOptions): Promise<StepResult>;
+    /** Record a tool call within a run. */
+    recordToolCall(runId: string, options: ToolCallOptions): Promise<{
+        toolCallId: string;
+    }>;
+    /** Complete or fail a run. */
+    completeRun(runId: string, options: CompleteRunOptions): Promise<RunResult>;
+    /** Capture a context snapshot for a run. */
+    captureContext(runId: string, options: CaptureContextOptions): Promise<{
+        contextPacketId: string;
+    }>;
+    /** Create a new session to group related runs. */
+    createSession(metadata?: Record<string, unknown>): Promise<SessionHandle>;
+    /**
+     * Convenience: trace a complete run with automatic lifecycle management.
+     * Starts a run, calls your function, records the result, completes the run.
+     */
+    trace<T>(name: string, fn: (run: {
+        runId: string;
+        step: (opts: StepOptions) => Promise<StepResult>;
+        tool: (opts: ToolCallOptions) => Promise<{
+            toolCallId: string;
+        }>;
+    }) => Promise<T>, options?: StartRunOptions): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}