kennel 0.2.0 → 0.2.2

package/kernel/packages/api/src/server/acp/process-manager.ts

@@ -0,0 +1,291 @@
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+
+import type { AgentAdapter } from "./types";
+
+/**
+ * Lifecycle states for an ACP-managed child process.
+ *
+ * - idle:      No process has been started for this key.
+ * - starting:  spawn() has been called, the process exists but may not be ready.
+ * - running:   The process has emitted 'spawn' and is ready for I/O.
+ * - stopping:  stop() has been called, SIGTERM (or equivalent) was sent.
+ * - stopped:   The process exited after a graceful stop.
+ * - errored:   The process exited with a non-zero code or a spawn failure.
+ */
+export type AcpProcessState =
+  "idle" | "starting" | "running" | "stopping" | "stopped" | "errored";
+
+/** Read-only information about an ACP-managed process. */
+export type AcpProcessInfo = {
+  /** Unique key used to start the process. */
+  key: string;
+  /** Current lifecycle state. */
+  state: AcpProcessState;
+  /** OS-assigned PID. Null when no process is active. */
+  pid: number | null;
+  /** ISO-8601 timestamp of the spawn. Null when idle. */
+  startedAt: string | null;
+  /** Exit code from the OS. Null while running. */
+  exitCode: number | null;
+  /** Signal that caused the exit. Null when no signal was involved. */
+  signal: NodeJS.Signals | null;
+  /** Bounded snapshot of stderr lines (newest lines last). */
+  stderrLines: string[];
+};
+
+/**
+ * A handle the caller uses to interact with a managed process.
+ *
+ * The caller writes JSON-RPC or ACP frames to `stdin` and reads responses
+ * from `stdout`. The `state` getter returns the current lifecycle state, and
+ * `onExit` resolves when the process terminates.
+ */
+export type AcpProcessHandle = {
+  /** Writable stream connected to the child's stdin. */
+  stdin: Writable;
+  /** Readable stream connected to the child's stdout. */
+  stdout: Readable;
+  /** Current lifecycle state (live). */
+  readonly state: AcpProcessState;
+  /** Promise that resolves with exit information when the process terminates. */
+  readonly onExit: Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  }>;
+  /** Optional readable stream for stderr (null if stderr is only buffered). */
+  readonly stderr: Readable | null;
+};
+
+/** Internal record for one active process slot. */
+type ActiveSlot = {
+  process: ChildProcess;
+  handle: AcpProcessHandle;
+  state: AcpProcessState;
+  startedAt: string;
+  stderrRing: string[];
+  stopResolver: (() => void) | null;
+  exitResolver: (value: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  }) => void;
+};
+
+/**
+ * Manage child processes for ACP adapters.
+ *
+ * One instance manages one or more independent adapter processes identified
+ * by unique string keys. Each key can have at most one active process.
+ *
+ * The manager is agent-neutral. It receives an {@link AgentAdapter}
+ * and starts the described command without a shell.
+ */
+export class AcpProcessManager {
+  private readonly slots = new Map<string, ActiveSlot>();
+
+  /**
+   * Start an ACP adapter process for the given key.
+   *
+   * Throws if a process is already active for this key.
+   *
+   * @param key    Unique connection key.
+   * @param config Adapter command configuration.
+   * @returns A handle for reading/writing and monitoring the process.
+   */
+  start(key: string, adapter: AgentAdapter): AcpProcessHandle {
+    if (this.slots.has(key)) {
+      throw new DuplicateProcessError(key);
+    }
+
+    const stderrLimit = 256;
+    const stderrRing: string[] = [];
+
+    // --- resolve callbacks once ---
+    let exitResolver!: (value: {
+      code: number | null;
+      signal: NodeJS.Signals | null;
+    }) => void;
+    let exitCalled = false;
+    const onExit = new Promise<{
+      code: number | null;
+      signal: NodeJS.Signals | null;
+    }>((resolve) => {
+      exitResolver = resolve;
+    });
+
+    // --- spawn without a shell ---
+    const child = spawn(adapter.command, adapter.args, {
+      env: process.env,
+      cwd: adapter.workingFolder,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    const startedAt = new Date().toISOString();
+
+    const handle: AcpProcessHandle = {
+      stdin: child.stdin!,
+      stdout: child.stdout!,
+      stderr: child.stderr!,
+      get state() {
+        return slot.state;
+      },
+      onExit,
+    };
+
+    const slot: ActiveSlot = {
+      process: child,
+      handle,
+      state: "starting",
+      startedAt,
+      stderrRing,
+      stopResolver: null,
+      exitResolver,
+    };
+
+    // --- bind stderr ring buffer ---
+    child.stderr!.on("data", (chunk: Buffer) => {
+      const text = chunk.toString("utf-8");
+      const lines = text.split("\n");
+      for (const line of lines) {
+        if (line.length === 0) continue;
+        stderrRing.push(line);
+        if (stderrRing.length > stderrLimit) {
+          stderrRing.splice(0, stderrRing.length - stderrLimit);
+        }
+      }
+    });
+
+    // --- lifecycle events ---
+    child.on("spawn", () => {
+      slot.state = "running";
+    });
+
+    child.on("error", (err) => {
+      stderrRing.push(`[spawn-error] ${err.message}`);
+      if (slot.state !== "stopping" && slot.state !== "stopped") {
+        slot.state = "errored";
+      }
+      if (!exitCalled) {
+        exitCalled = true;
+        exitResolver({ code: 1, signal: null });
+        this.slots.delete(key);
+      }
+    });
+
+    child.on("exit", (code, signal) => {
+      if (slot.state === "stopping") {
+        slot.state = "stopped";
+      } else if (slot.state !== "stopped") {
+        slot.state = code === 0 ? "stopped" : "errored";
+      }
+      slot.stopResolver?.();
+      slot.stopResolver = null;
+
+      if (!exitCalled) {
+        exitCalled = true;
+        exitResolver({ code, signal });
+        this.slots.delete(key);
+      }
+    });
+
+    this.slots.set(key, slot);
+    return handle;
+  }
+
+  /**
+   * Stop the process for the given key.
+   *
+   * Sends SIGTERM first. If the process does not exit within `graceMs`, sends
+   * SIGKILL and waits up to `killMs` before rejecting.
+   *
+   * @param key      Connection key.
+   * @param graceMs  Wait time after SIGTERM before SIGKILL (default 5000 ms).
+   * @param killMs   Wait time after SIGKILL before force-resolve (default 2000 ms).
+   * @returns Promise that resolves when the process exits.
+   */
+  async stop(key: string, graceMs = 5_000, killMs = 2_000): Promise<void> {
+    const slot = this.slots.get(key);
+    if (!slot) return;
+
+    if (
+      slot.state === "stopping" ||
+      slot.state === "stopped" ||
+      slot.state === "errored"
+    )
+      return;
+
+    slot.state = "stopping";
+
+    return new Promise<void>((resolve, reject) => {
+      slot.stopResolver = resolve;
+
+      // Phase 1: graceful signal
+      const killed = slot.process.kill("SIGTERM");
+      if (!killed) {
+        // Process already gone
+        resolve();
+        return;
+      }
+
+      const escalate = setTimeout(() => {
+        // Phase 2: force kill
+        slot.process.kill("SIGKILL");
+        const force = setTimeout(() => {
+          reject(
+            new Error(
+              `Process ${key} did not exit after SIGKILL (${killMs} ms)`,
+            ),
+          );
+        }, killMs);
+        slot.process.on("exit", () => clearTimeout(force));
+      }, graceMs);
+
+      slot.process.on("exit", () => clearTimeout(escalate));
+    });
+  }
+
+  /**
+   * Return a read-only snapshot of the process state for a key.
+   */
+  status(key: string): AcpProcessInfo | null {
+    const slot = this.slots.get(key);
+    if (!slot) return null;
+
+    return {
+      key,
+      state: slot.state,
+      pid: slot.process.pid ?? null,
+      startedAt: slot.startedAt,
+      exitCode: slot.process.exitCode ?? null,
+      signal: slot.process.signalCode as NodeJS.Signals | null,
+      stderrLines: [...slot.stderrRing],
+    };
+  }
+
+  /**
+   * List keys of all currently tracked processes (any state except idle).
+   */
+  activeKeys(): string[] {
+    return [...this.slots.keys()];
+  }
+
+  /**
+   * Stop all tracked processes with the same escalation logic as {@link stop}.
+   */
+  async stopAll(graceMs = 5_000, killMs = 2_000): Promise<void> {
+    const keys = this.activeKeys();
+    await Promise.all(keys.map((key) => this.stop(key, graceMs, killMs)));
+  }
+}
+
+/** Error thrown when start() is called for a key that is already in use. */
+export class DuplicateProcessError extends Error {
+  constructor(key: string) {
+    super(
+      `Process slot "${key}" is already active. Stop it before starting a new one.`,
+    );
+    this.name = "DuplicateProcessError";
+  }
+}

package/kernel/packages/api/src/server/acp/registry.ts

@@ -0,0 +1,140 @@
+/**
+ * ACP adapter registry.
+ *
+ * Maps stable agent IDs to executable commands and capabilities.
+ * Validates every entry. Supports registration so multiple
+ * harnesses can be added at runtime.
+ */
+
+import type { AgentAdapter, AgentRegistry } from "./types";
+
+const idPattern = /^[a-z][a-z0-9-]*$/;
+const commandPattern = /^[a-z][a-z0-9_-]*$/;
+const capabilityPattern = /^acp:[a-z][a-z0-9_:]*$/;
+
+const adapters = new Map<string, AgentAdapter>();
+
+// ---------------------------------------------------------------------------
+// Built-in: Pi
+// ---------------------------------------------------------------------------
+
+adapters.set("pi", {
+  id: "pi",
+  displayName: "Pi Coding Agent",
+  command: "pi-acp",
+  args: [],
+  workingFolder: "/tmp",
+  capabilities: [
+    "acp:tool_call",
+    "acp:resource_read",
+    "acp:prompt",
+    "acp:completion",
+    "acp:session_resume",
+  ],
+  enabled: true,
+});
+
+// ---------------------------------------------------------------------------
+// Built-in: OpenCode
+// ---------------------------------------------------------------------------
+
+adapters.set("opencode", {
+  id: "opencode",
+  displayName: "OpenCode",
+  command: "opencode",
+  args: ["acp"],
+  workingFolder: "/tmp",
+  capabilities: ["acp:tool_call", "acp:prompt", "acp:session_resume"],
+  enabled: true,
+});
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+function validateId(id: string): void {
+  if (!id) throw new Error("Agent adapter id must not be empty.");
+  if (!idPattern.test(id))
+    throw new Error(
+      `Agent adapter id "${id}" is invalid. Use lowercase letters, digits, and hyphens.`,
+    );
+}
+
+function validateCommand(command: string): void {
+  if (!command) throw new Error("Agent adapter command must not be empty.");
+  if (!commandPattern.test(command))
+    throw new Error(
+      `Agent adapter command "${command}" is invalid. Use lowercase letters, digits, underscores, and hyphens.`,
+    );
+}
+
+function validateWorkingFolder(folder: string): void {
+  if (!folder)
+    throw new Error("Agent adapter working folder must not be empty.");
+  if (!folder.startsWith("/"))
+    throw new Error(
+      `Agent adapter working folder "${folder}" is invalid. Use an absolute path.`,
+    );
+}
+
+function validateCapabilities(capabilities: string[]): void {
+  for (const c of capabilities) {
+    if (!capabilityPattern.test(c))
+      throw new Error(`Agent adapter capability "${c}" is invalid.`);
+  }
+}
+
+export function validateAdapter(adapter: AgentAdapter): void {
+  validateId(adapter.id);
+  validateCommand(adapter.command);
+  validateWorkingFolder(adapter.workingFolder);
+  validateCapabilities(adapter.capabilities);
+}
+
+export function isValidAdapter(adapter: AgentAdapter): boolean {
+  try {
+    validateAdapter(adapter);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registry API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register an adapter at runtime. Overwrites any existing entry with
+ * the same ID. Throws on validation failure.
+ */
+export function registerAdapter(adapter: AgentAdapter): void {
+  validateAdapter(adapter);
+  adapters.set(adapter.id, adapter);
+}
+
+/** Remove an adapter by ID. No-op when unknown. */
+export function unregisterAdapter(id: string): void {
+  adapters.delete(id);
+}
+
+export function agentRegistry(): AgentRegistry {
+  const list = [...adapters.values()];
+  return {
+    adapters: list,
+    enabledCount: list.filter((a) => a.enabled).length,
+    totalCount: list.length,
+  };
+}
+
+export function findAdapter(id: string): AgentAdapter | undefined {
+  return adapters.get(id);
+}
+
+export function listAdapters(
+  filter: { enabled?: boolean } = {},
+): AgentAdapter[] {
+  const all = [...adapters.values()];
+  if (filter.enabled === undefined) return all;
+  return all.filter((a) => a.enabled === filter.enabled);
+}

package/kernel/packages/api/src/server/acp/sdk.ts

@@ -0,0 +1,15 @@
+/**
+ * ACP SDK foundation — typed re-exports from @agentclientprotocol/sdk v1.
+ *
+ * Server-safe: carries only types and protocol constants.
+ * No connection, transport, process manager, UI, or registry logic.
+ */
+
+export type * from "@agentclientprotocol/sdk";
+
+export {
+  PROTOCOL_VERSION,
+  RequestError,
+  ndJsonStream,
+  methods as acpMethods,
+} from "@agentclientprotocol/sdk";

package/kernel/packages/api/src/server/acp/transport.ts

@@ -0,0 +1,115 @@
+import type {
+  ClientApp,
+  ClientConnection,
+  ClientContext,
+  Stream,
+} from "@agentclientprotocol/sdk";
+import { client, ndJsonStream } from "@agentclientprotocol/sdk";
+
+/**
+ * Server-side ACP JSON-RPC transport for Kennel.
+ *
+ * Wraps the stable @agentclientprotocol/sdk v1 `ClientApp` and `ndJsonStream`
+ * primitives into a thin transport that sends requests, correlates responses,
+ * sends notifications, and forwards incoming session updates.
+ *
+ * This module does not manage process lifecycle, connection pools, UI state,
+ * or HTTP/WebSocket transports.
+ */
+
+/** Callback for one incoming `session/update` notification. */
+export type SessionUpdateHandler = (
+  params: unknown,
+  cx: ClientContext,
+) => void | Promise<void>;
+
+/** Callback invoked when the transport closes (clean or error). */
+export type TransportCloseHandler = (error?: unknown) => void;
+
+/** Options passed to {@link createAcpTransport}. */
+export type AcpTransportOptions = {
+  /** Byte stream from the agent process (e.g. child stdout). */
+  input: ReadableStream<Uint8Array>;
+  /** Byte stream to the agent process (e.g. child stdin). */
+  output: WritableStream<Uint8Array>;
+  /** Receives every `session/update` notification the agent sends. */
+  onSessionUpdate?: SessionUpdateHandler;
+  /** Called once when the transport closes. */
+  onClose?: TransportCloseHandler;
+};
+
+/**
+ * A connected ACP transport that carries JSON-RPC over NDJSON byte streams.
+ *
+ * Create one with {@link createAcpTransport}. After the transport closes the
+ * connection is not reusable.
+ */
+export type AcpTransport = {
+  /** Context for calling agent-side ACP methods. */
+  agent: ClientContext;
+  /** Promise that resolves when the transport closes. */
+  closed: Promise<void>;
+  /** AbortSignal that aborts when the transport closes. */
+  signal: AbortSignal;
+  /**
+   * Closes the transport and rejects pending requests.
+   *
+   * Safe to call more than once.
+   */
+  close(error?: unknown): void;
+};
+
+/**
+ * Opens a server-side ACP transport over NDJSON byte streams.
+ *
+ * The transport stays open until `close()` is called, the peer closes its
+ * end, or a protocol error tears down the connection.
+ *
+ * @example
+ * ```ts
+ * const transport = createAcpTransport({
+ *   input: childProcess.stdout,
+ *   output: childProcess.stdin,
+ *   onSessionUpdate(params, cx) {
+ *     console.log("session update", params)
+ *   },
+ *   onClose(error) {
+ *     console.log("transport closed", error)
+ *   },
+ * })
+ *
+ * // Call agent-side methods through the returned context:
+ * const response = await transport.agent.request("initialize", {
+ *   protocolVersion: 1,
+ *   clientInfo: { name: "kennel", version: "1.0.0" },
+ *   capabilities: {},
+ * })
+ * ```
+ */
+export function createAcpTransport(options: AcpTransportOptions): AcpTransport {
+  const stream: Stream = ndJsonStream(options.output, options.input);
+
+  const app: ClientApp = client({ name: "kennel-acp" });
+
+  if (options.onSessionUpdate) {
+    app.onNotification("session/update", (ctx) => {
+      void Promise.resolve(options.onSessionUpdate!(ctx.params, ctx.agent));
+    });
+  }
+
+  const connection: ClientConnection = app.connect(stream);
+
+  connection.closed.then(
+    () => options.onClose?.(),
+    (error: unknown) => options.onClose?.(error),
+  );
+
+  return {
+    agent: connection.agent,
+    closed: connection.closed,
+    signal: connection.signal,
+    close(error?: unknown) {
+      connection.close(error);
+    },
+  };
+}

package/kernel/packages/api/src/server/acp/types.ts

@@ -0,0 +1,89 @@
+/**
+ * ACP adapter types and live-event protocol.
+ *
+ * Each adapter identifies one agent harness that speaks ACP over stdio.
+ * The registry maps stable IDs to executable commands and capabilities.
+ */
+
+/** A capability tag an agent harness supports. */
+export type AgentCapability =
+  | "acp:tool_call"
+  | "acp:resource_read"
+  | "acp:prompt"
+  | "acp:completion"
+  | "acp:session_resume";
+
+/** One adapter entry mapping a stable agent ID to its runtime command. */
+export type AgentAdapter = {
+  /** Stable lowercase identifier. Example: "pi". */
+  id: string;
+  /** Human-readable label for UIs and logs. */
+  displayName: string;
+  /** Executable command (no path separators). */
+  command: string;
+  /** Arguments passed directly to the command. */
+  args: string[];
+  /** Absolute path to the agent's working folder. */
+  workingFolder: string;
+  /** Ordered list of supported ACP capabilities. */
+  capabilities: AgentCapability[];
+  /** Whether this adapter is active in the current deployment. */
+  enabled: boolean;
+  /** Optional note explaining state. */
+  note?: string;
+};
+
+/** A read-only snapshot of the current registry state. */
+export type AgentRegistry = {
+  adapters: AgentAdapter[];
+  enabledCount: number;
+  totalCount: number;
+};
+
+// ---------------------------------------------------------------------------
+// Live event types shared between server transport and browser UI
+// ---------------------------------------------------------------------------
+
+/** Connection lifecycle states. */
+export type ConnectionState =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "disconnecting"
+  | "disconnected"
+  | "error";
+
+/** Token usage reported at the end of a response. */
+export type TokenUsage = {
+  inputTokens: number;
+  outputTokens: number;
+};
+
+/**
+ * Events the agent streams to browser subscribers.
+ *
+ * Each event has a `type` discriminant. Text and thinking deltas
+ * arrive incrementally. Tool calls bracket a start and end event.
+ */
+export type LiveEvent =
+  | { type: "text-delta"; text: string }
+  | { type: "thinking-delta"; text: string }
+  | {
+      type: "tool-call-start";
+      callId: string;
+      name: string;
+      input: unknown;
+    }
+  | {
+      type: "tool-call-end";
+      callId: string;
+      output?: string;
+      error?: string;
+    }
+  | { type: "error"; message: string; code?: string }
+  | {
+      type: "done";
+      stopReason: string;
+      usage?: TokenUsage;
+    }
+  | { type: "cancelled" };