kennel 0.2.0 → 0.2.2

package/kernel/packages/api/src/server/acp-live-plugin.ts

@@ -0,0 +1,423 @@
+/**
+ * Vite plugin — live ACP agent session endpoints.
+ *
+ * Each session has a browser-facing UUID and an ACP sessionId returned
+ * by `session/new`. The ACP id is used in prompt, cancel, load, and resume.
+ */
+
+import { randomUUID } from "node:crypto";
+import { Readable, Writable } from "node:stream";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ApiHost } from "./host";
+
+import { sameOrigin } from "@raggle-ai/folder-plugin/endpoint";
+import localSessions from "@raggle-ai/local/sessions";
+
+import type { AcpTransport } from "./acp/transport";
+import type { AgentAdapter, LiveEvent } from "./acp/types";
+import { AcpProcessManager } from "./acp/process-manager";
+import { findAdapter } from "./acp/registry";
+import { createAcpTransport } from "./acp/transport";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function bodyJson(
+  request: IncomingMessage,
+): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of request)
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  return raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+}
+
+function reply(
+  response: ServerResponse,
+  status: number,
+  body: unknown,
+  ct = "application/json; charset=utf-8",
+) {
+  response.writeHead(status, {
+    "Content-Type": ct,
+    "Cache-Control": "no-store",
+  });
+  response.end(typeof body === "string" ? body : JSON.stringify(body));
+}
+
+/**
+ * Reject mutating ACP calls that do not come from the requested Origin (or,
+ * lacking one, a matching Referer). ACP live sessions spawn local agent
+ * processes, so a cross-site POST must never reach them.
+ */
+function guardMutation(
+  request: IncomingMessage,
+  response: ServerResponse,
+): boolean {
+  if (sameOrigin(request)) return false;
+  reply(response, 403, "Cross-origin mutations are not allowed", "text/plain");
+  return true;
+}
+
+/** Loopback-only Host check: ACP session endpoints never answer DNS names. */
+function loopbackHost(value: string | undefined): boolean {
+  if (!value) return false;
+  try {
+    const parsed = new URL(value.includes("://") ? value : `http://${value}`);
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return (
+      hostname === "127.0.0.1" ||
+      hostname === "localhost" ||
+      hostname === "::1" ||
+      hostname === "::ffff:127.0.0.1" ||
+      hostname.startsWith("127.")
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+
+type Session = {
+  adapter: AgentAdapter;
+  browserId: string;
+  acpId: string | null;
+  transport: AcpTransport | null;
+  processKey: string;
+  subscribers: Set<(event: LiveEvent) => void>;
+  error: string | null;
+};
+
+export function createAcpApi({
+  remoteAccess = false,
+}: { remoteAccess?: boolean } = {}) {
+  const manager = new AcpProcessManager();
+  const sessions = new Map<string, Session>();
+  let closed = false;
+
+  function broadcast(s: Session, event: LiveEvent) {
+    for (const fn of s.subscribers) fn(event);
+  }
+
+  // Load a stored local chat session (`client:nativeId`, or a raw native id for
+  // the adapter's own store) into the live agent, so prompts continue that
+  // conversation. Returns the native ACP session id.
+  async function loadSession(
+    transport: AcpTransport,
+    adapter: AgentAdapter,
+    resumeId: string,
+  ) {
+    const stored = await localSessions
+      .readLocalSession(resumeId)
+      .catch(() => undefined);
+    const native = stored
+      ? stored.id.slice(stored.id.indexOf(":") + 1)
+      : resumeId;
+    await transport.agent.request("session/load", {
+      cwd: stored?.folder ?? adapter.workingFolder,
+      mcpServers: [],
+      sessionId: native,
+    });
+    return native;
+  }
+
+  async function startSession(
+    client?: string,
+    resumeId?: string,
+  ): Promise<Session> {
+    if (closed) throw new Error("Core is shutting down");
+    const adapter = findAdapter(client ?? "pi");
+    if (!adapter?.enabled)
+      throw new Error(`No ACP adapter available for "${client ?? "pi"}"`);
+
+    const browserId = randomUUID();
+    const processKey = `acp-${browserId.slice(0, 8)}`;
+
+    const handle = manager.start(processKey, adapter);
+    const transport = createAcpTransport({
+      input: Readable.toWeb(handle.stdout) as unknown as ReadableStream<Uint8Array>,
+      output: Writable.toWeb(handle.stdin) as WritableStream<Uint8Array>,
+      onClose: (err) => {
+        const s = sessions.get(browserId);
+        if (s) {
+          s.error = err ? String(err) : null;
+          s.transport = null;
+        }
+      },
+    });
+
+    await transport.agent.request("initialize", {
+      protocolVersion: 1,
+      clientInfo: { name: "kennel", version: "1.0.0" },
+      capabilities: {},
+    });
+    // Skip creating an empty session when the caller immediately resumes a
+    // stored one.
+    const acpId = resumeId
+      ? await loadSession(transport, adapter, resumeId)
+      : (
+          (await transport.agent.request("session/new", {
+            cwd: adapter.workingFolder,
+            mcpServers: [],
+          })) as { sessionId: string }
+        ).sessionId;
+
+    const session: Session = {
+      adapter,
+      browserId,
+      acpId,
+      transport,
+      processKey,
+      subscribers: new Set(),
+      error: null,
+    };
+    sessions.set(browserId, session);
+    return session;
+  }
+
+  async function destroySession(s: Session) {
+    s.transport?.close();
+    s.transport = null;
+    await manager.stop(s.processKey, 2_000, 1_000).catch(() => {});
+    s.subscribers.clear();
+    sessions.delete(s.browserId);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Plugin
+  // ---------------------------------------------------------------------------
+
+  return {
+    async close() {
+      closed = true;
+      await Promise.all([...sessions.values()].map(destroySession));
+      await manager.stopAll(2_000, 1_000);
+    },
+    name: "kennel-acp-live",
+    attach(server: ApiHost) {
+      server.use(async (request, response, next) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        const method = request.method ?? "GET";
+        if (!url.pathname.startsWith("/api/acp/")) return next();
+
+        // Live agent sessions spawn processes on the server: they exist only
+        // for local loopback development. Remote bindings reject them all,
+        // and DNS-rebinding Host headers (e.g. an attacker domain resolving
+        // to 127.0.0.1) never reach the agent endpoints.
+        if (remoteAccess) {
+          reply(
+            response,
+            403,
+            "ACP live sessions are disabled for remote access",
+            "text/plain",
+          );
+          return;
+        }
+        if (
+          url.pathname.startsWith("/api/acp/") &&
+          !loopbackHost(request.headers.host)
+        ) {
+          reply(response, 403, "Untrusted Host header", "text/plain");
+          return;
+        }
+
+        // SSE stream
+        const streamMatch = /^\/api\/acp\/stream\/([a-f0-9-]+)$/.exec(
+          url.pathname,
+        );
+        if (streamMatch?.[1] && method === "GET") {
+          const s = sessions.get(streamMatch[1]);
+          if (!s)
+            return reply(response, 404, "Session not found", "text/plain");
+
+          response.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-store",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no",
+          });
+
+          const onEvent = (event: LiveEvent) => {
+            if (!response.writableEnded)
+              response.write(`data: ${JSON.stringify(event)}\n\n`);
+          };
+          s.subscribers.add(onEvent);
+
+          request.on("close", () => {
+            s.subscribers.delete(onEvent);
+            if (!response.writableEnded) response.end();
+          });
+          return;
+        }
+
+        // Connect
+        if (url.pathname === "/api/acp/connect" && method === "POST") {
+          if (guardMutation(request, response)) return;
+          try {
+            const { client, resumeId } = await bodyJson(request);
+            const s = await startSession(
+              client ? String(client) : undefined,
+              resumeId ? String(resumeId) : undefined,
+            );
+            return reply(response, 200, {
+              sessionId: s.browserId,
+              connectionState: "connected",
+            });
+          } catch (err) {
+            return reply(response, 500, {
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
+
+        // Send
+        if (url.pathname === "/api/acp/send" && method === "POST") {
+          if (guardMutation(request, response)) return;
+          const { sessionId, text } = await bodyJson(request);
+          if (!sessionId || !text)
+            return reply(
+              response,
+              400,
+              "Missing sessionId or text",
+              "text/plain",
+            );
+
+          const s = sessions.get(String(sessionId));
+          if (!s?.transport || !s.acpId)
+            return reply(response, 404, "Session not found", "text/plain");
+
+          s.transport.agent
+            .request("session/prompt", {
+              sessionId: s.acpId,
+              prompt: [{ type: "text", text }],
+            })
+            .then((result: unknown) => {
+              const data = result as {
+                content?: Array<{
+                  type: string;
+                  text?: string;
+                  name?: string;
+                  input?: unknown;
+                }>;
+                stopReason?: string;
+                usage?: { inputTokens: number; outputTokens: number };
+              };
+              if (data?.content) {
+                for (const block of data.content) {
+                  if (block.type === "text" && block.text) {
+                    broadcast(s, { type: "text-delta", text: block.text });
+                  } else if (block.type === "tool_call") {
+                    const callId = randomUUID();
+                    broadcast(s, {
+                      type: "tool-call-start",
+                      callId,
+                      name: block.name ?? "unknown",
+                      input: block.input,
+                    });
+                    broadcast(s, { type: "tool-call-end", callId });
+                  }
+                }
+              }
+              if (data?.stopReason) {
+                broadcast(s, {
+                  type: "done",
+                  stopReason: data.stopReason,
+                  usage: data.usage,
+                });
+              }
+            })
+            .catch((err: unknown) => {
+              broadcast(s, {
+                type: "error",
+                message: err instanceof Error ? err.message : String(err),
+              });
+            });
+
+          return reply(response, 202, { accepted: true });
+        }
+
+        // Cancel
+        if (url.pathname === "/api/acp/cancel" && method === "POST") {
+          if (guardMutation(request, response)) return;
+          const { sessionId } = await bodyJson(request);
+          const s = sessions.get(String(sessionId ?? ""));
+          if (!s?.transport)
+            return reply(response, 404, "Session not found", "text/plain");
+          try {
+            s.transport.agent.notify("$/cancel_request", {});
+          } catch {
+            /* best-effort */
+          }
+          broadcast(s, { type: "cancelled" });
+          return reply(response, 200, { cancelled: true });
+        }
+
+        // Disconnect
+        if (url.pathname === "/api/acp/disconnect" && method === "POST") {
+          if (guardMutation(request, response)) return;
+          const { sessionId } = await bodyJson(request);
+          const s = sessions.get(String(sessionId ?? ""));
+          if (!s)
+            return reply(response, 404, "Session not found", "text/plain");
+          await destroySession(s);
+          return reply(response, 200, { disconnected: true });
+        }
+
+        // Resume
+        if (url.pathname === "/api/acp/resume" && method === "POST") {
+          if (guardMutation(request, response)) return;
+          const { sessionId, resumeId } = await bodyJson(request);
+          if (!resumeId)
+            return reply(response, 400, "Missing resumeId", "text/plain");
+          const s = sessions.get(String(sessionId ?? ""));
+          if (!s?.transport)
+            return reply(response, 404, "Session not found", "text/plain");
+          try {
+            s.acpId = await loadSession(
+              s.transport,
+              s.adapter,
+              String(resumeId),
+            );
+            return reply(response, 200, {
+              sessionId: s.browserId,
+              resumed: true,
+            });
+          } catch (err) {
+            return reply(response, 500, {
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
+
+        // Reconnect
+        if (url.pathname === "/api/acp/reconnect" && method === "POST") {
+          if (guardMutation(request, response)) return;
+          const { sessionId } = await bodyJson(request);
+          const old = sessions.get(String(sessionId ?? ""));
+          if (!old)
+            return reply(response, 404, "Session not found", "text/plain");
+
+          await destroySession(old);
+
+          try {
+            const s = await startSession();
+            return reply(response, 200, {
+              sessionId: s.browserId,
+              connectionState: "connected",
+            });
+          } catch (err) {
+            return reply(response, 500, {
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
+
+        next();
+      });
+    },
+  };
+}

package/kernel/packages/api/src/server/api/create-agent-file.ts

@@ -0,0 +1,46 @@
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import type { ApiRouteSpec } from "@raggle-ai/folder-plugin/endpoint";
+import { apiError, jsonResponse } from "@raggle-ai/folder-plugin/endpoint";
+
+export type CreateAgentFileContext = {
+  /**
+   * Resolves an authored folder path to a real path inside the viewer root.
+   * Throws for missing, out-of-root, or symlink-escaped targets.
+   */
+  resolve: (value: string | null) => string;
+};
+
+/**
+ * Host action: write a freshly created, empty AGENTS.md into an authorized
+ * folder. The created file's path is returned so the caller can open it in
+ * the default Markdown app; the route itself never launches an app, which
+ * keeps it testable and harmless on remote hosts. A folder that already has
+ * an AGENTS.md is rejected with a conflict.
+ */
+export const createAgentFileRoute: ApiRouteSpec<CreateAgentFileContext> = {
+  method: "POST",
+  maxBodyBytes: 0,
+  async handle({ context, query, response }) {
+    let folder: string;
+    try {
+      folder = context.resolve(query.get("path"));
+    } catch (error) {
+      throw apiError(
+        "not-found",
+        error instanceof Error ? error.message : "Folder not found",
+      );
+    }
+    const target = resolve(folder, "AGENTS.md");
+    try {
+      await writeFile(target, "", { flag: "wx" });
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+        throw apiError("conflict", "AGENTS.md already exists in this folder");
+      }
+      throw apiError("failed", "Could not create AGENTS.md");
+    }
+    jsonResponse(response, 200, { path: target });
+  },
+};

package/kernel/packages/api/src/server/api/document-edit.ts

@@ -0,0 +1,125 @@
+import { randomUUID } from "node:crypto";
+import { documentEditSchema, routes } from "../../contracts/schemas";
+import {
+  readFile,
+  realpath,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import {
+  dirname,
+  extname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+
+import type { ApiRouteSpec } from "@raggle-ai/folder-plugin/endpoint";
+import { replaceSelection } from "../../shared/selection";
+import {
+  apiError,
+  jsonResponse,
+  parseJsonBody,
+} from "@raggle-ai/folder-plugin/endpoint";
+
+const pending = new Map<string, Promise<unknown>>();
+
+export async function editDocument(
+  folder: string,
+  input: Record<string, unknown>,
+) {
+  const { path, original, start, end, replacement } = input;
+  if (
+    typeof path !== "string" ||
+    typeof original !== "string" ||
+    typeof replacement !== "string" ||
+    typeof start !== "number" ||
+    typeof end !== "number"
+  )
+    throw apiError("bad-request", "Invalid document edit.");
+  if (![".md", ".markdown"].includes(extname(path).toLowerCase()))
+    throw apiError("bad-request", "Only Markdown notes can be edited.");
+  const root = await realpath(folder);
+  const target = await realpath(resolve(root, path));
+  const local = relative(root, target);
+  if (
+    !local ||
+    local === ".." ||
+    local.startsWith(`..${sep}`) ||
+    isAbsolute(local)
+  )
+    throw apiError("forbidden", "The document must be inside its folder.");
+  let content: string;
+  try {
+    content = replaceSelection(original, start, end, replacement);
+  } catch {
+    throw apiError("bad-request", "Invalid selection range.");
+  }
+  // Serialize our own writes; re-read disk for each proposal, not a cached ETag.
+  const previous = pending.get(target) ?? Promise.resolve();
+  const operation = previous
+    .catch(() => {})
+    .then(async () => {
+      const details = await stat(target);
+      if (!details.isFile() || details.nlink !== 1)
+        throw apiError(
+          "forbidden",
+          "Only regular, unlinked files can be edited.",
+        );
+      if ((await readFile(target, "utf8")) !== original)
+        throw apiError(
+          "conflict",
+          "This note changed on disk. Close this preview, reload the note, and try again.",
+        );
+      const temporary = resolve(
+        dirname(target),
+        `.kennel-edit-${randomUUID()}.tmp`,
+      );
+      try {
+        await writeFile(temporary, content, {
+          flag: "wx",
+          mode: details.mode & 0o777,
+        });
+        if ((await readFile(target, "utf8")) !== original)
+          throw apiError(
+            "conflict",
+            "This note changed on disk. Reload before applying an edit.",
+          );
+        await rename(temporary, target);
+      } finally {
+        await unlink(temporary).catch(() => {});
+      }
+      return content;
+    });
+  pending.set(target, operation);
+  try {
+    return await operation;
+  } finally {
+    if (pending.get(target) === operation) pending.delete(target);
+  }
+}
+
+export const documentEditRoute: ApiRouteSpec<{
+  authorize: (folder: string) => string;
+  lockedFile?: string;
+}> = {
+  method: "POST",
+  maxBodyBytes: 2 * 1024 * 1024,
+  async handle({ body, context, response }) {
+    const parsed = documentEditSchema.safeParse(parseJsonBody(body));
+    if (!parsed.success) throw apiError("bad-request", "Invalid document edit.");
+    const input = parsed.data;
+    const folder = context.authorize(input.folder);
+    if (
+      context.lockedFile &&
+      (typeof input.path !== "string" ||
+        (await realpath(resolve(folder, input.path))) !== context.lockedFile)
+    )
+      throw apiError("forbidden", "Only the selected document can be edited.");
+    await editDocument(folder, input);
+    jsonResponse(response, 200, routes.documentEdit.response.parse({ saved: true }));
+  },
+};

package/kernel/packages/api/src/server/api/open-path.ts

@@ -0,0 +1,40 @@
+import { execFile } from "node:child_process";
+
+import type { ApiRouteSpec } from "@raggle-ai/folder-plugin/endpoint";
+import { apiError } from "@raggle-ai/folder-plugin/endpoint";
+
+export type OpenPathContext = {
+  /**
+   * Resolves an authored path to a real path inside the viewer root.
+   * Throws for missing, out-of-root, or symlink-escaped targets.
+   */
+  resolve: (value: string | null) => string;
+};
+
+/**
+ * Host action: open a physical file in the operating system's default app.
+ * Declarative route spec shared shape with document-edit; the middleware keeps
+ * the remote-access gate (403) in front of it, exactly like every host action.
+ */
+export const openPathRoute: ApiRouteSpec<OpenPathContext> = {
+  method: "GET",
+  async handle({ context, query, response }) {
+    let target: string;
+    try {
+      target = context.resolve(query.get("path"));
+    } catch (error) {
+      throw apiError(
+        "not-found",
+        error instanceof Error ? error.message : "Path not found",
+      );
+    }
+    await new Promise<void>((done, fail) => {
+      execFile("/usr/bin/open", [target], (error) => {
+        if (error) fail(apiError("failed", "Could not open path"));
+        else done();
+      });
+    });
+    response.writeHead(204);
+    response.end();
+  },
+};