@rovn-ai/agent 1.1.0

package/README.md

@@ -0,0 +1,495 @@
+# @rovn-platform/sdk
+
+**AI Agent Governance SDK** -- manage, monitor, and govern your AI agents.
+
+The official TypeScript/JavaScript SDK for [Rovn](https://rovn.io), the AI Agent Command Center. Zero runtime dependencies -- uses only the Fetch API.
+
+## Installation
+
+```bash
+npm install @rovn-platform/sdk
+```
+
+Works with Node.js 18+ (Fetch API required), Deno, Bun, and modern browsers.
+
+## Quick Start (5 minutes)
+
+```typescript
+import { RovnAgent, RovnError } from '@rovn-platform/sdk';
+
+// 1. Register your agent
+const { agent, id, apiKey } = await RovnAgent.register(
+  'https://your-rovn-instance.com',
+  {
+    name: 'my-data-pipeline',
+    description: 'Processes and analyzes customer data',
+    type: 'data_pipeline',
+    capabilities: ['read_database', 'write_reports', 'send_email'],
+  }
+);
+// Save apiKey -- you will need it to reconnect later
+
+// 2. Send an activity
+await agent.logActivity('Processed 1,200 records', {
+  type: 'data_processing',
+  metadata: { records: 1200, duration_ms: 4500 },
+});
+
+// 3. Check if an action is allowed (pre-flight)
+const check = await agent.checkAction('send_email', {
+  urgency: 'high',
+  cost: 0.05,
+});
+
+if (check.allowed) {
+  console.log('Go ahead!');
+} else if (check.needs_approval) {
+  // 4. Request approval from the owner
+  const approvalId = await agent.requestApproval({
+    type: 'action',
+    title: 'Send 500 marketing emails',
+    description: 'Campaign targeting new signups from last week',
+    urgency: 'high',
+  });
+  console.log(`Waiting for approval: ${approvalId}`);
+}
+
+// 5. Get your report card
+const report = await agent.getReportCard({ days: 7 });
+console.log('Trust:', report.trust);
+console.log('Recommendations:', report.recommendations);
+```
+
+## All Available Methods
+
+### Registration & Info
+
+```typescript
+// Register a new agent (static method, no API key needed)
+const { agent, id, apiKey } = await RovnAgent.register(
+  baseUrl: string,
+  options: {
+    name: string;
+    description?: string;
+    type?: string;
+    capabilities?: string[];
+    owner_email?: string;
+    metadata?: Record<string, unknown>;
+  }
+);
+
+// Connect with an existing API key
+const agent = new RovnAgent({
+  baseUrl: 'https://...',
+  apiKey: 'rovn_...',
+  fireAndForget: false,  // optional, default false
+});
+
+// Get agent info (auto-discovers agentId on first call)
+const info: AgentInfo = await agent.getInfo();
+// info.id, info.name, info.description, info.status, info.type,
+// info.approved, info.capabilities, info.metadata, info.created_at,
+// info.updated_at, info.last_seen_at
+```
+
+### Events & Activities
+
+```typescript
+// Log an activity
+await agent.logActivity(
+  title: string,
+  options?: { type?: string; description?: string; metadata?: Record<string, unknown> }
+);
+
+// Update agent status
+await agent.updateStatus(status);  // 'active' | 'idle' | 'busy' | 'offline' | 'error'
+
+// Share structured data with the owner
+await agent.shareData(title: string, content: Record<string, unknown>, type?: string);
+
+// Send a raw event (low-level)
+await agent.sendEvent(event: WebhookEvent, data: Record<string, unknown>);
+```
+
+### Tasks
+
+```typescript
+// Get assigned tasks
+const tasks: Task[] = await agent.getTasks({ status?: string, limit?: number });
+// Each task has: id, agent_id, owner_id, title, description, status,
+// priority, result, scheduled_at, started_at, completed_at
+
+// Update a task's status
+await agent.updateTaskStatus(taskId: string, status: string, result?: Record<string, unknown>);
+```
+
+### Messages & Chat
+
+```typescript
+// Send a message to the owner
+await agent.sendMessage(
+  content: string,
+  options?: { message_type?: string; metadata?: Record<string, unknown> }
+);
+
+// Respond to an owner command
+await agent.respondToCommand(
+  commandId: string, status: string, response?: Record<string, unknown>
+);
+
+// Send a message to another agent
+await agent.sendPeerMessage(
+  toAgentId: string,
+  content: string,
+  options?: { message_type?: string; metadata?: Record<string, unknown> }
+);
+
+// Get peer messages
+const messages: PeerMessage[] = await agent.getPeerMessages({
+  direction?: 'inbox' | 'outbox' | 'all',
+  limit?: number,
+});
+```
+
+### Approvals
+
+```typescript
+// Request approval from the owner
+const approvalId: string | undefined = await agent.requestApproval({
+  type: string,
+  title: string,
+  description?: string,
+  urgency?: 'low' | 'medium' | 'high' | 'critical',
+  metadata?: Record<string, unknown>,
+});
+
+// Poll all approvals
+const approvals: ApprovalRequest[] = await agent.getApprovals({
+  status?: string,
+  limit?: number,
+});
+
+// Poll a specific approval by ID
+const approval: ApprovalRequest = await agent.pollApproval(approvalId: string);
+// approval.id, approval.status, approval.decided_at, approval.decision_note
+```
+
+### Guardrails & Constraints
+
+```typescript
+// Get all guardrails set by the owner
+const guardrails: Guardrail[] = await agent.getGuardrails();
+// Each guardrail: id, metric, limit_value, current_value, window, action, enabled
+
+// Check remaining budget for a specific metric (cached for 60s)
+const remaining: number | null = await agent.getGuardrailRemaining(metric: string);
+
+// Clear the guardrail cache to force a fresh fetch
+agent.invalidateGuardrailCache();
+
+// Declare self-constraints before starting a task
+const constraint: Constraint = await agent.declareConstraint(
+  task: string,
+  constraints: Record<string, unknown>,  // e.g. { max_api_calls: 100, max_cost_usd: 5.0 }
+);
+
+// Update actual usage against a declared constraint
+const result = await agent.updateConstraint(
+  constraintId: string,
+  actualUsage: Record<string, unknown>,  // e.g. { api_calls: 45, cost_usd: 2.10 }
+  completed: boolean = false,
+);
+
+// Get all constraints for this agent
+const constraints: Constraint[] = await agent.getConstraints();
+```
+
+### Trust Score
+
+```typescript
+const trust: TrustScoreResult = await agent.getTrustScore();
+// trust.score (0-100), trust.grade ('A' through 'F'), trust.breakdown, trust.computed_at
+```
+
+### Pre-flight Check
+
+```typescript
+// "Can I do this?" -- checks policies, guardrails, and earned autonomy
+const check: CheckResult = await agent.checkAction(
+  action: string,
+  options?: {
+    urgency?: string;
+    cost?: number;
+    data_fields?: string[];
+  }
+);
+// check.allowed        -- true if the action can proceed
+// check.needs_approval -- true if the action requires owner approval
+// check.would_auto_approve -- true if earned autonomy would auto-approve
+// check.checks         -- array of individual check results
+// check.summary        -- human-readable summary
+```
+
+### Report Card
+
+```typescript
+const report: ReportCard = await agent.getReportCard({ days?: number });
+// report.agent          -- { id, name }
+// report.period         -- time period string
+// report.productivity   -- productivity metrics
+// report.reliability    -- reliability metrics
+// report.compliance     -- compliance metrics
+// report.trust          -- trust metrics
+// report.recommendations -- array of improvement suggestions
+```
+
+### SSE Connection (Real-Time)
+
+```typescript
+agent.connect(
+  handler: (event: SSEEventType, data: Record<string, unknown>) => void,
+  options?: {
+    agentId?: string;      // override auto-discovered ID
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    reconnect?: boolean;   // default true, auto-reconnect on disconnect
+  }
+);
+
+// Example handler
+agent.connect((event, data) => {
+  // event is one of: 'connected', 'command', 'approval_response',
+  //                   'interrupt', 'agent_updated', 'peer_message'
+  switch (event) {
+    case 'command':
+      console.log('Owner command:', data);
+      break;
+    case 'approval_response':
+      console.log(`Approval ${data.id}: ${data.status}`);
+      break;
+    case 'interrupt':
+      agent.disconnect();
+      break;
+  }
+});
+
+// Stop listening
+agent.disconnect();
+```
+
+### Flush & Close
+
+```typescript
+// Flush all queued events (blocks until drained)
+await agent.flush();
+
+// Graceful shutdown: disconnect SSE + flush pending events
+await agent.close();
+```
+
+## Advanced Features
+
+### Fire-and-Forget Mode
+
+Events are queued in memory and sent asynchronously with automatic retry. Your code never awaits HTTP calls for event delivery.
+
+```typescript
+const agent = new RovnAgent({
+  baseUrl: 'https://...',
+  apiKey: 'rovn_...',
+  fireAndForget: true,
+});
+
+await agent.logActivity('Instant return, sent in background');
+await agent.sendMessage('Also queued');
+await agent.updateStatus('busy');
+
+// Flush before shutdown to guarantee delivery
+await agent.flush();
+
+// Or use close() for full graceful shutdown
+await agent.close();
+```
+
+Even in synchronous mode, transient failures (5xx, network errors) are automatically queued for retry instead of throwing.
+
+### Error Handling
+
+All API errors throw `RovnError` with structured information.
+
+```typescript
+import { RovnError } from '@rovn-platform/sdk';
+
+try {
+  await agent.logActivity('test');
+} catch (err) {
+  if (err instanceof RovnError) {
+    console.error(err.message);     // human-readable message
+    console.error(err.statusCode);  // HTTP status code (0 for network errors)
+    console.error(err.errorCode);   // server error code (e.g. 'rate_limited')
+  }
+}
+```
+
+Common error scenarios:
+- **`statusCode === 0`** -- Network error (connection refused, DNS failure)
+- **`statusCode === 401`** -- Invalid or expired API key
+- **`statusCode === 429`** -- Rate limited (auto-retried)
+- **`statusCode >= 500`** -- Server error (auto-retried)
+- **`errorCode === 'AGENT_ID_MISSING'`** -- Call `getInfo()` or `register()` first
+
+### Retry Behavior
+
+The SDK automatically retries on:
+- Network errors (fetch failures, connection reset)
+- HTTP 429 (rate limit)
+- HTTP 5xx (server errors)
+
+Retry uses exponential backoff: 1s, 2s, 4s, 8s, ... up to 30s max. Non-retryable errors (4xx except 429) cause the event to be dropped from the queue.
+
+In fire-and-forget mode, failed events stay at the front of the queue and are retried with backoff. In synchronous mode, retryable failures are automatically queued for background retry instead of throwing.
+
+The event queue holds up to 10,000 events. When full, the oldest event is dropped to make room.
+
+### Guardrail Cache
+
+`getGuardrailRemaining()` caches the guardrail list for 60 seconds to avoid excessive API calls. The cache is automatically refreshed when stale.
+
+```typescript
+// First call fetches from API
+const remaining = await agent.getGuardrailRemaining('api_calls'); // -> 950
+
+// Subsequent calls within 60s use the cache
+const remaining2 = await agent.getGuardrailRemaining('api_calls'); // -> 950 (cached)
+
+// Force a fresh fetch
+agent.invalidateGuardrailCache();
+const remaining3 = await agent.getGuardrailRemaining('api_calls'); // -> 947 (fresh)
+```
+
+## Complete Workflow Example
+
+```typescript
+import { RovnAgent, RovnError } from '@rovn-platform/sdk';
+
+const ROVN_URL = 'https://your-rovn-instance.com';
+const API_KEY = 'rovn_abc123...';
+
+async function main() {
+  // Connect to Rovn
+  const agent = new RovnAgent({ baseUrl: ROVN_URL, apiKey: API_KEY });
+  const info = await agent.getInfo();
+  console.log(`Agent: ${info.name} (status: ${info.status})`);
+
+  // Check trust score
+  const trust = await agent.getTrustScore();
+  console.log(`Trust: ${trust.grade} (${trust.score}/100)`);
+
+  // Check if we're allowed to send emails
+  const check = await agent.checkAction('send_email', { cost: 2.5 });
+
+  if (!check.allowed) {
+    if (check.needs_approval) {
+      // Request approval and wait
+      const approvalId = await agent.requestApproval({
+        type: 'action',
+        title: 'Send weekly report emails',
+        description: '150 emails to subscribers, estimated cost $2.50',
+        urgency: 'medium',
+      });
+      console.log(`Approval requested: ${approvalId}`);
+
+      // Poll until decided
+      let approval;
+      do {
+        await new Promise(r => setTimeout(r, 5000));
+        approval = await agent.pollApproval(approvalId!);
+      } while (approval.status === 'pending');
+
+      if (approval.status !== 'approved') {
+        console.log(`Denied: ${approval.decision_note}`);
+        return;
+      }
+    } else {
+      console.log(`Blocked: ${check.summary}`);
+      return;
+    }
+  }
+
+  // Declare constraints for the task
+  const constraint = await agent.declareConstraint(
+    'send_weekly_emails',
+    { max_emails: 200, max_cost_usd: 5.0 },
+  );
+
+  // Do the work
+  await agent.updateStatus('busy');
+  await agent.logActivity('Sending weekly report emails', { type: 'email_campaign' });
+
+  const emailsSent = 150;
+  const cost = 2.35;
+
+  // Report actual usage
+  await agent.updateConstraint(
+    constraint.id,
+    { emails: emailsSent, cost_usd: cost },
+    true, // completed
+  );
+
+  // Notify owner
+  await agent.sendMessage(
+    `Weekly emails sent: ${emailsSent} emails, $${cost.toFixed(2)}`,
+    { metadata: { emails_sent: emailsSent, cost_usd: cost } },
+  );
+
+  await agent.updateStatus('idle');
+
+  // Check report card
+  const report = await agent.getReportCard({ days: 7 });
+  console.log('Recommendations:', report.recommendations);
+
+  // Graceful shutdown
+  await agent.close();
+}
+
+main().catch(console.error);
+```
+
+## Exported Types
+
+All types are importable from the package:
+
+```typescript
+import {
+  RovnAgent,         // Client class
+  RovnError,         // Error class
+  type RovnConfig,   // Constructor config
+  type AgentInfo,    // Agent profile
+  type Task,         // Assigned task
+  type PeerMessage,  // Inter-agent message
+  type Guardrail,    // Usage limit
+  type Constraint,   // Self-constraint declaration
+  type ApprovalRequest,   // Approval request/response
+  type TrustScoreResult,  // Trust score result
+  type CheckResult,       // Pre-flight check result
+  type ReportCard,        // Performance report card
+  type AgentStatus,       // 'active' | 'idle' | 'busy' | 'offline' | 'error'
+  type TaskStatus,        // 'pending' | 'in_progress' | 'completed' | 'cancelled' | 'failed'
+  type TaskPriority,      // 'low' | 'medium' | 'high' | 'urgent'
+  type WebhookEvent,      // Event type union
+  type SSEEventType,      // SSE event type union
+  type SSEHandler,        // SSE handler function type
+  type GuardrailWindow,   // 'hourly' | 'daily' | 'weekly' | 'monthly'
+  type GuardrailAction,   // 'warn' | 'block' | 'approval_required'
+} from '@rovn-platform/sdk';
+```
+
+## Requirements
+
+- Node.js 18+ (Fetch API), Deno, Bun, or modern browsers
+- TypeScript 5+ (for type definitions)
+- Zero runtime dependencies
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+export type RovnConfig = {
+    baseUrl: string;
+    apiKey: string;
+    /** When true, sendEvent queues events and returns immediately without awaiting the HTTP call. */
+    fireAndForget?: boolean;
+};
+export type WebhookEvent = 'activity' | 'task_update' | 'message' | 'status' | 'share_data' | 'command_response' | 'approval_request' | 'peer_message';
+export type SSEEventType = 'connected' | 'command' | 'approval_response' | 'interrupt' | 'agent_updated' | 'peer_message';
+export type SSEHandler = (event: SSEEventType, data: Record<string, unknown>) => void;
+export type AgentStatus = 'active' | 'idle' | 'busy' | 'offline' | 'error';
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled' | 'failed';
+export type TaskPriority = 'low' | 'medium' | 'high' | 'urgent';
+export type GuardrailWindow = 'hourly' | 'daily' | 'weekly' | 'monthly';
+export type GuardrailAction = 'warn' | 'block' | 'approval_required';
+export interface AgentInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    status: AgentStatus;
+    type: string;
+    approved: boolean;
+    capabilities: string[] | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+    last_seen_at: string | null;
+}
+export interface Task {
+    id: string;
+    agent_id: string;
+    owner_id: string;
+    title: string;
+    description: string | null;
+    status: TaskStatus;
+    priority: TaskPriority;
+    result: Record<string, unknown> | null;
+    scheduled_at: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface PeerMessage {
+    id: string;
+    from_agent_id: string;
+    to_agent_id: string;
+    content: string;
+    message_type: string;
+    metadata: Record<string, unknown> | null;
+    read_at: string | null;
+    created_at: string;
+    from_agent_name?: string;
+    to_agent_name?: string;
+}
+export interface Guardrail {
+    id: string;
+    agent_id: string;
+    owner_id: string;
+    metric: string;
+    limit_value: number;
+    current_value: number;
+    window: GuardrailWindow;
+    action: GuardrailAction;
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface Constraint {
+    id: string;
+    agent_id: string;
+    task: string;
+    constraints: Record<string, unknown>;
+    actual_usage: Record<string, unknown> | null;
+    compliance: string;
+    started_at: string;
+    completed_at: string | null;
+}
+export interface ApprovalRequest {
+    id: string;
+    agent_id: string;
+    type: string;
+    title: string;
+    status: string;
+    urgency: string;
+    description: string | null;
+    decided_at: string | null;
+    decided_by: string | null;
+    decision_note: string | null;
+    created_at: string;
+}
+export interface TrustScoreResult {
+    agent_id: string;
+    score: number;
+    grade: string;
+    breakdown: Record<string, unknown>;
+    computed_at: string;
+}
+export interface CheckResult {
+    action: string;
+    allowed: boolean;
+    needs_approval: boolean;
+    would_auto_approve: boolean;
+    checks: Array<{
+        check: string;
+        passed: boolean;
+        detail: string;
+    }>;
+    summary: string;
+}
+export interface ReportCard {
+    agent: {
+        id: string;
+        name: string;
+    };
+    period: string;
+    productivity: Record<string, unknown>;
+    reliability: Record<string, unknown>;
+    compliance: Record<string, unknown>;
+    trust: Record<string, unknown>;
+    recommendations: string[];
+}
+export declare class RovnError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string | undefined;
+    constructor(message: string, statusCode: number, errorCode?: string);
+}
+export declare class RovnAgent {
+    private baseUrl;
+    private apiKey;
+    private agentId;
+    private sseController;
+    private fireAndForget;
+    private eventQueue;
+    private flushTimer;
+    private flushing;
+    private guardrailCache;
+    constructor(config: RovnConfig);
+    private headers;
+    /**
+     * Throws RovnError if agentId has not been set yet.
+     * Call register(), getInfo(), or connect({ agentId }) first.
+     */
+    private ensureAgentId;
+    private request;
+    /**
+     * Returns true if the error looks like a network / transient failure
+     * (as opposed to a 4xx client error that retrying won't fix).
+     */
+    private isRetryable;
+    private enqueue;
+    private scheduleFlush;
+    /**
+     * Internal drain loop — sends queued events one by one.
+     * On failure, re-queues the event at the front with incremented retry count
+     * and waits with exponential backoff before trying again.
+     */
+    private drainQueue;
+    static register(baseUrl: string, options: {
+        name: string;
+        description?: string;
+        type?: string;
+        capabilities?: string[];
+        owner_email?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        agent: RovnAgent;
+        id: string;
+        apiKey: string;
+    }>;
+    getInfo(): Promise<AgentInfo>;
+    sendEvent(event: WebhookEvent, data: Record<string, unknown>): Promise<Record<string, unknown> | void>;
+    logActivity(title: string, options?: {
+        type?: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    updateTaskStatus(taskId: string, status: string, result?: Record<string, unknown>): Promise<void>;
+    sendMessage(content: string, options?: {
+        message_type?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    updateStatus(status: AgentStatus): Promise<void>;
+    shareData(title: string, content: Record<string, unknown>, type?: string): Promise<void>;
+    respondToCommand(commandId: string, status: string, response?: Record<string, unknown>): Promise<void>;
+    requestApproval(options: {
+        type: string;
+        title: string;
+        description?: string;
+        urgency?: 'low' | 'medium' | 'high' | 'critical';
+        metadata?: Record<string, unknown>;
+    }): Promise<string | undefined>;
+    sendPeerMessage(toAgentId: string, content: string, options?: {
+        message_type?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Sends all queued events. Resolves when the queue is drained.
+     * Useful before shutdown or when you need to guarantee delivery.
+     */
+    flush(): Promise<void>;
+    /**
+     * Graceful shutdown: disconnects SSE, flushes pending events.
+     */
+    close(): Promise<void>;
+    connect(handler: SSEHandler, options?: {
+        agentId?: string;
+        onConnect?: () => void;
+        onDisconnect?: () => void;
+        reconnect?: boolean;
+    }): void;
+    disconnect(): void;
+    getTasks(options?: {
+        status?: string;
+        limit?: number;
+    }): Promise<Task[]>;
+    getPeerMessages(options?: {
+        direction?: 'inbox' | 'outbox' | 'all';
+        limit?: number;
+    }): Promise<PeerMessage[]>;
+    getGuardrails(): Promise<Guardrail[]>;
+    /**
+     * Returns how many units remain before hitting the guardrail limit for the
+     * given metric.  Returns `null` if no guardrail matches.
+     *
+     * Results are cached for 60 seconds to reduce API calls.
+     */
+    getGuardrailRemaining(metric: string): Promise<number | null>;
+    /** Clears the cached guardrail data so the next call fetches fresh values. */
+    invalidateGuardrailCache(): void;
+    declareConstraint(task: string, constraints: Record<string, unknown>): Promise<Constraint>;
+    updateConstraint(constraintId: string, actualUsage: Record<string, unknown>, completed?: boolean): Promise<Record<string, unknown>>;
+    getConstraints(): Promise<Constraint[]>;
+    getTrustScore(): Promise<TrustScoreResult>;
+    getApprovals(options?: {
+        status?: string;
+        limit?: number;
+    }): Promise<ApprovalRequest[]>;
+    pollApproval(approvalId: string): Promise<ApprovalRequest>;
+    checkAction(action: string, options?: {
+        urgency?: string;
+        cost?: number;
+        data_fields?: string[];
+    }): Promise<CheckResult>;
+    getReportCard(options?: {
+        days?: number;
+    }): Promise<ReportCard>;
+}
+/**
+ * Wraps any function with Rovn governance: pre-flight policy check + activity reporting.
+ *
+ * @example
+ * ```ts
+ * import { RovnAgent, createGovernedTool } from 'rovn-sdk';
+ *
+ * const agent = new RovnAgent({ baseUrl: '...', apiKey: '...' });
+ * await agent.getInfo();
+ *
+ * const search = createGovernedTool(agent, {
+ *   name: 'search',
+ *   actionName: 'db_read',
+ *   fn: async (query: string) => `Results for ${query}`,
+ * });
+ *
+ * const result = await search('my query');
+ * ```
+ */
+export declare function createGovernedTool<TArgs extends unknown[], TResult>(agent: RovnAgent, options: {
+    name: string;
+    actionName?: string;
+    fn: (...args: TArgs) => TResult | Promise<TResult>;
+}): (...args: TArgs) => Promise<TResult>;
+/**
+ * Creates a middleware-style wrapper for Vercel AI SDK that reports
+ * each generation to Rovn and checks policies.
+ *
+ * @example
+ * ```ts
+ * import { RovnAgent, createVercelAIMiddleware } from 'rovn-sdk';
+ *
+ * const agent = new RovnAgent({ baseUrl: '...', apiKey: '...' });
+ * await agent.getInfo();
+ *
+ * const middleware = createVercelAIMiddleware(agent);
+ *
+ * // Wrap your doGenerate or doStream calls:
+ * const result = await middleware.wrapGenerate(async () => {
+ *   return await model.doGenerate({ prompt: '...' });
+ * });
+ * ```
+ */
+export declare function createVercelAIMiddleware(agent: RovnAgent, options?: {
+    actionName?: string;
+}): {
+    /**
+     * Wraps a doGenerate call with policy check + activity reporting.
+     */
+    wrapGenerate<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Wraps a doStream call with policy check + activity reporting.
+     */
+    wrapStream<T>(fn: () => Promise<T>): Promise<T>;
+};
+export default RovnAgent;

package/dist/index.js

@@ -0,0 +1,586 @@
+"use strict";
+// ==================== Types ====================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RovnAgent = exports.RovnError = void 0;
+exports.createGovernedTool = createGovernedTool;
+exports.createVercelAIMiddleware = createVercelAIMiddleware;
+// ==================== Error ====================
+class RovnError extends Error {
+    statusCode;
+    errorCode;
+    constructor(message, statusCode, errorCode) {
+        super(message);
+        this.name = 'RovnError';
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+    }
+}
+exports.RovnError = RovnError;
+// ==================== Client ====================
+const MAX_QUEUE_SIZE = 10_000;
+const MAX_BACKOFF_MS = 30_000;
+const GUARDRAIL_CACHE_TTL_MS = 60_000;
+class RovnAgent {
+    baseUrl;
+    apiKey;
+    agentId = null;
+    sseController = null;
+    fireAndForget;
+    // Event queue for fire-and-forget and offline resilience
+    eventQueue = [];
+    flushTimer = null;
+    flushing = false;
+    // Guardrail cache
+    guardrailCache = null;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.fireAndForget = config.fireAndForget ?? false;
+    }
+    // ==================== Private Helpers ====================
+    headers() {
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Throws RovnError if agentId has not been set yet.
+     * Call register(), getInfo(), or connect({ agentId }) first.
+     */
+    ensureAgentId() {
+        if (!this.agentId) {
+            throw new RovnError('agentId is required. Call register(), getInfo(), or connect({ agentId }) first.', 0, 'AGENT_ID_MISSING');
+        }
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok && res.headers.get('content-type')?.includes('text/html')) {
+            throw new RovnError(`Server error: ${res.status} ${res.statusText}`, res.status);
+        }
+        const data = await res.json();
+        if (!data.success) {
+            throw new RovnError(data.error || `Request failed: ${method} ${path}`, res.status, data.code);
+        }
+        return data.data;
+    }
+    /**
+     * Returns true if the error looks like a network / transient failure
+     * (as opposed to a 4xx client error that retrying won't fix).
+     */
+    isRetryable(err) {
+        if (err instanceof RovnError) {
+            // Retry on 5xx and 429; don't retry on 4xx client errors
+            return err.statusCode >= 500 || err.statusCode === 429;
+        }
+        // Network errors (TypeError from fetch), AbortError, etc. are retryable
+        return true;
+    }
+    // ==================== Event Queue Internals ====================
+    enqueue(event, data) {
+        if (this.eventQueue.length >= MAX_QUEUE_SIZE) {
+            // Drop the oldest event to make room
+            this.eventQueue.shift();
+        }
+        this.eventQueue.push({ event, data, retries: 0 });
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.flushTimer || this.flushing)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.drainQueue();
+        }, 0);
+    }
+    /**
+     * Internal drain loop — sends queued events one by one.
+     * On failure, re-queues the event at the front with incremented retry count
+     * and waits with exponential backoff before trying again.
+     */
+    async drainQueue() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        try {
+            while (this.eventQueue.length > 0) {
+                const item = this.eventQueue[0];
+                try {
+                    await this.request('POST', '/api/webhook/agent', { event: item.event, data: item.data });
+                    // Success — remove from queue
+                    this.eventQueue.shift();
+                }
+                catch (err) {
+                    if (this.isRetryable(err)) {
+                        // Exponential backoff: 1s, 2s, 4s, 8s, …, max 30s
+                        const delayMs = Math.min(1000 * Math.pow(2, item.retries), MAX_BACKOFF_MS);
+                        item.retries++;
+                        await new Promise(resolve => setTimeout(resolve, delayMs));
+                        // The item is still at the front of the queue; loop will retry it
+                    }
+                    else {
+                        // Non-retryable error — drop the event and move on
+                        this.eventQueue.shift();
+                    }
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    // ==================== Registration ====================
+    static async register(baseUrl, options) {
+        const res = await fetch(`${baseUrl.replace(/\/$/, '')}/api/agents/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(options),
+        });
+        const data = await res.json();
+        if (!data.success)
+            throw new RovnError(data.error || 'Registration failed', res.status);
+        const agent = new RovnAgent({ baseUrl, apiKey: data.data.api_key });
+        agent.agentId = data.data.id;
+        return { agent, id: data.data.id, apiKey: data.data.api_key };
+    }
+    // ==================== Agent Info ====================
+    async getInfo() {
+        if (!this.agentId) {
+            const info = await this.request('GET', '/api/agents/me');
+            this.agentId = info.id;
+            return info;
+        }
+        return this.request('GET', `/api/agents/${this.agentId}`);
+    }
+    // ==================== Webhook (unified event endpoint) ====================
+    async sendEvent(event, data) {
+        if (this.fireAndForget) {
+            this.enqueue(event, data);
+            return;
+        }
+        try {
+            return await this.request('POST', '/api/webhook/agent', { event, data });
+        }
+        catch (err) {
+            if (this.isRetryable(err)) {
+                // Queue for retry with backoff
+                this.enqueue(event, data);
+                return;
+            }
+            throw err;
+        }
+    }
+    async logActivity(title, options) {
+        await this.sendEvent('activity', { title, ...options });
+    }
+    async updateTaskStatus(taskId, status, result) {
+        await this.sendEvent('task_update', { task_id: taskId, status, result });
+    }
+    async sendMessage(content, options) {
+        await this.sendEvent('message', { content, ...options });
+    }
+    async updateStatus(status) {
+        await this.sendEvent('status', { status });
+    }
+    async shareData(title, content, type) {
+        await this.sendEvent('share_data', { title, content, type });
+    }
+    async respondToCommand(commandId, status, response) {
+        await this.sendEvent('command_response', { command_id: commandId, status, response });
+    }
+    async requestApproval(options) {
+        // Always send synchronously to guarantee approval_id, even in fire-and-forget mode
+        const result = await this.request('POST', '/api/webhook/agent', { event: 'approval_request', data: options });
+        return result?.approval_id;
+    }
+    async sendPeerMessage(toAgentId, content, options) {
+        await this.sendEvent('peer_message', { to_agent_id: toAgentId, content, ...options });
+    }
+    // ==================== Flush ====================
+    /**
+     * Sends all queued events. Resolves when the queue is drained.
+     * Useful before shutdown or when you need to guarantee delivery.
+     */
+    async flush() {
+        // Cancel any pending scheduled flush
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // If already flushing, wait for it to finish
+        if (this.flushing) {
+            // Spin-wait until the current drain completes
+            while (this.flushing) {
+                await new Promise(resolve => setTimeout(resolve, 50));
+            }
+            // If items were added during the wait, drain again
+            if (this.eventQueue.length > 0) {
+                await this.drainQueue();
+            }
+            return;
+        }
+        if (this.eventQueue.length > 0) {
+            await this.drainQueue();
+        }
+    }
+    // ==================== Close ====================
+    /**
+     * Graceful shutdown: disconnects SSE, flushes pending events.
+     */
+    async close() {
+        this.disconnect();
+        await this.flush();
+    }
+    // ==================== SSE Stream ====================
+    connect(handler, options) {
+        const targetId = options?.agentId ?? this.agentId;
+        if (targetId)
+            this.agentId = targetId;
+        if (!this.agentId) {
+            throw new RovnError('agentId is required. Call register() or getInfo() first, or pass agentId in options.', 0);
+        }
+        const reconnect = options?.reconnect !== false;
+        let lastEventId = null;
+        const doConnect = async () => {
+            this.sseController = new AbortController();
+            try {
+                const headers = { ...this.headers() };
+                if (lastEventId)
+                    headers['Last-Event-ID'] = lastEventId;
+                const response = await fetch(`${this.baseUrl}/api/agents/${this.agentId}/stream`, {
+                    headers,
+                    signal: this.sseController.signal,
+                });
+                if (!response.ok || !response.body) {
+                    throw new RovnError(`SSE connection failed: ${response.status}`, response.status);
+                }
+                options?.onConnect?.();
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                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() || '';
+                    let eventType = '';
+                    let eventData = '';
+                    for (const line of lines) {
+                        if (line.startsWith('id: ')) {
+                            lastEventId = line.slice(4);
+                        }
+                        else if (line.startsWith('event: ')) {
+                            eventType = line.slice(7);
+                        }
+                        else if (line.startsWith('data: ')) {
+                            eventData = line.slice(6);
+                        }
+                        else if (line === '' && eventType && eventData) {
+                            try {
+                                const parsed = JSON.parse(eventData);
+                                handler(eventType, parsed);
+                            }
+                            catch {
+                                // ignore parse errors
+                            }
+                            eventType = '';
+                            eventData = '';
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (err.name === 'AbortError')
+                    return;
+                options?.onDisconnect?.();
+                if (reconnect) {
+                    await new Promise(r => setTimeout(r, 3000));
+                    doConnect();
+                }
+            }
+        };
+        doConnect();
+    }
+    disconnect() {
+        this.sseController?.abort();
+        this.sseController = null;
+    }
+    // ==================== Tasks ====================
+    async getTasks(options) {
+        this.ensureAgentId();
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set('status', options.status);
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        const qs = params.toString();
+        return this.request('GET', `/api/agents/${this.agentId}/tasks${qs ? '?' + qs : ''}`);
+    }
+    // ==================== Peer Messages ====================
+    async getPeerMessages(options) {
+        this.ensureAgentId();
+        const params = new URLSearchParams();
+        if (options?.direction)
+            params.set('direction', options.direction);
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        const qs = params.toString();
+        return this.request('GET', `/api/agents/${this.agentId}/peer${qs ? '?' + qs : ''}`);
+    }
+    // ==================== Guardrails ====================
+    async getGuardrails() {
+        this.ensureAgentId();
+        return this.request('GET', `/api/agents/${this.agentId}/guardrails`);
+    }
+    // ==================== Guardrail Helper ====================
+    /**
+     * Returns how many units remain before hitting the guardrail limit for the
+     * given metric.  Returns `null` if no guardrail matches.
+     *
+     * Results are cached for 60 seconds to reduce API calls.
+     */
+    async getGuardrailRemaining(metric) {
+        this.ensureAgentId();
+        const now = Date.now();
+        if (!this.guardrailCache || now - this.guardrailCache.cachedAt > GUARDRAIL_CACHE_TTL_MS) {
+            this.guardrailCache = {
+                data: await this.request('GET', `/api/agents/${this.agentId}/guardrails`),
+                cachedAt: now,
+            };
+        }
+        const guardrail = this.guardrailCache.data.find(g => g.metric === metric);
+        if (!guardrail)
+            return null;
+        return guardrail.limit_value - guardrail.current_value;
+    }
+    /** Clears the cached guardrail data so the next call fetches fresh values. */
+    invalidateGuardrailCache() {
+        this.guardrailCache = null;
+    }
+    // ==================== Constraints (Self-Constraint Declaration) ====================
+    async declareConstraint(task, constraints) {
+        this.ensureAgentId();
+        return this.request('POST', `/api/agents/${this.agentId}/constraints`, {
+            task,
+            constraints,
+        });
+    }
+    async updateConstraint(constraintId, actualUsage, completed = false) {
+        this.ensureAgentId();
+        return this.request('PATCH', `/api/agents/${this.agentId}/constraints`, {
+            constraint_id: constraintId,
+            actual_usage: actualUsage,
+            completed,
+        });
+    }
+    async getConstraints() {
+        this.ensureAgentId();
+        return this.request('GET', `/api/agents/${this.agentId}/constraints`);
+    }
+    // ==================== Trust Score ====================
+    async getTrustScore() {
+        this.ensureAgentId();
+        return this.request('GET', `/api/agents/${this.agentId}/trust-score`);
+    }
+    // ==================== Approvals (Polling) ====================
+    async getApprovals(options) {
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set('status', options.status);
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        const qs = params.toString();
+        const data = await this.request('GET', `/api/approvals${qs ? '?' + qs : ''}`);
+        return data.approvals ?? data;
+    }
+    async pollApproval(approvalId) {
+        return this.request('GET', `/api/approvals/${approvalId}`);
+    }
+    // ==================== Pre-flight Check ("Can I Do This?") ====================
+    async checkAction(action, options) {
+        this.ensureAgentId();
+        const params = new URLSearchParams({ action });
+        if (options?.urgency)
+            params.set('urgency', options.urgency);
+        if (options?.cost !== undefined)
+            params.set('cost', String(options.cost));
+        if (options?.data_fields)
+            params.set('data_fields', options.data_fields.join(','));
+        return this.request('GET', `/api/agents/${this.agentId}/check?${params}`);
+    }
+    // ==================== Report Card ====================
+    async getReportCard(options) {
+        this.ensureAgentId();
+        const params = new URLSearchParams();
+        if (options?.days)
+            params.set('days', String(options.days));
+        const qs = params.toString();
+        return this.request('GET', `/api/agents/${this.agentId}/report-card${qs ? '?' + qs : ''}`);
+    }
+}
+exports.RovnAgent = RovnAgent;
+// ==================== LangChain-style Tool Wrapper ====================
+/**
+ * Wraps any function with Rovn governance: pre-flight policy check + activity reporting.
+ *
+ * @example
+ * ```ts
+ * import { RovnAgent, createGovernedTool } from 'rovn-sdk';
+ *
+ * const agent = new RovnAgent({ baseUrl: '...', apiKey: '...' });
+ * await agent.getInfo();
+ *
+ * const search = createGovernedTool(agent, {
+ *   name: 'search',
+ *   actionName: 'db_read',
+ *   fn: async (query: string) => `Results for ${query}`,
+ * });
+ *
+ * const result = await search('my query');
+ * ```
+ */
+function createGovernedTool(agent, options) {
+    const actionName = options.actionName ?? options.name;
+    return async (...args) => {
+        // Pre-flight check
+        try {
+            const check = await agent.checkAction(actionName);
+            if (!check.allowed) {
+                await agent.logActivity(`Blocked: ${actionName}`, {
+                    type: 'policy_block',
+                    description: check.summary,
+                });
+                throw new RovnError(`Action '${actionName}' blocked by policy: ${check.summary}`, 403, 'POLICY_BLOCKED');
+            }
+        }
+        catch (err) {
+            if (err instanceof RovnError)
+                throw err;
+            // If check fails (network, etc.), allow execution but continue
+        }
+        // Execute
+        try {
+            const result = await options.fn(...args);
+            await agent.logActivity(`Executed: ${actionName}`, {
+                type: 'tool_execution',
+                description: `Tool '${options.name}' completed successfully`,
+            });
+            return result;
+        }
+        catch (err) {
+            if (err instanceof RovnError)
+                throw err;
+            await agent.logActivity(`Failed: ${actionName}`, {
+                type: 'tool_error',
+                description: `Tool '${options.name}' failed: ${err}`,
+            });
+            throw err;
+        }
+    };
+}
+// ==================== Vercel AI SDK Middleware ====================
+/**
+ * Creates a middleware-style wrapper for Vercel AI SDK that reports
+ * each generation to Rovn and checks policies.
+ *
+ * @example
+ * ```ts
+ * import { RovnAgent, createVercelAIMiddleware } from 'rovn-sdk';
+ *
+ * const agent = new RovnAgent({ baseUrl: '...', apiKey: '...' });
+ * await agent.getInfo();
+ *
+ * const middleware = createVercelAIMiddleware(agent);
+ *
+ * // Wrap your doGenerate or doStream calls:
+ * const result = await middleware.wrapGenerate(async () => {
+ *   return await model.doGenerate({ prompt: '...' });
+ * });
+ * ```
+ */
+function createVercelAIMiddleware(agent, options) {
+    const actionName = options?.actionName ?? 'ai_generate';
+    return {
+        /**
+         * Wraps a doGenerate call with policy check + activity reporting.
+         */
+        async wrapGenerate(fn) {
+            // Pre-flight check
+            try {
+                const check = await agent.checkAction(actionName);
+                if (!check.allowed) {
+                    await agent.logActivity(`Blocked: ${actionName}`, {
+                        type: 'policy_block',
+                        description: check.summary,
+                    });
+                    throw new RovnError(`Action '${actionName}' blocked by policy: ${check.summary}`, 403, 'POLICY_BLOCKED');
+                }
+            }
+            catch (err) {
+                if (err instanceof RovnError)
+                    throw err;
+            }
+            const start = Date.now();
+            try {
+                const result = await fn();
+                const duration = Date.now() - start;
+                await agent.logActivity(`AI Generate completed`, {
+                    type: 'ai_generate',
+                    description: `Generation took ${duration}ms`,
+                    metadata: { duration_ms: duration },
+                });
+                return result;
+            }
+            catch (err) {
+                if (err instanceof RovnError)
+                    throw err;
+                const duration = Date.now() - start;
+                await agent.logActivity(`AI Generate failed`, {
+                    type: 'ai_error',
+                    description: `Generation failed after ${duration}ms: ${err}`,
+                });
+                throw err;
+            }
+        },
+        /**
+         * Wraps a doStream call with policy check + activity reporting.
+         */
+        async wrapStream(fn) {
+            try {
+                const check = await agent.checkAction(actionName);
+                if (!check.allowed) {
+                    await agent.logActivity(`Blocked: ${actionName} (stream)`, {
+                        type: 'policy_block',
+                        description: check.summary,
+                    });
+                    throw new RovnError(`Action '${actionName}' blocked by policy: ${check.summary}`, 403, 'POLICY_BLOCKED');
+                }
+            }
+            catch (err) {
+                if (err instanceof RovnError)
+                    throw err;
+            }
+            try {
+                const result = await fn();
+                await agent.logActivity(`AI Stream started`, { type: 'ai_stream' });
+                return result;
+            }
+            catch (err) {
+                if (err instanceof RovnError)
+                    throw err;
+                await agent.logActivity(`AI Stream failed`, {
+                    type: 'ai_error',
+                    description: `Stream failed: ${err}`,
+                });
+                throw err;
+            }
+        },
+    };
+}
+exports.default = RovnAgent;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@rovn-ai/agent",
+  "version": "1.1.0",
+  "description": "TypeScript SDK for Rovn Agent OS",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["ai-agent", "agent-os", "rovn"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}