@vaultysclaw/agent-runtime 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 François-Xavier Thoorens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @vaultysclaw/agent-runtime
+
+Generic agent protocol runtime: the transport, authentication, and intent-routing
+layer that lets a process connect to a VaultysClaw control plane as an agent. It is
+deliberately framework-agnostic so it can be embedded in different hosts (the
+full agent controller, the MCP gateway, custom integrations).
+
+## Responsibilities
+
+- **Connection** — WebSocket / WebRTC (PeerJS) transport to the control plane.
+- **Authentication** — VaultysId challenge/response handshake.
+- **Intent routing** — receive `intent` messages, dispatch to a handler, send
+  `result` messages back.
+- **Protocol framing** — msgpack encoding of the shared channel envelope.
+
+## Usage
+
+Consumed as a workspace library (ESM):
+
+```typescript
+import { /* runtime APIs */ } from "@vaultysclaw/agent-runtime";
+```
+
+See `packages/mcp-gateway` for a minimal embedding example and
+`packages/agent-controller` for the full-featured host.
+
+## Scripts
+
+```bash
+pnpm build        # compile to dist/ with tsc
+pnpm type-check
+```
+
+## Related
+
+- [`@vaultysclaw/shared`](../shared) — message types this runtime speaks
+- [`@vaultysclaw/agent-controller`](../agent-controller) — full agent host built on top
+- [`@vaultysclaw/mcp-gateway`](../mcp-gateway) — MCP server built on top

package/dist/base-agent.d.ts

