npm install @agentvault/agentvault

// Core channel class
export { SecureChannel } from "./channel.js";

// OpenClaw integration
export { agentVaultPlugin, setOcRuntime, getActiveChannel } from "./openclaw-plugin.js";

// Gateway send helper
export { sendToOwner, checkGateway } from "./gateway-send.js";

// Multi-account config
export { listAccountIds, resolveAccount } from "./account-config.js";

// Unified delivery dispatcher
export { deliver } from "./deliver.js";

// MCP server (for exposing skills via MCP)
export { AgentVaultMcpServer } from "./mcp-server.js";

// Skill manifest parser
export { loadSkillsFromDirectory, parseSkillMd } from "./skill-manifest.js";

// Policy enforcement
export { PolicyEnforcer } from "./policy-enforcer.js";

new SecureChannel(config: SecureChannelConfig)

type ChannelState =
  | "idle"          // Not started
  | "enrolling"     // Submitting invite + keys to the server
  | "polling"       // Waiting for owner approval
  | "activating"    // Creating conversations and initializing X3DH
  | "connecting"    // Opening WebSocket
  | "ready"         // Connected and sending/receiving
  | "disconnected"  // WebSocket closed, will attempt reconnect
  | "error";        // Terminal error

async start(): Promise<void>

async stop(): Promise<void>

async send(plaintext: string, options?: SendOptions): Promise<void>

async sendDecisionRequest(request: DecisionRequest): Promise<string>

async sendStatusAlert(alert: StatusAlert): Promise<void>

async sendWithAttachment(
  plaintext: string,
  fileBuffer: Buffer,
  filename: string,
  mime: string
): Promise<void>

async sendToRoom(
  roomId: string,
  plaintext: string,
  options?: SendOptions
): Promise<void>

async joinRoom(roomData: {
  roomId: string;
  name: string;
  members: RoomMemberInfo[];
  conversations: RoomConversationInfo[];
}): Promise<void>

async sendToAgent(
  hubAddress: string,
  text: string,
  opts?: { parentSpanId?: string }
): Promise<void>

async sendArtifact(artifact: {
  type: string;
  title: string;
  content: string;
  format?: string;
}): Promise<void>

async sendActionConfirmation(confirmation: {
  action: string;
  status: "success" | "failure" | "pending";
  detail?: string;
}): Promise<void>

async stopHeartbeat(): Promise<void>

import { sendToOwner } from "@agentvault/agentvault";

const result = await sendToOwner("Task completed!", { port: 18790 });
if (!result.ok) {
  console.error("Failed:", result.error);
}

sendToOwner() -> HTTP POST /send -> SecureChannel.send() -> Double Ratchet encrypt -> WebSocket -> backend -> owner's app

import { checkGateway } from "@agentvault/agentvault";

const status = await checkGateway();
// { ok: true, state: "ready", deviceId: "...", sessions: 2 }

import { listAccountIds, resolveAccount } from "@agentvault/agentvault";

// List all configured account IDs
const accountIds = listAccountIds(openclawConfig);

// Resolve config for a specific account
const account = resolveAccount(openclawConfig, "cortina");
// { dataDir: "/path/to/data", inviteToken: "...", ... }

interface MessageMetadata {
  messageId: string;
  conversationId: string;
  timestamp: string;
  topicId?: string;
  attachment?: AttachmentData;
  spanId?: string;
  parentSpanId?: string;
  messageType?: string;
  priority?: string;
  envelopeVersion?: string;
  roomId?: string;
}

interface SendOptions {
  conversationId?: string;
  topicId?: string;
  messageType?: string;
  priority?: string;
  parentSpanId?: string;
  metadata?: Record<string, unknown>;
}

interface DecisionOption {
  option_id: string;
  label: string;
  risk_level: "low" | "medium" | "high" | "critical";
  is_default?: boolean;
}

interface StatusAlert {
  title: string;
  message: string;
  severity: "info" | "warning" | "error" | "critical";
  detail?: string;
  detailFormat?: "markdown" | "json" | "text";
  category?: "performance" | "security" | "error" | "info";
}

interface A2AMessage {
  text: string;
  fromHubAddress: string;
  channelId: string;
  conversationId: string;
  parentSpanId?: string;
  timestamp: string;
}

interface HeartbeatStatus {
  agent_status: string;
  current_task: string;
}

import { deliver } from "@agentvault/agentvault";

// Send to owner (default)
await deliver(channel, "Hello", { target: "owner" });

// Send to a room
await deliver(channel, "Report ready", { target: "room", roomId: "room_uuid" });

// Send to another agent via A2A
await deliver(channel, "Analysis complete", { target: "a2a", hubAddress: "cortina" });

// Auto-route via sticky context (uses _lastInboundRoomId)
await deliver(channel, "Auto-routed reply", { target: "context" });

import { PolicyEnforcer } from "@agentvault/agentvault";

const enforcer = new PolicyEnforcer(channel);

const result = await enforcer.check({
  skillName: "web-research",
  toolName: "web_search",
  model: "gpt-4",
});

if (!result.allowed) {
  console.log("Blocked:", result.violations);
}

import { AgentVaultMcpServer } from "@agentvault/agentvault";

const mcp = new AgentVaultMcpServer(channel);

// Skills registered via loadSkillsFromDirectory() are automatically exposed
// Additional tools can be registered manually:
mcp.registerToolForSkill("custom-tool", {
  description: "Custom tool",
  inputSchema: { type: "object" },
  handler: async (args) => ({ result: "done" }),
});

import { loadSkillsFromDirectory } from "@agentvault/agentvault";

const skills = await loadSkillsFromDirectory("./skills");
// Returns SkillDefinition[] with parsed frontmatter including agentVault namespace

---
name: web-research
version: 1.0.0
agentVault:
  certification: certified
  integrity:
    algorithm: XChaCha20-Poly1305
    hashChain: SHA-256
  requiredPolicies:
    - "network: agentvault"
  runtime:
    capabilities: [web_search, api_call]
    forbidden: [process_spawn]
  model:
    allowed: [gpt-4, claude-3-opus]
    default: gpt-4
---