@aria-cli/tools 1.0.0

package/src/mcp/jsonrpc.ts

@@ -0,0 +1,195 @@
+/**
+ * JSON-RPC 2.0 Client for MCP
+ *
+ * Handles newline-delimited JSON over stdio streams.
+ */
+
+import { Readable, Writable } from "stream";
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+
+interface JSONRPCRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+interface JSONRPCResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+interface JSONRPCNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+
+type PendingRequest = {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timeout: NodeJS.Timeout;
+};
+
+export class JSONRPCClient extends EventEmitter {
+  private stdin?: Writable;
+  private stdout?: Readable;
+  private pending: Map<string, PendingRequest> = new Map();
+  private buffer = "";
+  private requestTimeout: number;
+
+  constructor(options: { timeout?: number } = {}) {
+    super();
+    this.requestTimeout = options.timeout ?? 30000;
+  }
+
+  /**
+   * Connect to a process via stdio streams
+   */
+  connect(stdin: Writable, stdout: Readable): void {
+    this.stdin = stdin;
+    this.stdout = stdout;
+
+    stdout.on("data", (chunk: Buffer) => {
+      this.buffer += chunk.toString();
+      this.processBuffer();
+    });
+
+    stdout.on("error", (error) => {
+      this.emit("error", error);
+    });
+
+    stdout.on("end", () => {
+      this.emit("close");
+    });
+  }
+
+  private processBuffer(): void {
+    let newlineIdx: number;
+    while ((newlineIdx = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, newlineIdx).trim();
+      this.buffer = this.buffer.slice(newlineIdx + 1);
+
+      if (line) {
+        try {
+          this.handleMessage(JSON.parse(line));
+        } catch (e) {
+          this.emit("error", new Error(`Invalid JSON: ${line}`));
+        }
+      }
+    }
+  }
+
+  private handleMessage(msg: unknown): void {
+    // Ignore messages that aren't valid JSON-RPC 2.0
+    if (
+      typeof msg !== "object" ||
+      msg === null ||
+      !("jsonrpc" in msg) ||
+      (msg as { jsonrpc: unknown }).jsonrpc !== "2.0"
+    )
+      return;
+
+    const rpcMsg = msg as JSONRPCResponse | JSONRPCNotification;
+
+    // Response to our request
+    if ("id" in rpcMsg && (rpcMsg as JSONRPCResponse).id !== undefined) {
+      const response = rpcMsg as JSONRPCResponse;
+      const pending = this.pending.get(String(response.id));
+      if (pending) {
+        this.pending.delete(String(response.id));
+        clearTimeout(pending.timeout);
+
+        if (response.error) {
+          pending.reject(
+            new Error(`${response.error.code}: ${response.error.message}`),
+          );
+        } else {
+          pending.resolve(response.result);
+        }
+      }
+      return;
+    }
+
+    // Notification from server
+    if ("method" in rpcMsg) {
+      const notification = rpcMsg as JSONRPCNotification;
+      this.emit(notification.method, notification.params);
+      this.emit("notification", {
+        method: notification.method,
+        params: notification.params,
+      });
+    }
+  }
+
+  /**
+   * Send a request and wait for response
+   */
+  async request<T = unknown>(method: string, params?: unknown): Promise<T> {
+    if (!this.stdin) {
+      throw new Error("Not connected");
+    }
+
+    const id = randomUUID();
+
+    const message: JSONRPCRequest = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`Request timeout: ${method}`));
+        }
+      }, this.requestTimeout);
+
+      this.pending.set(id, {
+        resolve: resolve as (v: unknown) => void,
+        reject,
+        timeout,
+      });
+      this.send(message);
+    });
+  }
+
+  /**
+   * Send a notification (no response expected)
+   */
+  notify(method: string, params?: unknown): void {
+    const message: JSONRPCNotification = {
+      jsonrpc: "2.0",
+      method,
+      params,
+    };
+    this.send(message);
+  }
+
+  private send(message: JSONRPCRequest | JSONRPCNotification): void {
+    if (!this.stdin) {
+      throw new Error("Not connected");
+    }
+    this.stdin.write(JSON.stringify(message) + "\n");
+  }
+
+  /**
+   * Close and cleanup
+   */
+  close(): void {
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Connection closed"));
+    }
+    this.pending.clear();
+    this.buffer = "";
+    this.stdin = undefined;
+    this.stdout?.removeAllListeners();
+    this.stdout = undefined;
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,199 @@
+/**
+ * MCP (Model Context Protocol) Types
+ *
+ * Protocol version: 2024-11-05
+ * https://modelcontextprotocol.io
+ */
+
+import type { JSONSchema7 } from "json-schema";
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * MCP server configuration
+ */
+export interface MCPServerConfig {
+  /** Unique server identifier */
+  name: string;
+  /** Transport type (defaults to 'stdio' if omitted) */
+  transport?: "stdio" | "sse";
+  /** Command to spawn (stdio transport) */
+  command?: string;
+  /** Command arguments */
+  args?: string[];
+  /** SSE endpoint URL */
+  url?: string;
+  /** Environment variables for server process */
+  env?: Record<string, string>;
+  /** Configuration scope */
+  scope?: "project" | "global";
+}
+
+// ============================================================================
+// Protocol Messages
+// ============================================================================
+
+/**
+ * Server capabilities from initialize response
+ */
+export interface MCPCapabilities {
+  tools?: { listChanged?: boolean };
+  resources?: { subscribe?: boolean; listChanged?: boolean };
+  prompts?: { listChanged?: boolean };
+  logging?: Record<string, never>;
+}
+
+/**
+ * Initialize request params
+ */
+export interface MCPInitializeParams {
+  protocolVersion: string;
+  capabilities: {
+    roots?: { listChanged?: boolean };
+    sampling?: Record<string, never>;
+  };
+  clientInfo: {
+    name: string;
+    version: string;
+  };
+}
+
+/**
+ * Initialize response
+ */
+export interface MCPInitializeResult {
+  protocolVersion: string;
+  capabilities: MCPCapabilities;
+  serverInfo: {
+    name: string;
+    version: string;
+  };
+}
+
+// ============================================================================
+// Tools
+// ============================================================================
+
+/**
+ * Tool definition from tools/list
+ */
+export interface MCPTool {
+  name: string;
+  description?: string;
+  inputSchema: JSONSchema7;
+  annotations?: {
+    readOnlyHint?: boolean;
+  };
+}
+
+/**
+ * Tool call request params
+ */
+export interface MCPToolCallParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+/**
+ * Content types in tool results
+ */
+export type MCPContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | { type: "resource"; resource: { uri: string; mimeType?: string; text?: string } };
+
+/**
+ * Tool call result
+ */
+export interface MCPToolCallResult {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+// ============================================================================
+// Resources
+// ============================================================================
+
+/**
+ * Resource definition from resources/list
+ */
+export interface MCPResource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * Resource content from resources/read
+ */
+export interface MCPResourceContent {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+}
+
+/**
+ * Resources read result
+ */
+export interface MCPResourceReadResult {
+  contents: MCPResourceContent[];
+}
+
+// ============================================================================
+// Prompts
+// ============================================================================
+
+/**
+ * Prompt definition from prompts/list
+ */
+export interface MCPPrompt {
+  name: string;
+  description?: string;
+  arguments?: Array<{
+    name: string;
+    description?: string;
+    required?: boolean;
+  }>;
+}
+
+/**
+ * Prompt message from prompts/get
+ */
+export interface MCPPromptMessage {
+  role: "user" | "assistant";
+  content: MCPContent;
+}
+
+/**
+ * Prompts get result
+ */
+export interface MCPPromptGetResult {
+  description?: string;
+  messages: MCPPromptMessage[];
+}
+
+// ============================================================================
+// Notifications
+// ============================================================================
+
+/**
+ * Log message from server
+ */
+export interface MCPLogMessage {
+  level: "debug" | "info" | "warning" | "error";
+  logger?: string;
+  data?: unknown;
+}
+
+/**
+ * Progress notification
+ */
+export interface MCPProgress {
+  progressToken: string | number;
+  progress: number;
+  total?: number;
+}

package/src/network-control-adapter.ts

@@ -0,0 +1,88 @@
+import { SigningPublicKeySchema, type SigningPublicKey } from "./network-runtime/index.js";
+import type {
+  NetworkControlRef,
+  NetworkManagerPeerInfo,
+  NetworkManagerRef,
+  NetworkManagerStatusView,
+  NetworkPeerView,
+  NetworkStatusView,
+} from "./types.js";
+
+export function toNetworkPeerView(peer: NetworkManagerPeerInfo): NetworkPeerView | null {
+  const parsedSigningPublicKey = SigningPublicKeySchema.safeParse(peer.signingPublicKey?.trim());
+  if (
+    !parsedSigningPublicKey.success ||
+    typeof peer.nodeId !== "string" ||
+    peer.nodeId.length === 0
+  ) {
+    return null;
+  }
+  const signingPublicKey = parsedSigningPublicKey.data;
+  return {
+    nodeId: peer.nodeId,
+    transportPublicKey: peer.publicKey,
+    displayNameSnapshot: peer.name,
+    endpointHost: peer.endpointHost,
+    endpointPort: peer.endpointPort,
+    controlEndpoint: peer.controlEndpoint ?? null,
+    signingPublicKey,
+    status: peer.status,
+    membershipStatus: peer.membershipStatus ?? peer.status,
+    routeOwnership: peer.routeOwnership,
+    routeOwnerNodeId: peer.routeOwnerNodeId ?? null,
+    sessionState: peer.sessionState,
+    deliveryReadiness: peer.deliveryReadiness,
+    lastHandshake: peer.lastHandshake,
+    createdAt: peer.createdAt,
+    endpointRevision: peer.endpointRevision ?? 0,
+    updatedAt: peer.updatedAt ?? peer.createdAt,
+  };
+}
+
+export function toNetworkStatusView(status: NetworkManagerStatusView): NetworkStatusView {
+  const parsedSigningPublicKey = SigningPublicKeySchema.safeParse(status.signingPublicKey?.trim());
+  const signingPublicKey: SigningPublicKey | null = parsedSigningPublicKey.success
+    ? parsedSigningPublicKey.data
+    : null;
+  return {
+    configured: status.configured,
+    nodeId: status.nodeId,
+    principalFingerprint: status.principalFingerprint,
+    transportPublicKey: status.publicKey,
+    listenPort: status.listenPort,
+    externalEndpoint: status.externalEndpoint,
+    activePeers: status.activePeers,
+    totalPeers: status.totalPeers,
+    connectedPeers: status.connectedPeers,
+    handshakingPeers: status.handshakingPeers,
+    queueOnlyPeers: status.queueOnlyPeers,
+    supersededPeers: status.supersededPeers,
+    signingPublicKey,
+  };
+}
+
+export function toNetworkControlRef(
+  networkManager?: NetworkManagerRef,
+): NetworkControlRef | undefined {
+  if (!networkManager) {
+    return undefined;
+  }
+
+  return {
+    invite(displayName, options) {
+      return networkManager.invite(displayName, options);
+    },
+    revokePeer(nodeId) {
+      return networkManager.revokePeer(nodeId);
+    },
+    listPeers() {
+      return networkManager.listPeers().flatMap((peer) => {
+        const projected = toNetworkPeerView(peer);
+        return projected ? [projected] : [];
+      });
+    },
+    status() {
+      return toNetworkStatusView(networkManager.status());
+    },
+  };
+}

package/src/network-runtime/address-types.ts

@@ -0,0 +1,218 @@
+import { z } from "zod";
+
+const NonEmptyStringSchema = z.string().trim().min(1);
+
+/**
+ * Stable durable identity for a node.
+ * Semantic rules are enforced by the runtime cutover plan; the contract layer
+ * starts by making the shape canonical everywhere.
+ */
+export const NodeIdSchema = NonEmptyStringSchema.brand<"NodeId">();
+export type NodeId = z.infer<typeof NodeIdSchema>;
+
+/** One boot of a given node runtime. */
+export const RuntimeIdSchema = NonEmptyStringSchema.brand<"RuntimeId">();
+export type RuntimeId = z.infer<typeof RuntimeIdSchema>;
+
+export const NodeMetadataSchema = z.object({
+  nodeId: NodeIdSchema,
+  createdAt: NonEmptyStringSchema,
+  schemaVersion: z.number().int().positive(),
+  migratedFromLegacy: z.boolean(),
+});
+export type NodeMetadata = z.infer<typeof NodeMetadataSchema>;
+
+/** Monotonic publication revision for externally visible runtime advertisements. */
+export const PublicationRevisionSchema = z.number().int().nonnegative();
+export type PublicationRevision = z.infer<typeof PublicationRevisionSchema>;
+
+/** Monotonic endpoint revision for register/discovery refreshes. */
+export const EndpointRevisionSchema = z.number().int().nonnegative();
+export type EndpointRevision = z.infer<typeof EndpointRevisionSchema>;
+
+/** Monotonic generation for peer-binding continuity transitions. */
+export const BindingGenerationSchema = z.number().int().nonnegative();
+export type BindingGeneration = z.infer<typeof BindingGenerationSchema>;
+
+/** Monotonic generation for revocation precedence and continuity conflict checks. */
+export const RevocationGenerationSchema = z.number().int().nonnegative();
+export type RevocationGeneration = z.infer<typeof RevocationGenerationSchema>;
+
+/** How a local operator confirmed a revocation decision. */
+export const RevocationOperatorConfirmationSchema = z.enum([
+  "local_operator_confirmed",
+  "remote_capability_authenticated",
+]);
+export type RevocationOperatorConfirmation = z.infer<typeof RevocationOperatorConfirmationSchema>;
+
+/** Structured local authority record for a peer revocation decision. */
+export const RevocationDecisionSchema = z.object({
+  localNodeId: NodeIdSchema,
+  targetNodeId: NodeIdSchema,
+  revocationGeneration: RevocationGenerationSchema,
+  operatorConfirmation: RevocationOperatorConfirmationSchema,
+});
+export type RevocationDecision = z.infer<typeof RevocationDecisionSchema>;
+
+/** Monotonic owner generation for runtime ownership records. */
+export const OwnerGenerationSchema = z.number().int().positive();
+export type OwnerGeneration = z.infer<typeof OwnerGenerationSchema>;
+
+/** Monotonic revision for durable delivery lifecycle state transitions. */
+export const DeliveryLifecycleRevisionSchema = z.number().int().nonnegative();
+export type DeliveryLifecycleRevision = z.infer<typeof DeliveryLifecycleRevisionSchema>;
+
+export const RuntimeOwnerRecordSchema = z
+  .object({
+    schemaVersion: z.number().int().positive(),
+    nodeId: NodeIdSchema,
+    ariaHome: NonEmptyStringSchema,
+    runtimePid: z.number().int().positive(),
+    runtimeId: RuntimeIdSchema,
+    displayNameSnapshot: NonEmptyStringSchema.optional(),
+    runtimeSocket: NonEmptyStringSchema,
+    startedAt: NonEmptyStringSchema,
+    lastHeartbeat: NonEmptyStringSchema,
+    ownerGeneration: OwnerGenerationSchema,
+  })
+  .strict();
+export type RuntimeOwnerRecord = z.infer<typeof RuntimeOwnerRecordSchema>;
+
+/** One attached local client of the runtime. */
+export const ClientIdSchema = NonEmptyStringSchema.brand<"ClientId">();
+export type ClientId = z.infer<typeof ClientIdSchema>;
+
+/** Durable principal fingerprint (SHA-256 hex of signing public key DER). Signing-key evidence only. */
+export const PrincipalFingerprintSchema = NonEmptyStringSchema.brand<"PrincipalFingerprint">();
+export type PrincipalFingerprint = z.infer<typeof PrincipalFingerprintSchema>;
+
+/** Transport public key / transport identity for a peer. */
+export const PeerTransportIdSchema = NonEmptyStringSchema.brand<"PeerTransportId">();
+export type PeerTransportId = z.infer<typeof PeerTransportIdSchema>;
+
+/** TLS CA certificate fingerprint (SHA-256 hex of CA cert DER). Certificate-authority evidence only — distinct from signing-key evidence. */
+export const TlsCaFingerprintSchema = NonEmptyStringSchema.brand<"TlsCaFingerprint">();
+export type TlsCaFingerprint = z.infer<typeof TlsCaFingerprintSchema>;
+
+/** Local-only loopback TLS SAN identity used for same-machine control attachment. */
+export const LoopbackTlsIdentitySchema = NonEmptyStringSchema.brand<"LoopbackTlsIdentity">();
+export type LoopbackTlsIdentity = z.infer<typeof LoopbackTlsIdentitySchema>;
+/** Base64-encoded signing public key material crossing runtime/shared boundaries. */
+export const SigningPublicKeySchema = NonEmptyStringSchema.brand<"SigningPublicKey">();
+export type SigningPublicKey = z.infer<typeof SigningPublicKeySchema>;
+
+/** Explicit network transport endpoint advertisement. */
+export const TransportEndpointAdvertisementSchema = z.object({
+  host: NonEmptyStringSchema,
+  port: z.number().int().min(1).max(65535),
+});
+export type TransportEndpointAdvertisement = z.infer<typeof TransportEndpointAdvertisementSchema>;
+
+/**
+ * Runtime-owned local inbox addressing.
+ * Same-machine clients are local attachments, not mesh peers.
+ */
+export const InboxAddressSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("node"),
+    nodeId: NodeIdSchema,
+  }),
+  z.object({
+    kind: z.literal("client"),
+    clientId: ClientIdSchema,
+  }),
+]);
+export type InboxAddress = z.infer<typeof InboxAddressSchema>;
+
+/**
+ * Public control-plane endpoint advertisement used by peers for pinned,
+ * mutating requests.
+ */
+export const ControlEndpointAdvertisementSchema = z.object({
+  host: NonEmptyStringSchema,
+  port: z.number().int().min(1).max(65535),
+  tlsCaFingerprint: TlsCaFingerprintSchema,
+  tlsServerIdentity: PrincipalFingerprintSchema,
+  protocolVersion: z.number().int().positive(),
+  endpointRevision: EndpointRevisionSchema.optional(),
+});
+export type ControlEndpointAdvertisement = z.infer<typeof ControlEndpointAdvertisementSchema>;
+
+/**
+ * Remote/public node advertisement. This deliberately excludes local-only
+ * runtime/session identity like RuntimeId.
+ */
+export const NodeAdvertisementSchema = z.object({
+  nodeId: NodeIdSchema,
+  principalFingerprint: PrincipalFingerprintSchema,
+  transportPublicKey: PeerTransportIdSchema,
+  publicationRevision: PublicationRevisionSchema.optional(),
+  controlEndpoint: ControlEndpointAdvertisementSchema.optional(),
+  displayNameSnapshot: NonEmptyStringSchema.optional(),
+});
+export type NodeAdvertisement = z.infer<typeof NodeAdvertisementSchema>;
+
+/**
+ * Local-only runtime registry summary. This is not a remote/public mesh
+ * contract and may include RuntimeId.
+ */
+export const LocalRuntimeSummarySchema = z.object({
+  nodeId: NodeIdSchema,
+  runtimeId: RuntimeIdSchema,
+  lastHeartbeat: NonEmptyStringSchema.optional(),
+  controlEndpoint: ControlEndpointAdvertisementSchema.optional(),
+  displayNameSnapshot: NonEmptyStringSchema.optional(),
+});
+export type LocalRuntimeSummary = z.infer<typeof LocalRuntimeSummarySchema>;
+
+// ── Durable Delivery Handle ────────────────────────────────────────
+
+/**
+ * Branded operation handle for durable delivery.
+ * Produced ONLY by `submitDurable()` — the caller never mints handles.
+ */
+export const DurableDeliveryHandleSchema = NonEmptyStringSchema.brand<"DurableDeliveryHandle">();
+export type DurableDeliveryHandle = z.infer<typeof DurableDeliveryHandleSchema>;
+
+/**
+ * Terminal status types for a durable delivery operation.
+ */
+export const DurableDeliveryResultSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("pending"),
+    queuedAt: z.string(),
+    nextAttemptAt: z.string().optional(),
+    attemptCount: z.number(),
+  }),
+  z.object({
+    status: z.literal("delivered"),
+    deliveredAt: z.string(),
+  }),
+  z.object({
+    status: z.literal("expired"),
+    reason: z.literal("ttl_exceeded"),
+    queuedAt: z.string(),
+    expiredAt: z.string(),
+  }),
+  z.object({
+    status: z.literal("rejected"),
+    reason: z.enum(["recipient_revoked", "recipient_unknown", "envelope_invalid"]),
+  }),
+]);
+export type DurableDeliveryResult = z.infer<typeof DurableDeliveryResultSchema>;
+
+/**
+ * Submit result — returned immediately from `submitDurable()`.
+ */
+export const DurableSubmitResultSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("accepted"),
+    operationId: DurableDeliveryHandleSchema,
+    queuedAt: z.string(),
+  }),
+  z.object({
+    status: z.literal("rejected"),
+    reason: z.enum(["recipient_revoked", "recipient_unknown", "envelope_invalid"]),
+  }),
+]);
+export type DurableSubmitResult = z.infer<typeof DurableSubmitResultSchema>;