@aphrody/os 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@aphrody/os",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bun client for the Aphrody OS kernel: join the OS as a subsystem, call any OS tool or skill.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --target bun --packages external --outdir dist",
+    "lint": "oxlint src test",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Bun client for the Aphrody OS kernel.
+ *
+ * A Bun process joins the OS as a subsystem with {@link registerSubsystem}: its tools are
+ * published to every agent next to the native ones and the kernel routes their calls back
+ * here. {@link KernelClient} also calls any OS tool or skill directly.
+ *
+ * Wire format: newline-delimited JSON-RPC 2.0 over the per-user local endpoint (Unix socket or
+ * Windows named pipe), the same one `aphrody-kernel` and the desktop serve.
+ */
+import { connect, type Socket } from "node:net";
+import { join } from "node:path";
+
+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+
+/** The per-user endpoint, identical to `aphrody_kernel::transport::default_endpoint`. */
+export function defaultEndpoint(): string {
+  const override = process.env.APHRODY_OS_SOCKET;
+  if (override) return override;
+  const user = (process.env.USERNAME ?? process.env.USER ?? "user").replace(/[^A-Za-z0-9_-]/g, "");
+  if (process.platform === "win32") return `\\\\.\\pipe\\aphrody-os-${user}`;
+  const runtime = process.env.XDG_RUNTIME_DIR;
+  return runtime ? join(runtime, "aphrody-os.sock") : `/tmp/aphrody-os-${user}.sock`;
+}
+
+type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+interface Message {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: Json;
+  result?: Json;
+  error?: { code: number; message: string };
+}
+export class KernelError extends Error {
+  constructor(
+    message: string,
+    readonly code: number,
+  ) {
+    super(message);
+  }
+}
+
+/** A JSON-RPC connection to the kernel. */
+export class KernelClient {
+  #socket: Socket;
+  #buffer = "";
+  #bufferBytes = 0;
+  #nextId = 1;
+  #pending = new Map<string, { resolve: (m: Message) => void; reject: (e: Error) => void }>();
+  #onRequest?: (message: Message) => Promise<Json>;
+  #onNotification?: (message: Message) => void;
+  readonly closed: Promise<void>;
+
+  private constructor(socket: Socket) {
+    this.#socket = socket;
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk: string) => this.#receive(chunk));
+    socket.on("error", (error: Error) => {
+      for (const { reject } of this.#pending.values()) reject(error);
+      this.#pending.clear();
+    });
+    this.closed = new Promise((resolve) => {
+      socket.on("close", () => {
+        for (const { reject } of this.#pending.values())
+          reject(new Error("kernel connection closed"));
+        this.#pending.clear();
+        resolve();
+      });
+    });
+  }
+
+  /** Connect and perform the MCP handshake. */
+  static async connect(
+    endpoint = defaultEndpoint(),
+    clientName = "aphrody-os-bun",
+    timeoutMs = 30_000,
+  ): Promise<KernelClient> {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+      throw new Error("connect timeout must be positive");
+    const socket = await new Promise<Socket>((resolve, reject) => {
+      const s = connect(endpoint);
+      const timer = setTimeout(
+        () => s.destroy(new Error("kernel connection timed out")),
+        timeoutMs,
+      );
+      s.once("connect", () => {
+        clearTimeout(timer);
+        resolve(s);
+      });
+      s.once("error", (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+    const client = new KernelClient(socket);
+    const initialize: { [key: string]: Json } = {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: { name: clientName, version: "1.0.0" },
+    };
+    const authToken = process.env.APHRODY_OS_AUTH_TOKEN;
+    if (authToken) initialize.authToken = authToken;
+    try {
+      await client.request("initialize", initialize, timeoutMs);
+      client.notify("notifications/initialized", {});
+      return client;
+    } catch (error) {
+      client.close();
+      throw error;
+    }
+  }
+
+  #send(message: Message): void {
+    this.#socket.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+  }
+
+  #receive(chunk: string): void {
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf("\n", offset);
+      const end = newline < 0 ? chunk.length : newline + 1;
+      const part = chunk.slice(offset, end);
+      this.#bufferBytes += Buffer.byteLength(part, "utf8");
+      if (this.#bufferBytes > MAX_MESSAGE_BYTES) {
+        this.#socket.destroy(new Error("kernel message too large"));
+        return;
+      }
+      this.#buffer += part;
+      offset = end;
+      if (newline < 0) continue;
+      const line = this.#buffer.trim();
+      this.#buffer = "";
+      this.#bufferBytes = 0;
+      if (!line) continue;
+      let message: Message;
+      try {
+        message = JSON.parse(line) as Message;
+      } catch {
+        continue;
+      }
+      if (message.method === undefined && message.id !== undefined) {
+        const waiter = this.#pending.get(String(message.id));
+        this.#pending.delete(String(message.id));
+        if (!waiter) continue;
+        if (message.error)
+          waiter.reject(new KernelError(message.error.message, message.error.code));
+        else waiter.resolve(message);
+      } else if (message.method !== undefined && message.id !== undefined && message.id !== null) {
+        const id = message.id;
+        const handle =
+          this.#onRequest ??
+          (async () => ({ content: [{ type: "text", text: "no handler" }], isError: true }));
+        void handle(message).then(
+          (result) => this.#send({ id, result }),
+          (error: unknown) => this.#send({ id, error: { code: -32603, message: String(error) } }),
+        );
+      } else if (message.method !== undefined) {
+        this.#onNotification?.(message);
+      }
+    }
+  }
+
+  /** Send a request; resolves with its `result`. */
+  request(method: string, params: Json = {}, timeoutMs = 0): Promise<Json> {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+      return Promise.reject(new Error("request timeout must be nonnegative"));
+    if (this.#socket.destroyed) return Promise.reject(new Error("kernel connection closed"));
+    const id = String(this.#nextId++);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return new Promise<Message>((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      if (timeoutMs > 0)
+        timer = setTimeout(() => {
+          this.#pending.delete(id);
+          reject(new Error(`kernel ${method} timed out`));
+        }, timeoutMs);
+      this.#send({ id, method, params });
+    })
+      .then((message) => message.result ?? null)
+      .finally(() => clearTimeout(timer));
+  }
+
+  notify(method: string, params: Json = {}): void {
+    this.#send({ method, params });
+  }
+
+  /** Call an OS tool; resolves with its structured value, rejects when the tool failed. */
+  async call(tool: string, args: Record<string, Json> = {}, timeoutMs = 0): Promise<Json> {
+    const result = (await this.request(
+      "tools/call",
+      { name: tool, arguments: args },
+      timeoutMs,
+    )) as Record<string, Json>;
+    const text = ((result.content as Array<Record<string, Json>>) ?? [])
+      .map((part) => part.text ?? "")
+      .join("\n");
+    if (result.isError) throw new KernelError(text, -32000);
+    const structured = result.structuredContent as Record<string, Json> | undefined;
+    if (structured)
+      return Object.keys(structured).length === 1 && "result" in structured
+        ? structured.result
+        : structured;
+    return text;
+  }
+
+  onRequest(handler: (message: Message) => Promise<Json>): void {
+    this.#onRequest = handler;
+  }
+
+  onNotification(handler: (message: Message) => void): void {
+    this.#onNotification = handler;
+  }
+
+  close(): void {
+    this.#socket.destroy();
+  }
+}
+
+export interface ToolSpec {
+  name: string;
+  description: string;
+  inputSchema?: Json;
+  readOnly?: boolean;
+  handler: (args: Record<string, Json>) => unknown | Promise<unknown>;
+}
+
+export interface SubsystemSpec {
+  name: string;
+  description?: string;
+  tools: ToolSpec[];
+  skills?: Json[];
+}
+
+function toCallResult(value: unknown): Json {
+  const json = (value ?? null) as Json;
+  const text = typeof json === "string" ? json : JSON.stringify(json, null, 2);
+  const structured =
+    json !== null && typeof json === "object" && !Array.isArray(json) ? json : { result: json };
+  return { content: [{ type: "text", text }], structuredContent: structured, isError: false };
+}
+
+/**
+ * Join the kernel as a subsystem. The returned client stays connected; closing it (or the
+ * process exiting) unregisters the subsystem.
+ */
+export async function registerSubsystem(
+  spec: SubsystemSpec,
+  endpoint = defaultEndpoint(),
+): Promise<KernelClient> {
+  const client = await KernelClient.connect(endpoint, `bun/${spec.name}`);
+  const handlers = new Map(spec.tools.map((tool) => [tool.name, tool.handler]));
+  client.onRequest(async (message) => {
+    if (message.method === "ping") return {};
+    if (message.method !== "tools/call")
+      return { content: [{ type: "text", text: `unsupported: ${message.method}` }], isError: true };
+    const params = (message.params ?? {}) as Record<string, Json>;
+    const handler = handlers.get(String(params.name));
+    if (!handler)
+      return { content: [{ type: "text", text: `unknown tool: ${params.name}` }], isError: true };
+    try {
+      return toCallResult(await handler((params.arguments ?? {}) as Record<string, Json>));
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  });
+  await client.request("system/register_subsystem", {
+    name: spec.name,
+    description: spec.description ?? `Bun subsystem ${spec.name}.`,
+    runtime: "bun",
+    tools: spec.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema ?? { type: "object" },
+      annotations: { readOnlyHint: tool.readOnly ?? false },
+    })),
+    skills: spec.skills ?? [],
+  });
+  return client;
+}
+
+export * as systemd from "./systemd.ts";
+export {
+  formatJournal,
+  getWatchdogUsec,
+  journal,
+  notifyReady,
+  notifyStatus,
+  notifyStopping,
+  notifyWatchdog,
+  sdNotify,
+  startWatchdogLoop,
+  SyslogPriority,
+  type SyslogLevel,
+} from "./systemd.ts";

package/src/systemd.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Native systemd integration for Bun runtimes:
+ * - Zero-dependency sd_notify and watchdog heartbeats via `bun:ffi` libc sockets.
+ * - Standard syslog priority formatting for high-performance direct journald indexing.
+ */
+import { dlopen, FFIType } from "bun:ffi";
+
+/** Standard syslog priority prefixes for stdout/stderr journald indexing. */
+export const SyslogPriority = {
+  EMERG: "<0>",
+  ALERT: "<1>",
+  CRIT: "<2>",
+  ERR: "<3>",
+  WARNING: "<4>",
+  NOTICE: "<5>",
+  INFO: "<6>",
+  DEBUG: "<7>",
+} as const;
+
+export type SyslogLevel = keyof typeof SyslogPriority;
+
+/** Format a message with a syslog priority prefix recognized by systemd journald. */
+export function formatJournal(level: SyslogLevel, message: string): string {
+  return `${SyslogPriority[level]}${message}`;
+}
+
+export const journal = {
+  emerg: (msg: string) => console.error(formatJournal("EMERG", msg)),
+  alert: (msg: string) => console.error(formatJournal("ALERT", msg)),
+  crit: (msg: string) => console.error(formatJournal("CRIT", msg)),
+  err: (msg: string) => console.error(formatJournal("ERR", msg)),
+  warn: (msg: string) => console.warn(formatJournal("WARNING", msg)),
+  notice: (msg: string) => console.log(formatJournal("NOTICE", msg)),
+  info: (msg: string) => console.log(formatJournal("INFO", msg)),
+  debug: (msg: string) => console.debug(formatJournal("DEBUG", msg)),
+};
+
+let libc: any = null;
+function getLibc() {
+  if (libc !== null) return libc;
+  if (process.platform === "win32") {
+    libc = false;
+    return false;
+  }
+  try {
+    const libPath = process.platform === "darwin" ? "libSystem.B.dylib" : "libc.so.6";
+    libc = dlopen(libPath, {
+      socket: { args: [FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      sendto: {
+        args: [FFIType.i32, FFIType.ptr, FFIType.u64, FFIType.i32, FFIType.ptr, FFIType.u32],
+        returns: FFIType.i64,
+      },
+      close: { args: [FFIType.i32], returns: FFIType.i32 },
+    });
+    return libc;
+  } catch {
+    libc = false;
+    return false;
+  }
+}
+
+/**
+ * Send a notification string to systemd via `NOTIFY_SOCKET`.
+ * Supports both filesystem paths and Linux abstract namespace sockets (leading `@`).
+ *
+ * @returns `true` if notification was transmitted, `false` if `NOTIFY_SOCKET` was unset or unavailable.
+ */
+export function sdNotify(state: string): boolean {
+  const socketPath = process.env.NOTIFY_SOCKET;
+  if (!socketPath) return false;
+
+  const lib = getLibc();
+  if (!lib) return false;
+
+  const AF_UNIX = 1;
+  const SOCK_DGRAM = 2;
+  const fd = lib.symbols.socket(AF_UNIX, SOCK_DGRAM, 0);
+  if (fd < 0) return false;
+
+  try {
+    const isAbstract = socketPath.startsWith("@");
+    const rawPath = isAbstract ? `\0${socketPath.slice(1)}` : socketPath;
+    const pathBuffer = Buffer.from(rawPath, "utf-8");
+
+    // struct sockaddr_un:
+    //   unsigned short sun_family (2 bytes)
+    //   char sun_path[108]
+    const sockaddr = Buffer.alloc(2 + 108);
+    sockaddr.writeUInt16LE(AF_UNIX, 0);
+    pathBuffer.copy(sockaddr, 2, 0, Math.min(pathBuffer.length, 108));
+
+    const stateBuf = Buffer.from(state, "utf-8");
+    const addrLen = isAbstract ? 2 + pathBuffer.length : 2 + pathBuffer.length + 1;
+
+    const sent = lib.symbols.sendto(fd, stateBuf, BigInt(stateBuf.length), 0, sockaddr, addrLen);
+
+    return Number(sent) >= 0;
+  } finally {
+    lib.symbols.close(fd);
+  }
+}
+
+/** Notify service manager that startup is complete. */
+export function notifyReady(): boolean {
+  return sdNotify("READY=1");
+}
+
+/** Update the service's single-line status message. */
+export function notifyStatus(status: string): boolean {
+  return sdNotify(`STATUS=${status}`);
+}
+
+/** Notify service manager that service shutdown has initiated. */
+export function notifyStopping(): boolean {
+  return sdNotify("STOPPING=1");
+}
+
+/** Send keepalive heartbeat ping for services with `WatchdogSec=`. */
+export function notifyWatchdog(): boolean {
+  return sdNotify("WATCHDOG=1");
+}
+
+/** Read watchdog timeout in microseconds from `WATCHDOG_USEC`. */
+export function getWatchdogUsec(): number | null {
+  const raw = process.env.WATCHDOG_USEC;
+  if (!raw) return null;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+/**
+ * Spawns an automatic periodic watchdog heartbeat timer.
+ * Defaults to sending `WATCHDOG=1` at half the interval specified in `WATCHDOG_USEC`.
+ *
+ * @returns a controller with `.stop()` to cancel the heartbeat, or `null` if watchdog is not enabled.
+ */
+export function startWatchdogLoop(customIntervalMs?: number): { stop(): void } | null {
+  let intervalMs: number | null = null;
+  if (customIntervalMs !== undefined && customIntervalMs > 0) {
+    intervalMs = customIntervalMs;
+  } else {
+    const usec = getWatchdogUsec();
+    if (usec) {
+      intervalMs = Math.max(100, Math.floor(usec / 2000));
+    }
+  }
+
+  if (!intervalMs) return null;
+
+  const timer = setInterval(() => {
+    sdNotify("WATCHDOG=1");
+  }, intervalMs);
+
+  return {
+    stop() {
+      clearInterval(timer);
+    },
+  };
+}

package/test/kernel.test.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+// End-to-end against a real `aphrody-kernel serve` on a private endpoint.
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { KernelClient, registerSubsystem } from "../src/index.ts";
+
+const exe = process.platform === "win32" ? "aphrody-kernel.exe" : "aphrody-kernel";
+// The Rust workspace root owns target/; an explicit binary override is available for installed builds.
+const binary =
+  process.env.APHRODY_KERNEL_BIN ?? join(import.meta.dir, "../../../../target/debug", exe);
+const endpoint =
+  process.platform === "win32"
+    ? `\\\\.\\pipe\\aphrody-os-bun-test-${process.pid}`
+    : `/tmp/aphrody-os-bun-test-${process.pid}.sock`;
+let server: ReturnType<typeof Bun.spawn> | undefined;
+
+beforeAll(async () => {
+  if (!existsSync(binary))
+    throw new Error(`build it first through scripts/build/rust/cargo-serial.sh: ${binary}`);
+  server = Bun.spawn([binary, "--socket", endpoint, "serve", "--no-browser"], {
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  for (let i = 0; i < 200; i++) {
+    try {
+      (await KernelClient.connect(endpoint)).close();
+      return;
+    } catch {
+      await Bun.sleep(50);
+    }
+  }
+  throw new Error("kernel did not start");
+}, 60_000);
+
+afterAll(() => server?.kill());
+
+test("a Bun subsystem is served to other clients and leaves on close", async () => {
+  const bun = await registerSubsystem(
+    {
+      name: "bun_text",
+      tools: [
+        {
+          name: "bun_reverse",
+          description: "Reverse a string.",
+          inputSchema: {
+            type: "object",
+            properties: { text: { type: "string" } },
+            required: ["text"],
+          },
+          handler: ({ text }) => ({
+            reversed: String(text).split("").toReversed().join(""),
+            runtime: `bun ${Bun.version}`,
+          }),
+        },
+      ],
+    },
+    endpoint,
+  );
+  const agent = await KernelClient.connect(endpoint, "agent");
+  const tools = (await agent.request("tools/list")) as { tools: { name: string }[] };
+  expect(tools.tools.map((t) => t.name)).toContain("bun_reverse");
+  const out = (await agent.call("bun_reverse", { text: "aphrody" })) as { reversed: string };
+  expect(out.reversed).toBe("ydorhpa");
+
+  // The Bun process can drive native subsystems too: Nushell through the kernel.
+  const nu = (await bun.call("nu_eval", { code: "[1 2 3] | math sum" })) as { value: number };
+  expect(nu.value).toBe(6);
+
+  bun.close();
+  await bun.closed;
+  for (let i = 0; i < 100; i++) {
+    const after = (await agent.request("tools/list")) as { tools: { name: string }[] };
+    if (!after.tools.some((t) => t.name === "bun_reverse")) break;
+    await Bun.sleep(20);
+  }
+  const after = (await agent.request("tools/list")) as { tools: { name: string }[] };
+  expect(after.tools.map((t) => t.name)).not.toContain("bun_reverse");
+  agent.close();
+}, 60_000);

package/test/systemd.test.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+import { expect, test } from "bun:test";
+import {
+  formatJournal,
+  getWatchdogUsec,
+  notifyReady,
+  notifyStatus,
+  notifyStopping,
+  notifyWatchdog,
+  sdNotify,
+  startWatchdogLoop,
+  SyslogPriority,
+} from "../src/systemd.ts";
+
+test("journal formatting uses standard syslog prefixes", () => {
+  expect(formatJournal("INFO", "service booted")).toBe("<6>service booted");
+  expect(formatJournal("ERR", "database connection failed")).toBe("<3>database connection failed");
+  expect(formatJournal("WARNING", "rate limit approaching")).toBe("<4>rate limit approaching");
+  expect(SyslogPriority.EMERG).toBe("<0>");
+  expect(SyslogPriority.DEBUG).toBe("<7>");
+});
+
+test("sdNotify returns false when NOTIFY_SOCKET is not set", () => {
+  const prev = process.env.NOTIFY_SOCKET;
+  try {
+    delete process.env.NOTIFY_SOCKET;
+    expect(sdNotify("READY=1")).toBe(false);
+    expect(notifyReady()).toBe(false);
+    expect(notifyStatus("running")).toBe(false);
+    expect(notifyStopping()).toBe(false);
+    expect(notifyWatchdog()).toBe(false);
+  } finally {
+    if (prev !== undefined) process.env.NOTIFY_SOCKET = prev;
+  }
+});
+
+test("watchdog interval calculation parses WATCHDOG_USEC correctly", () => {
+  const prev = process.env.WATCHDOG_USEC;
+  try {
+    process.env.WATCHDOG_USEC = "20000000"; // 20s
+    expect(getWatchdogUsec()).toBe(20000000);
+
+    const loop = startWatchdogLoop();
+    expect(loop).not.toBeNull();
+    loop?.stop();
+
+    delete process.env.WATCHDOG_USEC;
+    expect(getWatchdogUsec()).toBeNull();
+    expect(startWatchdogLoop()).toBeNull();
+  } finally {
+    if (prev !== undefined) process.env.WATCHDOG_USEC = prev;
+    else delete process.env.WATCHDOG_USEC;
+  }
+});

package/test/transport.test.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+import { expect, test } from "bun:test";
+import { createServer, type Socket } from "node:net";
+import { join } from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { KernelClient } from "../src/index.ts";
+
+async function endpoint(reply: boolean) {
+  const root = await mkdtemp(join(tmpdir(), "aphrody-transport-"));
+  const path =
+    process.platform === "win32"
+      ? `\\\\.\\pipe\\aphrody-transport-${crypto.randomUUID()}`
+      : join(root, "kernel.sock");
+  const sockets = new Set<Socket>();
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    socket.on("error", () => {});
+    let buffer = "";
+    socket.on("data", (data) => {
+      buffer += data.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop()!;
+      for (const line of lines) {
+        const request = JSON.parse(line);
+        if (reply && request.method === "initialize")
+          socket.write(JSON.stringify({ jsonrpc: "2.0", id: request.id, result: {} }) + "\n");
+      }
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(path, resolve);
+  });
+  return {
+    path,
+    async dispose() {
+      for (const socket of sockets) socket.destroy();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await rm(root, { recursive: true, force: true });
+    },
+  };
+}
+
+test("a stalled MCP handshake times out and closes its connection", async () => {
+  const server = await endpoint(false);
+  try {
+    await expect(KernelClient.connect(server.path, "test", 30)).rejects.toThrow("timed out");
+  } finally {
+    await server.dispose();
+  }
+});
+
+test("request deadlines and shutdown reject waits, including calls made after close", async () => {
+  const server = await endpoint(true);
+  const client = await KernelClient.connect(server.path);
+  try {
+    await expect(client.call("stalled-tool", {}, 30)).rejects.toThrow("timed out");
+    const pending = client.request("tools/list");
+    client.close();
+    await expect(pending).rejects.toThrow("closed");
+    await client.closed;
+    await expect(client.request("tools/list")).rejects.toThrow("closed");
+  } finally {
+    client.close();
+    await server.dispose();
+  }
+});
+
+test("invalid deadlines are refused before starting a connection", async () => {
+  await expect(KernelClient.connect("/missing", "test", 0)).rejects.toThrow("positive");
+});

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": [
+    "src",
+    "test",
+    "*.ts",
+    "bindings",
+    "scripts"
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.