chainlesschain 0.165.10 → 0.166.0

package/src/lib/app-server/bounded-queue.js

@@ -0,0 +1,87 @@
+export class QueueOverloadedError extends Error {
+  constructor(message, { retryAfterMs = 100, limit, queued } = {}) {
+    super(message);
+    this.name = "QueueOverloadedError";
+    this.code = "CC_APP_SERVER_OVERLOADED";
+    this.retryAfterMs = retryAfterMs;
+    this.limit = limit;
+    this.queued = queued;
+  }
+}
+
+export class BoundedAsyncQueue {
+  constructor({
+    maxItems = 256,
+    maxBytes = 4 * 1024 * 1024,
+    sizeOf = null,
+  } = {}) {
+    this.maxItems = Math.max(1, Number(maxItems) || 256);
+    this.maxBytes = Math.max(1, Number(maxBytes) || 4 * 1024 * 1024);
+    this.sizeOf =
+      sizeOf || ((value) => Buffer.byteLength(String(value), "utf8"));
+    this.items = [];
+    this.bytes = 0;
+    this.closed = false;
+    this.waiters = [];
+  }
+
+  push(value) {
+    if (this.closed) throw new Error("bounded queue is closed");
+    const bytes = Math.max(0, Number(this.sizeOf(value)) || 0);
+    if (
+      this.items.length >= this.maxItems ||
+      this.bytes + bytes > this.maxBytes
+    ) {
+      throw new QueueOverloadedError("App Server queue capacity exceeded", {
+        limit: this.maxItems,
+        queued: this.items.length,
+      });
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter.resolve({ value, done: false });
+      return;
+    }
+    this.items.push({ value, bytes });
+    this.bytes += bytes;
+  }
+
+  shift() {
+    const entry = this.items.shift();
+    if (!entry) return undefined;
+    this.bytes -= entry.bytes;
+    return entry.value;
+  }
+
+  async next() {
+    const value = this.shift();
+    if (value !== undefined) return { value, done: false };
+    if (this.closed) return { value: undefined, done: true };
+    return new Promise((resolve, reject) =>
+      this.waiters.push({ resolve, reject }),
+    );
+  }
+
+  close(error = null) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      if (error) waiter.reject(error);
+      else waiter.resolve({ value: undefined, done: true });
+    }
+  }
+
+  snapshot() {
+    return Object.freeze({
+      queuedItems: this.items.length,
+      queuedBytes: this.bytes,
+      maxItems: this.maxItems,
+      maxBytes: this.maxBytes,
+      closed: this.closed,
+    });
+  }
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}

package/src/lib/app-server/cli-agent-kernel-adapter.js