@@ -0,0 +1,182 @@
+/**
+ * BaseAgentRuntime — abstract protocol layer for VaultysClaw agents.
+ *
+ * Handles WebSocket/WebRTC connection, VaultysId auth handshake, intent
+ * routing, policy enforcement, peer catalog management, and delegation
+ * verification.  Subclasses implement `executeIntent` and `executeChat`
+ * to add LLM/tool execution on top.
+ *
+ * Emitted events (same contract as the original Agent class):
+ *   status_changed  { status: AgentStatus }
+ *   log             { level: 'info'|'warn'|'error'|'debug', message: string, data?: unknown }
+ *   heartbeat       { uptime: number }
+ *   intent_received { intentId: string; action: string; params: Record<string, unknown> }
+ *   intent_result   { intentId: string; status: 'success'|'failed'; output?: unknown; error?: string }
+ *   config_updated  { source: 'remote'|'env'; provider?: string; model?: string }
+ */
+import EventEmitter from "events";
+import { WebSocket } from "ws";
+import { VaultysId } from "@vaultys/id";
+import { type WSMessage, type WSAuthCompletePayload, type WSDelegationUpdatePayload, type WSLlmConfigPayload, type ExecutionResult, type AgentCapability, type AgentPeerGrant, type WSSkillsConfigPayload, type ResourceLimits, type ChatMessageEntry } from "@vaultysclaw/shared";
+type ChatErrorCode = "llm_unavailable" | "llm_error" | "agent_offline";
+import { type AgentRuntimeConfig } from "./config.js";
+import { PeerManager } from "./peer-manager.js";
+export type AgentStatus = "initializing" | "connecting" | "pending_approval" | "connected" | "disconnected";
+export interface LogEntry {
+    ts: string;
+    level: "info" | "warn" | "error" | "debug";
+    message: string;
+    data?: unknown;
+}
+export interface IntentEntry {
+    intentId: string;
+    action: string;
+    params: Record<string, unknown>;
+    status: "pending" | "success" | "failed";
+    output?: unknown;
+    error?: string;
+    receivedAt: string;
+    completedAt?: string;
+}
+export interface AgentInfo {
+    id: string;
+    name: string;
+    version: string;
+    status: AgentStatus;
+    capabilities: AgentCapability[];
+    uptime: number;
+    lastHeartbeat: string | null;
+    recentLogs: LogEntry[];
+    recentIntents: IntentEntry[];
+}
+declare class RingBuffer<T> {
+    private readonly max;
+    private buf;
+    constructor(max: number);
+    push(item: T): void;
+    toArray(): T[];
+}
+export declare abstract class BaseAgentRuntime extends EventEmitter {
+    protected config: AgentRuntimeConfig;
+    protected vaultysId: VaultysId | null;
+    protected ws: WebSocket | null;
+    /** Active PeerJS DataConnection (when connecting via WebRTC instead of WebSocket). */
+    protected peerjsConn: import("peerjs").DataConnection | null;
+    /** Underlying PeerJS Peer instance (kept for cleanup on reconnect). */
+    private peerjsPeer;
+    private heartbeatTimer;
+    private reconnectTimer;
+    protected stopped: boolean;
+    /** Consecutive failed connection attempts — drives exponential backoff. */
+    private reconnectAttempts;
+    protected _status: AgentStatus;
+    protected id: string;
+    protected capabilities: AgentCapability[];
+    private startedAt;
+    protected lastHeartbeat: Date | null;
+    private authChallenger;
+    private authSessionId;
+    private reAuthPending;
+    protected serverPublicKey: Buffer | null;
+    protected peerManager: PeerManager | null;
+    protected peerCatalog: AgentPeerGrant[];
+    protected _peerListenerStarted: boolean;
+    protected logBuffer: RingBuffer<LogEntry>;
+    protected intentBuffer: RingBuffer<IntentEntry>;
+    protected _tokenUsageSinceLastSync: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    protected _tokenUsageTotal: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    protected resourceLimits: ResourceLimits | null;
+    protected policyId: string | null;
+    protected policyExpiresAt: string | null;
+    /** Rolling hourly request counter for maxRequestsPerHour enforcement. */
+    protected _requestsThisHour: {
+        count: number;
+        hourStart: number;
+    };
+    constructor(config: AgentRuntimeConfig);
+    abstract executeIntent(action: string, params: Record<string, unknown>, callerDid?: string, intentId?: string): Promise<unknown>;
+    abstract executeChat(messages: ChatMessageEntry[], conversationId: string, sendChunk: (chunk: string, done?: boolean, isError?: boolean, errorCode?: ChatErrorCode) => void): Promise<void>;
+    protected getDailyTokenUsageForBudget(): {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    protected onAuthComplete(_payload: WSAuthCompletePayload): Promise<void>;
+    protected onDelegationUpdate(_payload: WSDelegationUpdatePayload): Promise<void>;
+    protected onPeerCatalogUpdated(_grants: AgentPeerGrant[]): Promise<void>;
+    protected onLlmConfig(_config: WSLlmConfigPayload): Promise<void>;
+    protected onSkillsConfig(_payload: WSSkillsConfigPayload): Promise<void>;
+    protected onKnowledgeSources(_sources: unknown[]): Promise<void>;
+    protected handleGetChatSessions(_msg: WSMessage): Promise<void>;
+    protected handleGetChatHistory(_msg: WSMessage): Promise<void>;
+    protected handleToolApprovalResponse(_msg: WSMessage): Promise<void>;
+    protected handleTaskEnqueue(_msg: WSMessage): Promise<void>;
+    protected handleScheduleUpdate(_msg: WSMessage): Promise<void>;
+    protected handleScheduleDelete(_msg: WSMessage): Promise<void>;
+    protected handleKnowledgeSync(_msg: WSMessage): Promise<void>;
+    start(): Promise<void>;
+    stop(): void;
+    getInfo(): AgentInfo;
+    /**
+     * Returns the agent's DID (stable identifier derived from its VaultysId).
+     * Falls back to the control-plane-assigned id if VaultysId is not yet loaded.
+     */
+    getDid(): string;
+    getStatus(): AgentStatus;
+    /** Returns the current peer catalog (agents this agent has grants to talk to). */
+    getPeerCatalog(): AgentPeerGrant[];
+    /**
+     * Invoke a peer agent via WebRTC.
+     * Throws if the peer manager is not ready or the target is not in the catalog.
+     */
+    invokePeer(targetDid: string, action: string, params?: Record<string, unknown>): Promise<unknown>;
+    getRecentLogs(limit?: number): LogEntry[];
+    getRecentIntents(limit?: number): IntentEntry[];
+    protected setStatus(s: AgentStatus): void;
+    protected log(level: LogEntry["level"], message: string, data?: unknown): void;
+    protected initVaultysId(identityPath: string): Promise<VaultysId>;
+    protected connect(): void;
+    /**
+     * Schedule a reconnect attempt with exponential backoff + ±20 % jitter.
+     * Delay starts at 2 s and doubles each attempt, capped at 60 s.
+     * Resets to 0 after a successful authentication.
+     */
+    private scheduleReconnect;
+    private resetReconnectBackoff;
+    private connectViaPeerjs;
+    private connectViaWs;
+    protected send(message: WSMessage): void;
+    protected sendHeartbeat(): void;
+    protected sendResult(intentId: string, result: ExecutionResult): void;
+    protected sendAck(messageId: string, success: boolean, reason?: string): void;
+    protected handleMessage(data: string): void;
+    private handleAuthChallenge;
+    private startAuthHandshake;
+    private handleAuthComplete;
+    private handleAuthFailed;
+    private handleRegistrationPending;
+    private handleRegistrationApproved;
+    private handleRegistrationRejected;
+    private handleUpdateCapabilities;
+    private handleIntent;
+    private handleChatMessageProtocol;
+    private handleDelegationUpdateMsg;
+    private handleAgentPeerCatalog;
+    /**
+     * Verify an intent message's ECDSA signature produced by the control plane.
+     */
+    private verifyIntentSignature;
+    protected verifyUserDelegation(userDid: string, capability: string): Promise<boolean>;
+    /**
+     * @deprecated The `policy_update` message is superseded by the cert-reissue path.
+     */
+    private handlePolicyUpdate;
+    protected getPeerjsServerUrl(): string | null;
+}
+export {};
+//# sourceMappingURL=base-agent.d.ts.map

package/dist/base-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-agent.d.ts","sourceRoot":"","sources":["../src/base-agent.ts"],"names":[],"mappings":"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"}