@vorionsys/sdk

Developer-friendly SDK for AI agent governance. Register agents, request action permissions, and report outcomes with a simple API. Supports both local mode (in-memory, for testing) and remote mode (Cognigate API).

Installation

npm install @vorionsys/sdk

Quick Start

import { Vorion } from '@vorionsys/sdk';

// Local mode (for development/testing)
const vorion = new Vorion({ localMode: true });

const agent = await vorion.registerAgent({
  agentId: 'my-agent',
  name: 'My AI Agent',
  capabilities: ['read:*', 'write:documents'],
});

const result = await agent.requestAction({
  type: 'read',
  resource: 'documents/report.pdf',
});

if (result.allowed) {
  // Perform the action
  await agent.reportSuccess('read');
} else {
  console.log('Denied:', result.reason);
}

Features

• Simple API: Register agents, request permissions, report outcomes
• Local Mode: In-memory governance for development and testing
• Remote Mode: Connect to a hosted Cognigate API for production
• Trust Signals: Report success/failure to dynamically update agent trust scores
• Capability Checks: Permission-based action authorization
• Audit Trail: Every action request returns a proof ID for compliance
• Full TypeScript: Complete type definitions for all APIs

Modes

Local Mode

No external dependencies. Agent trust is managed in-memory with a simple capability check:

const vorion = new Vorion({ localMode: true });

Remote Mode

Connects to a Cognigate API instance for production governance:

const vorion = new Vorion({
  apiEndpoint: 'https://cognigate.dev',
  apiKey: process.env.VORION_API_KEY,
});

API Reference

Vorion Client

const vorion = new Vorion({
  apiEndpoint?: string,       // Cognigate API URL (enables remote mode)
  apiKey?: string,            // API key (required for remote mode)
  localMode?: boolean,        // Force local mode (default: true if no endpoint)
  defaultObservationTier?: 'BLACK_BOX' | 'GRAY_BOX' | 'WHITE_BOX',
  timeout?: number,           // Request timeout in ms (default: 30000)
});

// Or use the factory
import { createVorion } from '@vorionsys/sdk';
const vorion = createVorion({ localMode: true });

Agent Registration

const agent = await vorion.registerAgent({
  agentId: 'unique-id',
  name: 'Agent Name',
  capabilities: ['read:*', 'write:documents'],
  observationTier: 'GRAY_BOX',  // Optional
  metadata: { version: '1.0' }, // Optional
});

Action Requests

const result = await agent.requestAction({
  type: 'read',
  resource: 'documents/report.pdf',
  parameters: { format: 'json' }, // Optional
});

// result: {
//   allowed: boolean,
//   tier: 'GREEN' | 'YELLOW' | 'RED',
//   reason: string,
//   proofId: string,
//   constraints?: string[],
//   processingTimeMs?: number,  // Remote mode only
// }

Trust Signals

// Report successful action
await agent.reportSuccess('read');

// Report failed action
await agent.reportFailure('write', 'Permission denied by upstream service');

// Get current trust info
const trust = await agent.getTrustInfo();
// { score: 750, tierName: 'Standard', tierNumber: 4, observationTier: 'GRAY_BOX' }

Utilities

vorion.isLocalMode();      // boolean
vorion.getAgent('id');     // Agent | undefined
vorion.getAllAgents();     // Agent[]
await vorion.healthCheck(); // { status, version }

Trust Tiers

Agents start at T3 (Monitored, score 500) in local mode. Trust adjusts based on signals:

| Tier | Score | Name | Constraints | |------|-------|------|-------------| | T0-T1 | 0-349 | Sandbox/Observed | rate_limit:10/min, audit:full, sandbox:true | | T2-T3 | 350-649 | Provisional/Monitored | rate_limit:100/min, audit:standard | | T4-T5 | 650-875 | Standard/Trusted | rate_limit:1000/min, audit:light | | T6-T7 | 876-1000 | Certified/Autonomous | No constraints |

TypeScript

import type {
  VorionConfig,
  AgentOptions,
  ActionResult,
  TrustInfo,
  TrustTier,
  DecisionTier,
  AgentCredentials,
  Action,
  TrustSignal,
} from '@vorionsys/sdk';

License

MIT