@sekuire/sdk 0.1.9 → 0.1.11

package/README.md

@@ -48,11 +48,75 @@ console.log(response);
 
 ## Features
 
-- ✅ **4 LLM Providers**: OpenAI, Anthropic, Google, Ollama
-- ✅ **Built-in Tools**: Calculator, Web Search, HTTP, File Operations
-- ✅ **Streaming**: Token-by-token responses
-- ✅ **Config-First**: Declarative YAML configuration
-- ✅ **Type-Safe**: Full TypeScript support
+- **4 LLM Providers**: OpenAI, Anthropic, Google, Ollama
+- **Built-in Tools**: Calculator, Web Search, HTTP, File Operations
+- **Streaming**: Token-by-token responses
+- **Config-First**: Declarative YAML configuration
+- **Type-Safe**: Full TypeScript support
+- **Beacon/Heartbeat**: Automatic registration and health reporting
+
+## Deployment Registration (Beacon)
+
+The SDK includes a Beacon system for registering deployed agents with Sekuire and sending periodic heartbeats.
+
+### Getting an Install Token
+
+Before deploying, generate an install token from the dashboard or CLI:
+
+**From Dashboard:**
+1. Go to your workspace
+2. Click "Install Agent"
+3. Generate an install token
+
+**From CLI:**
+```bash
+sekuire install token --workspace ws_xxxx --agent <agent_id>
+```
+
+### Using the SDK with Install Token
+
+Set the required environment variables:
+
+```bash
+export SEKUIRE_AGENT_ID="your-agent-sekuire-id"
+export SEKUIRE_INSTALL_TOKEN="skt_xxxx"  # From dashboard or CLI
+export SEKUIRE_API_URL="https://api.sekuire.ai"  # Optional, defaults to production
+```
+
+Then initialize the SDK:
+
+```typescript
+import { SekuireSDK } from '@sekuire/sdk';
+
+// Create SDK from environment variables (recommended)
+const sdk = SekuireSDK.fromEnv();
+
+// Or with explicit config
+const sdk = new SekuireSDK({
+  agentId: process.env.SEKUIRE_AGENT_ID,
+  installToken: process.env.SEKUIRE_INSTALL_TOKEN,
+  apiUrl: 'https://api.sekuire.ai',
+});
+
+// Start the SDK (bootstraps and begins heartbeat loop)
+await sdk.start();
+
+// Check connection status
+console.log('Connected:', sdk.isConnected());
+
+// Graceful shutdown
+await sdk.shutdown();
+```
+
+### Beacon Configuration Options
+
+| Option | Environment Variable | Description |
+|--------|---------------------|-------------|
+| `installToken` | `SEKUIRE_INSTALL_TOKEN` | Install token from dashboard/CLI (required) |
+| `agentId` | `SEKUIRE_AGENT_ID` | Your agent's sekuire_id (required) |
+| `apiUrl` | `SEKUIRE_API_URL` | API base URL (default: https://api.sekuire.ai) |
+| `heartbeatIntervalSeconds` | - | Heartbeat interval (default: 60) |
+| `capabilities` | - | List of capabilities this agent provides |
 
 ## API Reference
 

package/dist/a2a-client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A2A Protocol Client
+ *
+ * Client for interacting with A2A-compliant agents via the Sekuire API.
+ */
+import type { A2AMessage, A2ARouteRequest, A2ARouteResponse, A2ATask, AgentCard, TasksSendParams, TaskUpdateEvent } from "./types/a2a-types";
+export interface A2AClientOptions {
+    /** Base URL for the Sekuire API */
+    baseUrl: string;
+    /** Authentication token */
+    authToken: string;
+    /** Optional timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * A2A Protocol Client
+ *
+ * @example
+ * ```typescript
+ * const client = new A2AClient({
+ *   baseUrl: "https://api.sekuire.ai",
+ *   authToken: "your-token",
+ * });
+ *
+ * // Auto-discover and send task by skill
+ * const result = await client.sendBySkill({
+ *   skill: "document:summarize",
+ *   message: {
+ *     role: "user",
+ *     parts: [{ type: "text", text: "Summarize this document" }],
+ *   },
+ * });
+ *
+ * // Stream task updates
+ * for await (const event of client.subscribe(result.taskId)) {
+ *   console.log(event.status, event.artifacts);
+ * }
+ * ```
+ */
+export declare class A2AClient {
+    private baseUrl;
+    private authToken;
+    private timeout;
+    constructor(options: A2AClientOptions);
+    /**
+     * Send a task by skill using auto-discovery routing.
+     * The API will find an agent with the matching skill and forward the task.
+     */
+    sendBySkill(request: A2ARouteRequest): Promise<A2ARouteResponse>;
+    /**
+     * Send a message directly to a specific agent.
+     */
+    send(agentUrl: string, message: A2AMessage, taskId?: string): Promise<A2ATask>;
+    /**
+     * Send a task via JSON-RPC to the Sekuire API.
+     */
+    sendTask(params: TasksSendParams): Promise<A2ATask>;
+    /**
+     * Get task status and details.
+     */
+    getTask(taskId: string): Promise<A2ATask>;
+    /**
+     * Cancel a running task.
+     */
+    cancelTask(taskId: string): Promise<A2ATask>;
+    /**
+     * Subscribe to task updates via SSE.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.subscribe(taskId)) {
+     *   console.log(event.status);
+     *   if (event.status === "completed") break;
+     * }
+     * ```
+     */
+    subscribe(taskId: string): AsyncGenerator<TaskUpdateEvent>;
+    /**
+     * Get an agent's card (capabilities, skills).
+     */
+    getAgentCard(agentId: string): Promise<AgentCard>;
+    /**
+     * Make a JSON-RPC call to the A2A endpoint.
+     */
+    private jsonRpc;
+    private fetch;
+}
+/**
+ * A2A Protocol Error
+ */
+export declare class A2AError extends Error {
+    readonly code: string;
+    readonly jsonRpcCode?: number | undefined;
+    constructor(message: string, code: string, jsonRpcCode?: number | undefined);
+}

package/dist/a2a-delegator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A2A Task Delegator
+ *
+ * Enables agents to delegate tasks to other agents and receive completion callbacks.
+ * Provides a complete feedback loop for multi-agent orchestration.
+ */
+import type { A2AMessage, A2ATaskState, TaskUpdateEvent } from "./types/a2a-types";
+export interface DelegatorConfig {
+    apiUrl: string;
+    authToken: string;
+    workspaceId: string;
+    agentId: string;
+    timeout?: number;
+    pollInterval?: number;
+}
+export interface DelegationRequest {
+    skill: string;
+    message: string | A2AMessage;
+    contextId?: string;
+    parentTaskId?: string;
+    traceId?: string;
+    timeout?: number;
+    onProgress?: (event: TaskUpdateEvent) => void;
+}
+export interface DelegationResult {
+    taskId: string;
+    agentId: string;
+    traceId?: string;
+    status: A2ATaskState;
+    result?: A2AMessage;
+    artifacts?: Array<{
+        name?: string;
+        parts: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+    error?: string;
+    executionTimeMs: number;
+}
+export declare class A2ATaskDelegator {
+    private client;
+    private config;
+    private activeDelegations;
+    constructor(config: DelegatorConfig);
+    delegate(request: DelegationRequest): Promise<DelegationResult>;
+    delegateWithStreaming(request: DelegationRequest): AsyncGenerator<TaskUpdateEvent, DelegationResult>;
+    cancelDelegation(taskId: string): void;
+    cancelAllDelegations(): void;
+    discoverAgents(skill: string): Promise<Array<{
+        agentId: string;
+        name: string;
+    }>>;
+    private waitForCompletion;
+    private pollForCompletion;
+    private sleep;
+}
+export declare function createDelegator(config: DelegatorConfig): A2ATaskDelegator;

package/dist/a2a-server.d.ts

@@ -0,0 +1,84 @@
+/**
+ * A2A Protocol Server
+ *
+ * Server implementation for creating A2A-compliant agents with streaming support.
+ */
+import type { A2AArtifact, A2AMessage, A2ATask, A2ATaskState, AgentCard, AgentSkill, JsonRpcRequest, JsonRpcResponse, TaskUpdateEvent } from "./types/a2a-types";
+import { AgentIdentity } from "./identity";
+export interface A2AServerOptions {
+    card: AgentCard;
+    identity?: AgentIdentity;
+    port?: number;
+    handlers: Record<string, SkillHandler>;
+    streamingHandlers?: Record<string, StreamingSkillHandler>;
+}
+export type SkillHandler = (message: A2AMessage, context: SkillContext) => Promise<A2AMessage | A2AArtifact[]>;
+export type StreamingSkillHandler = (message: A2AMessage, context: StreamingSkillContext) => AsyncGenerator<StreamingUpdate>;
+export interface SkillContext {
+    taskId: string;
+    contextId?: string;
+    history: A2AMessage[];
+}
+export interface StreamingSkillContext extends SkillContext {
+    emit: (update: StreamingUpdate) => void;
+}
+export type StreamingUpdate = {
+    type: "progress";
+    message: string;
+    percent?: number;
+} | {
+    type: "artifact";
+    artifact: A2AArtifact;
+} | {
+    type: "message";
+    message: A2AMessage;
+} | {
+    type: "status";
+    status: A2ATaskState;
+};
+export interface TaskState {
+    id: string;
+    contextId?: string;
+    status: A2ATaskState;
+    history: A2AMessage[];
+    artifacts: A2AArtifact[];
+    createdAt: Date;
+    updatedAt: Date;
+    subscribers: Set<(event: TaskUpdateEvent) => void>;
+}
+export declare class A2AServer {
+    private card;
+    private identity?;
+    private handlers;
+    private streamingHandlers;
+    private tasks;
+    private heartbeatInterval?;
+    constructor(options: A2AServerOptions);
+    /**
+     * Start sending heartbeats to the registry
+     * @param publicUrl The public URL where this agent is reachable
+     * @param registryUrl The registry API base URL (default: http://localhost:3000)
+     */
+    startHeartbeat(publicUrl: string, registryUrl?: string): Promise<void>;
+    stopHeartbeat(): void;
+    getAgentCard(): AgentCard;
+    getTask(taskId: string): TaskState | undefined;
+    handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+    handleStreamingRequest(request: JsonRpcRequest): AsyncGenerator<TaskUpdateEvent>;
+    subscribeToTask(taskId: string): AsyncGenerator<TaskUpdateEvent> | null;
+    formatSSE(event: TaskUpdateEvent): string;
+    notifySubscribers(taskId: string): void;
+    private handleTasksSend;
+    private handleTasksGet;
+    private handleTasksCancel;
+    private findHandler;
+    private findStreamingHandler;
+    private findHandlerInMap;
+    private extractText;
+    private createUpdateEvent;
+    private taskToResponse;
+    private success;
+    private error;
+    private generateId;
+}
+export type { A2AArtifact, A2AMessage, A2ATask, AgentCard, AgentSkill, TaskUpdateEvent };

package/dist/agent.d.ts

@@ -30,7 +30,7 @@ export interface ToolDefinition<T extends z.ZodObject<any> = any> {
     /** Zod schema for input validation */
     schema: T;
     /** Tool execution function */
-    execute: (input: z.infer<T>) => Promise<any> | any;
+    execute: (input: z.infer<T>) => Promise<unknown> | unknown;
     /** Optional: Additional compliance checks */
     beforeExecute?: (input: z.infer<T>) => Promise<void> | void;
 }

package/dist/beacon.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Sekuire Beacon - Deployment Registration & Heartbeat
+ *
+ * Automatically registers the agent with Sekuire and sends periodic heartbeats
+ * to show online status in the Dashboard.
+ *
+ * Supports two authentication modes:
+ * 1. Install Token (recommended): Use an install token from the dashboard
+ * 2. API Key: Use an API key for SDK-initiated bootstrap (requires workspace)
+ */
+export interface BeaconConfig {
+    /** Sekuire Core API base URL */
+    apiBaseUrl: string;
+    /** Install token from dashboard (preferred for BYOC deployments) */
+    installToken?: string;
+    /** API key for authentication (reads from SEKUIRE_API_KEY if not set) */
+    apiKey?: string;
+    /** Agent ID to register */
+    agentId: string;
+    /** Workspace ID (required when using API key without install token) */
+    workspaceId?: string;
+    /** Heartbeat interval in seconds (default: 60) */
+    heartbeatIntervalSeconds?: number;
+    /** Optional explicit deployment URL (auto-detected if not set) */
+    deploymentUrl?: string;
+    /** Optional capabilities this agent provides */
+    capabilities?: string[];
+    /** Optional callback invoked on status changes */
+    onStatusChange?: (status: BeaconStatus) => void;
+}
+export interface BeaconStatus {
+    isRunning: boolean;
+    installationId?: string;
+    runtimeToken?: string;
+    deploymentUrl?: string;
+    lastHeartbeat?: Date;
+    failedHeartbeats: number;
+}
+export interface BootstrapResponse {
+    installation_id: string;
+    runtime_token: string;
+    refresh_token: string;
+    expires_at: string;
+    heartbeat_interval: number;
+}
+export declare class Beacon {
+    private config;
+    private intervalId;
+    private installationId;
+    private runtimeToken;
+    private refreshToken;
+    private lastHeartbeat;
+    private failedHeartbeats;
+    constructor(config: BeaconConfig);
+    /**
+     * Start the beacon - registers with Sekuire and begins heartbeat loop
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the beacon
+     */
+    stop(): void;
+    /**
+     * Get current beacon status
+     */
+    getStatus(): BeaconStatus;
+    /**
+     * Bootstrap registration with Sekuire
+     *
+     * Exchanges an install token for runtime credentials (installation_id + runtime_token).
+     * The install token is obtained from the dashboard or CLI.
+     */
+    private bootstrap;
+    /**
+     * Send heartbeat (lease renewal) to Sekuire
+     *
+     * Uses the installation-based lease endpoint with runtime token authentication.
+     */
+    private heartbeat;
+    /**
+     * Refresh the runtime token using the refresh token
+     */
+    private refreshRuntimeToken;
+    /**
+     * Notify status change callback
+     */
+    private notifyStatusChange;
+    /**
+     * Get API key from environment
+     */
+    private getApiKey;
+    /**
+     * Get install token from environment
+     */
+    private getInstallToken;
+}
+/**
+ * Create a new beacon instance
+ */
+export declare function createBeacon(config: BeaconConfig): Beacon;

package/dist/compliance.d.ts

@@ -171,21 +171,21 @@ export declare class ComplianceMonitor {
      * @param codeSnippet Code snippet for pattern checking
      * @throws ToolUsageError If tool usage is blocked
      */
-    checkToolUsage(toolName: string, codeSnippet?: string): boolean;
+    checkToolUsage(toolName: string, codeSnippet?: string): void;
     /**
      * 💬 Check input content for policy violations
      *
      * @param content Input content to check
      * @throws ContentPolicyError If content violates policy
      */
-    checkInputContent(content: string): boolean;
+    checkInputContent(content: string): void;
     /**
      * 📤 Check output content for policy violations
      *
      * @param content Output content to check
      * @throws ContentPolicyError If content violates policy
      */
-    checkOutputContent(content: string): boolean;
+    checkOutputContent(content: string): void;
     private checkContent;
     /**
      * 🤖 Check AI model usage compliance

package/dist/config/loader.d.ts

@@ -71,7 +71,7 @@ export interface LLMConfig {
     base_url?: string;
 }
 export interface MemoryConfig {
-    type: 'in-memory' | 'redis' | 'postgres';
+    type: 'in-memory' | 'buffer' | 'redis' | 'postgres' | 'sqlite' | 'upstash' | 'cloudflare-kv' | 'cloudflare-d1' | 'dynamodb' | 'turso' | 'convex' | string;
     max_messages?: number;
     redis?: {
         url?: string;
@@ -90,6 +90,43 @@ export interface MemoryConfig {
         password?: string;
         tableName?: string;
     };
+    sqlite?: {
+        filename: string;
+        tableName?: string;
+    };
+    upstash?: {
+        url: string;
+        token: string;
+        keyPrefix?: string;
+    };
+    cloudflareKV?: {
+        namespaceId?: string;
+        accountId?: string;
+        apiToken?: string;
+        keyPrefix?: string;
+    };
+    cloudflareD1?: {
+        databaseId?: string;
+        accountId?: string;
+        apiToken?: string;
+        tableName?: string;
+    };
+    dynamodb?: {
+        tableName: string;
+        region?: string;
+        endpoint?: string;
+        createTable?: boolean;
+    };
+    turso?: {
+        url: string;
+        authToken?: string;
+        tableName?: string;
+    };
+    convex?: {
+        url: string;
+        adminKey?: string;
+    };
+    config?: Record<string, unknown>;
 }
 export interface ComplianceConfig {
     framework?: string;

package/dist/crypto.d.ts

@@ -1,7 +1,4 @@
 import { type HexString, type KeyPair } from "./types";
-/**
- * Cryptographic utilities for Sekuire protocol
- */
 export declare class SekuireCrypto {
     /**
      * Generate a new Ed25519 keypair

package/dist/http/base-client.d.ts

@@ -0,0 +1,25 @@
+export interface HttpClientConfig {
+    baseUrl: string;
+    timeout?: number;
+    retries?: number;
+    apiKey?: string;
+    authToken?: string;
+}
+export declare class HttpClient {
+    private baseUrl;
+    private timeout;
+    private retries;
+    private apiKey?;
+    private authToken?;
+    constructor(config: HttpClientConfig);
+    setAuthToken(token: string): void;
+    setApiKey(apiKey: string): void;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, data?: unknown): Promise<T>;
+    put<T>(path: string, data?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    private resolveUrl;
+    private fetchWithRetry;
+    private shouldRetry;
+    private delay;
+}

package/dist/http/index.d.ts

@@ -0,0 +1,2 @@
+export { HttpClient } from './base-client';
+export type { HttpClientConfig } from './base-client';

package/dist/identity.d.ts

@@ -2,8 +2,17 @@ export declare class AgentIdentity {
     readonly name: string;
     readonly sekuireId: string;
     private readonly privateKey?;
-    private readonly publicKey?;
+    readonly publicKey?: string | undefined;
     constructor(name: string, sekuireId: string, privateKey?: string | undefined, publicKey?: string | undefined);
     static load(manifestPath?: string): Promise<AgentIdentity>;
-    sign(payload: any): Promise<string>;
+    /**
+     * Sign a message using Ed25519
+     * @param message The message string to sign
+     * @returns Hex-encoded signature
+     */
+    sign(message: string): Promise<string>;
+    /**
+     * Verify a signature (useful for testing)
+     */
+    verify(message: string, signatureHex: string): boolean;
 }