Skip to content

README.md

Latest commit

 

History

History
99 lines (70 loc) · 2.88 KB

README.md

File metadata and controls

99 lines (70 loc) · 2.88 KB
Raw

Adrian TypeScript SDK

Monorepo for the Adrian TypeScript SDK. The core package owns the event pipeline: event pairing, PII redaction, JSONL logging, WebSocket streaming, policy verdicts, and shared capture helpers.

Requirements

Node.js 18 or later.

Packages

Package npm name Install Import
Core @secureagentics/adrian npm install @secureagentics/adrian import { adrian } from "@secureagentics/adrian"
OpenAI @secureagentics/adrian-openai npm install @secureagentics/adrian-openai openai import { adrian } from "@secureagentics/adrian-openai"

Environment

Explicit init() options take precedence over environment variables.

Variable Description
ADRIAN_API_KEY API key used for WebSocket authentication
ADRIAN_LOG_FILE Local JSONL log path (default: events.jsonl)
ADRIAN_WS_URL WebSocket endpoint (default: ws://localhost:8080/ws)
ADRIAN_SESSION_ID Session identifier for grouping events
ADRIAN_BLOCK_TIMEOUT Seconds to wait for a BLOCK-mode verdict before fail-open (default: 30)
ADRIAN_REPLAY_BUFFER_FRAMES WebSocket replay buffer size (default: 1000)

Policy and BLOCK mode

When connected over WebSocket and the dashboard policy is in BLOCK or HITL mode, the SDK waits for backend verdicts on tool calls proposed by an LLM turn. In BLOCK mode, if no verdict arrives within blockTimeout seconds, the SDK fail-open and allows execution (matching the Python SDK). Dashboard-configurable failure policy is planned for a later release.

Manual callback wiring

For custom integrations, pair an LLM start and end with the same runId:

import { randomUUID } from "node:crypto";
import { adrian } from "@secureagentics/adrian";

await adrian.init({ wsUrl: null });

const handler = adrian.getHandler();
const runId = randomUUID();

await handler?.handleChatModelStart(
  { name: "custom-model" },
  [[{ role: "user", content: "Hello" }]],
  runId,
);

await handler?.handleLLMEnd(
  {
    output: "Hi there",
    toolCalls: [],
    usage: { promptTokens: 1, completionTokens: 2, totalTokens: 3 },
  },
  runId,
);

await adrian.shutdown();

Manual tool events work the same way:

const toolRunId = randomUUID();

await handler?.handleToolStart(
  { name: "lookup_user" },
  JSON.stringify({ userId: "user_123" }),
  toolRunId,
  undefined,
  { tool_call_id: "call_123", metadata: { source: "custom-integration" } },
);

await handler?.handleToolEnd(JSON.stringify({ ok: true }), toolRunId);

Subpath export

@secureagentics/adrian/capture exposes shared LLM capture helpers used internally by provider packages.

Development

From this directory:

npm install
npm run build
npm test

Build or test the core package only:

npm run build -w @secureagentics/adrian
npm test -w @secureagentics/adrian