@@ -0,0 +1,309 @@
+import { PassThrough } from "node:stream";
+import { randomUUID } from "node:crypto";
+import {
+  assertSandboxAvailable,
+  normalizeAgentSandboxMode,
+} from "../agent-sandbox.js";
+
+const PERMISSION_MODES = new Set(["default", "manual", "dontAsk", "plan"]);
+
+function adapterError(code, message) {
+  const error = new Error(message);
+  error.name = "CliAgentKernelAdapterError";
+  error.code = code;
+  return error;
+}
+
+function writeLine(input, value) {
+  if (input.destroyed || input.writableEnded) {
+    throw adapterError(
+      "CC_APP_SERVER_AGENT_SESSION_CLOSED",
+      "Agent Kernel input stream is closed",
+    );
+  }
+  input.write(`${JSON.stringify(value)}\n`);
+}
+
+function approvalBoolean(decision) {
+  return ["acceptOnce", "acceptForTurn", "acceptForSession"].includes(
+    decision?.kind,
+  );
+}
+
+function outputCollector(onEvent, onStderr) {
+  let stdout = "";
+  let stderr = "";
+  return {
+    writeOut(chunk) {
+      stdout += String(chunk);
+      for (;;) {
+        const index = stdout.indexOf("\n");
+        if (index < 0) break;
+        const line = stdout.slice(0, index).trim();
+        stdout = stdout.slice(index + 1);
+        if (!line) continue;
+        let event;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          event = { type: "raw", subtype: "invalid_json", text: line };
+        }
+        onEvent(event);
+      }
+      return true;
+    },
+    writeErr(chunk) {
+      stderr += String(chunk);
+      for (;;) {
+        const index = stderr.indexOf("\n");
+        if (index < 0) break;
+        const line = stderr.slice(0, index).trim();
+        stderr = stderr.slice(index + 1);
+        if (line) onStderr(line);
+      }
+      return true;
+    },
+    flush() {
+      if (stdout.trim()) {
+        try {
+          onEvent(JSON.parse(stdout.trim()));
+        } catch {
+          onEvent({
+            type: "raw",
+            subtype: "invalid_json",
+            text: stdout.trim(),
+          });
+        }
+      }
+      if (stderr.trim()) onStderr(stderr.trim());
+      stdout = "";
+      stderr = "";
+    },
+  };
+}
+
+export class CliAgentKernelAdapter {
+  constructor({
+    cwd = process.cwd(),
+    sandboxMode = "workspace-write",
+    sandboxEngine = null,
+    allowedPermissionModes = PERMISSION_MODES,
+    sessionOptions = {},
+    dependencies = {},
+  } = {}) {
+    this.cwd = cwd;
+    this.sandboxMode = sandboxMode;
+    this.sandboxEngine = sandboxEngine;
+    this.allowedPermissionModes = new Set(allowedPermissionModes);
+    this.sessionOptions = { ...sessionOptions };
+    this.dependencies = dependencies;
+    this.sessions = new Map();
+  }
+
+  async _createSession(threadId, turnOptions = {}) {
+    const { runAgentHeadlessStream } =
+      await import("../../runtime/headless-stream.js");
+    const permissionMode = String(
+      turnOptions.permissionMode ||
+        this.sessionOptions.permissionMode ||
+        "default",
+    );
+    if (!this.allowedPermissionModes.has(permissionMode)) {
+      throw adapterError(
+        "CC_APP_SERVER_PERMISSION_MODE_DENIED",
+        `permission mode is not allowed by the App Server: ${permissionMode}`,
+      );
+    }
+    const sandbox = normalizeAgentSandboxMode(
+      this.sandboxMode,
+      this.sandboxEngine || true,
+      {
+        cwd: this.cwd,
+        network: false,
+        settings: {
+          enabled: true,
+          failIfUnavailable: true,
+          allowUnsandboxedCommands: false,
+        },
+      },
+    );
+    assertSandboxAvailable(sandbox);
+
+    const input = new PassThrough();
+    const session = {
+      threadId,
+      input,
+      current: null,
+      eventChain: Promise.resolve(),
+      closed: false,
+      failure: null,
+      runPromise: null,
+      collector: null,
+    };
+    const queueEvent = (event) => {
+      const current = session.current;
+      session.eventChain = session.eventChain.then(async () => {
+        if (!current) return;
+        await current.emit(event);
+        if (event.type === "approval_request") {
+          let decision = {
+            kind: "decline",
+            reason: "approval host unavailable",
+          };
+          try {
+            decision = await current.requestApproval(event);
+          } catch (error) {
+            decision = {
+              kind: "decline",
+              reason: String(error?.message || error).slice(0, 2048),
+            };
+          }
+          writeLine(input, {
+            type: "approval",
+            id: event.id,
+            approve: approvalBoolean(decision),
+            binding: event.binding,
+          });
+        }
+        if (event.type === "result") {
+          session.current = null;
+          current.resolve(event);
+        }
+      });
+      session.eventChain.catch((error) => {
+        if (session.current === current) session.current = null;
+        current?.reject(error);
+      });
+    };
+    const collector = outputCollector(queueEvent, (line) => {
+      const current = session.current;
+      if (!current) return;
+      queueEvent({ type: "raw", subtype: "stderr", text: line });
+    });
+    session.collector = collector;
+    session.runPromise = runAgentHeadlessStream(
+      {
+        ...this.sessionOptions,
+        model: turnOptions.model || this.sessionOptions.model,
+        provider: turnOptions.provider || this.sessionOptions.provider,
+        baseUrl: this.sessionOptions.baseUrl,
+        apiKey: this.sessionOptions.apiKey,
+        sessionId: threadId,
+        cwd: this.cwd,
+        permissionMode,
+        sandbox,
+        interactiveApprovals: true,
+        includePartialMessages: true,
+        ephemeral: false,
+      },
+      {
+        ...this.dependencies,
+        input,
+        writeOut: collector.writeOut,
+        writeErr: collector.writeErr,
+      },
+    )
+      .then(async (outcome) => {
+        collector.flush();
+        await session.eventChain;
+        session.closed = true;
+        if (session.current) {
+          session.current.reject(
+            adapterError(
+              "CC_APP_SERVER_AGENT_SESSION_CLOSED",
+              "Agent Kernel session closed before the turn completed",
+            ),
+          );
+          session.current = null;
+        }
+        return outcome;
+      })
+      .catch((error) => {
+        session.failure = error;
+        session.closed = true;
+        if (session.current) {
+          session.current.reject(error);
+          session.current = null;
+        }
+        throw error;
+      });
+    session.runPromise.catch(() => {});
+    this.sessions.set(threadId, session);
+    return session;
+  }
+
+  async _session(threadId, options) {
+    const existing = this.sessions.get(threadId);
+    if (existing && !existing.closed) return existing;
+    if (existing?.failure) throw existing.failure;
+    return this._createSession(threadId, options);
+  }
+
+  async startTurn({
+    threadId,
+    turnId,
+    input,
+    options = {},
+    emit,
+    requestApproval,
+  }) {
+    const session = await this._session(threadId, options);
+    if (session.current) {
+      throw adapterError(
+        "CC_APP_SERVER_TURN_ACTIVE",
+        `thread already has an active turn: ${threadId}`,
+      );
+    }
+    const prompt = String(input || "").trim();
+    if (!prompt) {
+      throw adapterError(
+        "CC_APP_SERVER_INVALID_INPUT",
+        "turn input must contain non-empty text",
+      );
+    }
+    const terminal = new Promise((resolve, reject) => {
+      session.current = {
+        turnId,
+        emit,
+        requestApproval,
+        resolve,
+        reject,
+      };
+    });
+    writeLine(session.input, {
+      type: "user",
+      text: prompt,
+      images: Array.isArray(options.images) ? options.images : undefined,
+    });
+    return terminal;
+  }
+
+  async interruptTurn(threadId, turnId) {
+    const session = this.sessions.get(threadId);
+    if (!session?.current || session.current.turnId !== turnId) return false;
+    writeLine(session.input, { type: "interrupt" });
+    return true;
+  }
+
+  async forkThread(sourceThreadId, requestId = randomUUID()) {
+    const { forkSession, sessionExists } =
+      await import("../../harness/jsonl-session-store.js");
+    if (!sessionExists(sourceThreadId)) return null;
+    return forkSession(sourceThreadId, { requestId });
+  }
+
+  async closeThread(threadId) {
+    const session = this.sessions.get(threadId);
+    if (!session) return false;
+    session.input.end();
+    await session.runPromise.catch(() => {});
+    this.sessions.delete(threadId);
+    return true;
+  }
+
+  async close() {
+    await Promise.all(
+      [...this.sessions.keys()].map((threadId) => this.closeThread(threadId)),
+    );
+  }
+}

