@aria-cli/tools 1.0.0

package/tests/network-runtime/runtime-socket-local-control-client.test.ts

@@ -0,0 +1,621 @@
+import * as net from "node:net";
+import { EventEmitter } from "node:events";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createRuntimeSocketAttachedLocalControlClient,
+  createRuntimeSocketLocalControlClient,
+} from "../../src/runtime-socket-local-control-client.js";
+
+const createConnectionMock = vi.fn();
+
+vi.mock("node:net", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:net")>();
+  return {
+    ...actual,
+    createConnection: (...args: Parameters<typeof actual.createConnection>) =>
+      createConnectionMock(...args),
+  };
+});
+
+function installRuntimeSocketMock(
+  runtimeSocket: string,
+  responses: Record<string, unknown>,
+): {
+  requests: Array<{ method: string; payload?: unknown; auth?: unknown }>;
+  restore(): void;
+} {
+  const requests: Array<{ method: string; payload?: unknown; auth?: unknown }> = [];
+  createConnectionMock.mockImplementation((target) => {
+    const requestedPath =
+      typeof target === "string" ? target : typeof target === "object" && target ? target.path : "";
+    if (requestedPath !== runtimeSocket) {
+      const failingSocket = new EventEmitter() as net.Socket;
+      failingSocket.setEncoding = vi.fn();
+      failingSocket.write = vi.fn();
+      failingSocket.end = vi.fn();
+      failingSocket.destroy = vi.fn(() => {
+        failingSocket.emit("close");
+        return failingSocket;
+      });
+      queueMicrotask(() => {
+        failingSocket.emit("error", new Error(`connect ENOENT ${String(requestedPath)}`));
+      });
+      return failingSocket;
+    }
+
+    const socket = new EventEmitter() as net.Socket;
+    socket.setEncoding = vi.fn();
+    socket.write = vi.fn((chunk: string) => {
+      const newlineIndex = chunk.indexOf("\n");
+      const request = JSON.parse(
+        chunk.slice(0, newlineIndex === -1 ? chunk.length : newlineIndex),
+      ) as {
+        id: string;
+        method: string;
+        payload?: unknown;
+        auth?: unknown;
+      };
+      requests.push({ method: request.method, payload: request.payload, auth: request.auth });
+      const payload = responses[request.method];
+      queueMicrotask(() => {
+        socket.emit(
+          "data",
+          `${JSON.stringify({
+            id: request.id,
+            ok: true,
+            payload,
+          })}\n`,
+        );
+        socket.emit("end");
+        socket.emit("close");
+      });
+      return true;
+    });
+    socket.end = vi.fn(() => {
+      socket.emit("end");
+      socket.emit("close");
+      return socket;
+    });
+    socket.destroy = vi.fn(() => {
+      socket.emit("close");
+      return socket;
+    });
+    queueMicrotask(() => {
+      socket.emit("connect");
+    });
+    return socket;
+  });
+
+  return {
+    requests,
+    restore() {
+      createConnectionMock.mockReset();
+    },
+  };
+}
+
+describe("runtime socket local control client", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("creates a LocalControlApi that resolves runtime status over the runtime socket", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    const socketMock = installRuntimeSocketMock(runtimeSocket, {
+      getRuntimeStatus: {
+        nodeId: "node-test-1234",
+        runtimeId: "runtime-test",
+        port: 58291,
+        autonomousLoop: {
+          status: "stopped",
+          intervalMs: null,
+          lastWakeTickAt: null,
+          lastCheckpointResult: "never",
+          safetyPolicySummary: {},
+          ownerClientKind: null,
+        },
+      },
+    });
+
+    try {
+      const client = createRuntimeSocketLocalControlClient({ runtimeSocket });
+
+      await expect(client.getRuntimeStatus()).resolves.toMatchObject({
+        nodeId: "node-test-1234",
+        runtimeId: "runtime-test",
+        port: 58291,
+      });
+      expect(socketMock.requests.map((request) => request.method)).toEqual(["getRuntimeStatus"]);
+    } finally {
+      socketMock.restore();
+    }
+  });
+
+  it("streams runtime events over the runtime socket", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    createConnectionMock.mockImplementation((target) => {
+      const requestedPath =
+        typeof target === "string"
+          ? target
+          : typeof target === "object" && target
+            ? target.path
+            : "";
+      if (requestedPath !== runtimeSocket) {
+        throw new Error(`unexpected socket target: ${String(requestedPath)}`);
+      }
+
+      const socket = new EventEmitter() as net.Socket;
+      socket.setEncoding = vi.fn();
+      socket.write = vi.fn((chunk: string) => {
+        const request = JSON.parse(chunk.trim()) as { id: string; method: string };
+        queueMicrotask(() => {
+          socket.emit(
+            "data",
+            `${JSON.stringify({
+              id: request.id,
+              ok: true,
+              payload: {
+                eventId: "evt-1",
+                nodeId: "node-test-1234",
+                runtimeId: "runtime-test",
+                kind: "durable_send_queued",
+                revision: 1,
+                recordedAt: "2026-03-13T00:00:00.000Z",
+                payload: { messageId: "msg-1" },
+              },
+            })}\n`,
+          );
+        });
+        return true;
+      });
+      socket.end = vi.fn(() => {
+        socket.emit("end");
+        socket.emit("close");
+        return socket;
+      });
+      socket.destroy = vi.fn(() => {
+        socket.emit("close");
+        return socket;
+      });
+      queueMicrotask(() => {
+        socket.emit("connect");
+      });
+      return socket;
+    });
+
+    const client = createRuntimeSocketLocalControlClient({ runtimeSocket });
+    const iterator = client.subscribeRuntimeEvents()[Symbol.asyncIterator]();
+    try {
+      await expect(iterator.next()).resolves.toEqual({
+        done: false,
+        value: {
+          eventId: "evt-1",
+          nodeId: "node-test-1234",
+          runtimeId: "runtime-test",
+          kind: "durable_send_queued",
+          revision: 1,
+          recordedAt: "2026-03-13T00:00:00.000Z",
+          payload: { messageId: "msg-1" },
+        },
+      });
+    } finally {
+      await iterator.return?.();
+    }
+  });
+
+  it("sends attached-client auth for attached-client directory methods", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    const socketMock = installRuntimeSocketMock(runtimeSocket, {
+      listAttachedClients: [
+        {
+          clientId: "client-other",
+          clientKind: "tui",
+          displayLabel: "Other terminal",
+          self: false,
+          attachedAt: "2026-03-13T00:00:00.000Z",
+          lastSeenAt: "2026-03-13T00:00:01.000Z",
+        },
+      ],
+    });
+
+    try {
+      const client = createRuntimeSocketAttachedLocalControlClient({
+        runtimeSocket,
+        auth: {
+          clientId: "client-self",
+          clientAuthToken: "secret-proof",
+        },
+      });
+
+      await expect(client.listAttachedClients()).resolves.toEqual([
+        {
+          clientId: "client-other",
+          clientKind: "tui",
+          displayLabel: "Other terminal",
+          self: false,
+          attachedAt: "2026-03-13T00:00:00.000Z",
+          lastSeenAt: "2026-03-13T00:00:01.000Z",
+        },
+      ]);
+
+      expect(socketMock.requests).toEqual([
+        {
+          method: "listAttachedClients",
+          payload: undefined,
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+      ]);
+    } finally {
+      socketMock.restore();
+    }
+  });
+
+  it("sends attached-client auth for direct client inbox list and subscription methods", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    const socketMock = installRuntimeSocketMock(runtimeSocket, {
+      listDirectClientInbox: [
+        {
+          id: "msg-1",
+          senderNodeId: "node-alpha",
+          senderDisplayNameSnapshot: "Alpha",
+          inboxAddress: { kind: "client", clientId: "client-self" },
+          type: "finding",
+          content: "Hello there",
+          priority: 1,
+          createdAt: 1,
+        },
+      ],
+      subscribeDirectClientInbox: {
+        id: "msg-2",
+        senderNodeId: "node-bravo",
+        senderDisplayNameSnapshot: "Bravo",
+        inboxAddress: { kind: "client", clientId: "client-self" },
+        type: "finding",
+        content: "Streaming hello",
+        priority: 1,
+        createdAt: 2,
+      },
+    });
+
+    try {
+      const client = createRuntimeSocketAttachedLocalControlClient({
+        runtimeSocket,
+        auth: {
+          clientId: "client-self",
+          clientAuthToken: "secret-proof",
+        },
+      });
+
+      await expect(client.listDirectClientInbox({ unreadOnly: true })).resolves.toEqual([
+        {
+          id: "msg-1",
+          senderNodeId: "node-alpha",
+          senderDisplayNameSnapshot: "Alpha",
+          inboxAddress: { kind: "client", clientId: "client-self" },
+          type: "finding",
+          content: "Hello there",
+          priority: 1,
+          createdAt: 1,
+        },
+      ]);
+
+      const iterator = client.subscribeDirectClientInbox()[Symbol.asyncIterator]();
+      try {
+        await expect(iterator.next()).resolves.toEqual({
+          done: false,
+          value: {
+            id: "msg-2",
+            senderNodeId: "node-bravo",
+            senderDisplayNameSnapshot: "Bravo",
+            inboxAddress: { kind: "client", clientId: "client-self" },
+            type: "finding",
+            content: "Streaming hello",
+            priority: 1,
+            createdAt: 2,
+          },
+        });
+      } finally {
+        await iterator.return?.();
+      }
+
+      expect(socketMock.requests).toEqual([
+        {
+          method: "listDirectClientInbox",
+          payload: {
+            unreadOnly: true,
+          },
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+        {
+          method: "subscribeDirectClientInbox",
+          payload: undefined,
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+      ]);
+    } finally {
+      socketMock.restore();
+    }
+  });
+
+  it("sends attached-client auth for attached-client message delivery methods", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    const socketMock = installRuntimeSocketMock(runtimeSocket, {
+      sendBestEffort: {
+        transport: "local_runtime",
+        delivered: true,
+        queued: false,
+      },
+      sendDurable: {
+        transport: "local_runtime",
+        delivered: true,
+        queued: false,
+      },
+    });
+
+    try {
+      const client = createRuntimeSocketAttachedLocalControlClient({
+        runtimeSocket,
+        auth: {
+          clientId: "client-self",
+          clientAuthToken: "secret-proof",
+        },
+      });
+
+      await expect(
+        client.sendBestEffort({
+          rawMessage: {
+            id: "msg-best-effort",
+            sender: { id: "node-alpha", name: "Alpha", type: "arion" },
+            recipient: { id: "client-other", name: "Other terminal", type: "client" },
+            type: "message",
+            content: "best effort hello",
+            timestamp: 1,
+            priority: 2,
+          },
+          recipientInbox: { kind: "client", clientId: "client-other" },
+        }),
+      ).resolves.toMatchObject({
+        transport: "local_runtime",
+        delivered: true,
+        queued: false,
+      });
+
+      await expect(
+        client.sendDurable({
+          rawMessage: {
+            id: "msg-durable",
+            sender: { id: "node-alpha", name: "Alpha", type: "arion" },
+            recipient: { id: "client-other", name: "Other terminal", type: "client" },
+            type: "message",
+            content: "durable hello",
+            timestamp: 2,
+            priority: 2,
+          },
+          recipientInbox: { kind: "client", clientId: "client-other" },
+        }),
+      ).resolves.toMatchObject({
+        transport: "local_runtime",
+        delivered: true,
+        queued: false,
+      });
+
+      expect(socketMock.requests).toEqual([
+        {
+          method: "sendBestEffort",
+          payload: {
+            rawMessage: {
+              id: "msg-best-effort",
+              sender: { id: "node-alpha", name: "Alpha", type: "arion" },
+              recipient: { id: "client-other", name: "Other terminal", type: "client" },
+              type: "message",
+              content: "best effort hello",
+              timestamp: 1,
+              priority: 2,
+            },
+            recipientInbox: { kind: "client", clientId: "client-other" },
+          },
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+        {
+          method: "sendDurable",
+          payload: {
+            rawMessage: {
+              id: "msg-durable",
+              sender: { id: "node-alpha", name: "Alpha", type: "arion" },
+              recipient: { id: "client-other", name: "Other terminal", type: "client" },
+              type: "message",
+              content: "durable hello",
+              timestamp: 2,
+              priority: 2,
+            },
+            recipientInbox: { kind: "client", clientId: "client-other" },
+          },
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+      ]);
+    } finally {
+      socketMock.restore();
+    }
+  });
+
+  it("sends attached-client auth for attached-client run methods", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    const socketMock = installRuntimeSocketMock(runtimeSocket, {
+      submitRun: {
+        success: true,
+        output: "submitted",
+      },
+      resumeRun: {
+        success: true,
+        output: "resumed",
+      },
+      streamRun: {
+        type: "text_delta",
+        content: "streamed output",
+      },
+    });
+
+    try {
+      const client = createRuntimeSocketAttachedLocalControlClient({
+        runtimeSocket,
+        auth: {
+          clientId: "client-self",
+          clientAuthToken: "secret-proof",
+        },
+      });
+
+      const handle = await client.submitRun({ task: "hello attached runtime" });
+      await expect(handle.wait()).resolves.toMatchObject({
+        success: true,
+        output: "submitted",
+      });
+
+      await expect(
+        client.resumeRun({ state: { input: "resume attached runtime" } }),
+      ).resolves.toMatchObject({
+        success: true,
+        output: "resumed",
+      });
+
+      const iterator = client
+        .streamRun({ task: "stream attached runtime" })
+        [Symbol.asyncIterator]();
+      try {
+        await expect(iterator.next()).resolves.toEqual({
+          done: false,
+          value: {
+            type: "text_delta",
+            content: "streamed output",
+          },
+        });
+      } finally {
+        await iterator.return?.();
+      }
+
+      expect(socketMock.requests).toEqual([
+        {
+          method: "submitRun",
+          payload: {
+            task: "hello attached runtime",
+          },
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+        {
+          method: "resumeRun",
+          payload: {
+            state: {
+              input: "resume attached runtime",
+            },
+          },
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+        {
+          method: "streamRun",
+          payload: {
+            task: "stream attached runtime",
+          },
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "secret-proof",
+          },
+        },
+      ]);
+    } finally {
+      socketMock.restore();
+    }
+  });
+
+  it("preserves diagnostics from runtime socket error responses", async () => {
+    const runtimeSocket = "/tmp/aria-runtime.sock";
+    createConnectionMock.mockImplementation((target) => {
+      const requestedPath =
+        typeof target === "string"
+          ? target
+          : typeof target === "object" && target
+            ? target.path
+            : "";
+      if (requestedPath !== runtimeSocket) {
+        throw new Error(`unexpected socket target: ${String(requestedPath)}`);
+      }
+
+      const socket = new EventEmitter() as net.Socket;
+      socket.setEncoding = vi.fn();
+      socket.write = vi.fn((chunk: string) => {
+        const request = JSON.parse(chunk.trim()) as { id: string };
+        queueMicrotask(() => {
+          socket.emit(
+            "data",
+            `${JSON.stringify({
+              id: request.id,
+              ok: false,
+              error: "Internal server error",
+              diagnostic: {
+                name: "TypeError",
+                message: "Cannot read properties of undefined (reading 'estimatedCost')",
+                stack: "TypeError: Cannot read properties of undefined (reading 'estimatedCost')",
+                code: "STREAM_FINAL_RESPONSE_MISSING",
+              },
+            })}\n`,
+          );
+        });
+        return true;
+      });
+      socket.destroy = vi.fn(() => {
+        socket.emit("close");
+        return socket;
+      });
+      queueMicrotask(() => {
+        socket.emit("connect");
+      });
+      return socket;
+    });
+
+    const client = createRuntimeSocketLocalControlClient({ runtimeSocket });
+    const handle = await client.submitRun({ task: "say something funny" });
+
+    await expect(handle.wait()).rejects.toMatchObject({
+      message: "Cannot read properties of undefined (reading 'estimatedCost')",
+      diagnostic: {
+        code: "STREAM_FINAL_RESPONSE_MISSING",
+      },
+    });
+  });
+
+  it("keeps attached-only methods off the base runtime-socket client", () => {
+    if (false) {
+      const client = createRuntimeSocketLocalControlClient({
+        runtimeSocket: "/tmp/aria-runtime.sock",
+      });
+
+      // @ts-expect-error the base runtime-socket client must not expose attached-only methods
+      void client.listAttachedClients;
+      // @ts-expect-error the base runtime-socket client must not expose direct client inbox methods
+      void client.listDirectClientInbox;
+      // @ts-expect-error the base runtime-socket client must not expose direct client inbox stream methods
+      void client.subscribeDirectClientInbox;
+    }
+
+    expect(true).toBe(true);
+  });
+});