package/src/lib/app-server/protocol.js

@@ -0,0 +1,125 @@
+import { readFileSync } from "node:fs";
+import { validate } from "../json-schema-validate.js";
+
+const schema = JSON.parse(
+  readFileSync(
+    new URL("../../generated/cc-agent-protocol.schema.json", import.meta.url),
+    "utf8",
+  ),
+);
+
+export const APP_SERVER_PROTOCOL_VERSION = schema["x-cc-protocol"].version;
+export const APP_SERVER_MIN_PROTOCOL_VERSION =
+  schema["x-cc-protocol"].minimumCompatibleVersion;
+export const APP_SERVER_FEATURES = Object.freeze([
+  ...schema["x-cc-protocol"].features,
+]);
+export const APP_SERVER_SCHEMA = schema;
+
+export const JSON_RPC_ERROR = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  OVERLOADED: -32001,
+  NOT_INITIALIZED: -32002,
+  NOT_FOUND: -32004,
+  CONFLICT: -32009,
+  INTERRUPTED: -32010,
+});
+
+export class JsonRpcError extends Error {
+  constructor(code, message, data = null) {
+    super(message);
+    this.name = "JsonRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+export function validateAppServerMessage(value) {
+  const result = validate(value, APP_SERVER_SCHEMA);
+  return Object.freeze({
+    ok: result.valid,
+    errors: Object.freeze(
+      result.errors.map((error) =>
+        Object.freeze({
+          path: error.instancePath || error.schemaPath || "#",
+          message: error.message || error.code || "invalid message",
+        }),
+      ),
+    ),
+  });
+}
+
+export function rpcResult(id, result) {
+  return { jsonrpc: "2.0", id, result: result ?? null };
+}
+
+export function rpcError(id, error) {
+  const code = Number.isInteger(error?.code)
+    ? error.code
+    : JSON_RPC_ERROR.INTERNAL_ERROR;
+  const output = {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: {
+      code,
+      message:
+        code === JSON_RPC_ERROR.INTERNAL_ERROR
+          ? "Internal App Server error"
+          : String(error?.message || "Request failed").slice(0, 4096),
+    },
+  };
+  if (error?.data != null) output.error.data = error.data;
+  return output;
+}
+
+export function rpcNotification(method, params) {
+  return { jsonrpc: "2.0", method, params: params ?? null };
+}
+
+export function negotiateProtocol(params = {}) {
+  const clientMax = Number(params.protocolVersion);
+  const clientMin = Number(params.minimumProtocolVersion);
+  if (
+    !Number.isSafeInteger(clientMax) ||
+    !Number.isSafeInteger(clientMin) ||
+    clientMin > clientMax
+  ) {
+    throw new JsonRpcError(
+      JSON_RPC_ERROR.INVALID_PARAMS,
+      "initialize requires a valid protocol version range",
+    );
+  }
+  const minimum = Math.max(clientMin, APP_SERVER_MIN_PROTOCOL_VERSION);
+  const maximum = Math.min(clientMax, APP_SERVER_PROTOCOL_VERSION);
+  if (minimum > maximum) {
+    throw new JsonRpcError(
+      JSON_RPC_ERROR.INVALID_PARAMS,
+      "client and server protocol ranges do not overlap",
+      {
+        client: { minimum: clientMin, maximum: clientMax },
+        server: {
+          minimum: APP_SERVER_MIN_PROTOCOL_VERSION,
+          maximum: APP_SERVER_PROTOCOL_VERSION,
+        },
+      },
+    );
+  }
+  const requested = Array.isArray(params.features)
+    ? new Set(params.features.map(String))
+    : null;
+  const features = requested
+    ? APP_SERVER_FEATURES.filter((feature) => requested.has(feature))
+    : [...APP_SERVER_FEATURES];
+  return Object.freeze({
+    protocolVersion: maximum,
+    minimumProtocolVersion: APP_SERVER_MIN_PROTOCOL_VERSION,
+    features: Object.freeze(features),
+    downgraded:
+      maximum !== APP_SERVER_PROTOCOL_VERSION ||
+      features.length !== APP_SERVER_FEATURES.length,
+  });
+}