@theokit/acp 0.1.0

package/dist/index.cjs

@@ -0,0 +1,681 @@
+'use strict';
+
+var stream = require('stream');
+var acp2 = require('@agentclientprotocol/sdk');
+var crypto = require('crypto');
+var fs = require('fs');
+var path = require('path');
+var sdk = require('@theokit/sdk');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var acp2__namespace = /*#__PURE__*/_interopNamespace(acp2);
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// src/serve.ts
+
+// src/agent-resolver.ts
+function looksLikeSDKAgent(value) {
+  return typeof value === "object" && value !== null && typeof value.agentId === "string" && typeof value.send === "function";
+}
+var InvalidAgentError = class extends Error {
+  name = "InvalidAgentError";
+};
+function resolveAgentFactory(input, options = {}) {
+  const log = options.log ?? ((msg) => process.stderr.write(`${msg}
+`));
+  if (typeof input === "function") {
+    return input;
+  }
+  if (looksLikeSDKAgent(input)) {
+    let warned = false;
+    return (_sessionId) => {
+      if (!warned) {
+        warned = true;
+        log(
+          "[acp] WARN: serveAcp received a single SDKAgent instance; sessions will share conversation state. Pass a factory (sessionId) => Agent.create(...) for per-session isolation (D351)."
+        );
+      }
+      return input;
+    };
+  }
+  throw new InvalidAgentError(
+    "serveAcp({ agent }) must receive an SDKAgent or a factory (sessionId) => SDKAgent | Promise<SDKAgent>"
+  );
+}
+function buildInitializeResponse(_params, deps) {
+  const userCaps = deps.capabilities ?? {};
+  return {
+    protocolVersion: acp2__namespace.PROTOCOL_VERSION,
+    agentCapabilities: {
+      loadSession: userCaps.loadSession ?? true,
+      promptCapabilities: {
+        image: userCaps.prompt?.image ?? true,
+        audio: userCaps.prompt?.audio ?? false,
+        embeddedContext: userCaps.prompt?.embeddedContext ?? true
+      }
+    },
+    authMethods: []
+  };
+}
+var ACP_ERR = {
+  INVALID_REQUEST: -32602,
+  INTERNAL_ERROR: -32603,
+  INVALID_SESSION: -32001,
+  AUTH_REQUIRED: -32002
+};
+function resolveCwdOrError(rawCwd) {
+  if (typeof rawCwd !== "string" || rawCwd.length === 0) {
+    return {
+      ok: false,
+      error: { code: ACP_ERR.INVALID_REQUEST, message: "cwd is required" }
+    };
+  }
+  const resolved = path__default.default.resolve(rawCwd);
+  if (!fs.existsSync(resolved)) {
+    return {
+      ok: false,
+      error: { code: ACP_ERR.INVALID_REQUEST, message: `cwd not found: ${resolved}` }
+    };
+  }
+  return { ok: true, value: resolved };
+}
+async function handleNewSession(params, deps) {
+  const cwdResult = resolveCwdOrError(params.cwd);
+  if (!cwdResult.ok) return { error: cwdResult.error };
+  const sessionId = crypto.randomUUID();
+  let agent;
+  try {
+    agent = await deps.factory(sessionId);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    deps.log(`[acp] new_session factory threw: ${msg}`);
+    return {
+      error: {
+        code: ACP_ERR.INTERNAL_ERROR,
+        message: `agent factory threw: ${msg}`
+      }
+    };
+  }
+  const session = {
+    sessionId,
+    agent,
+    createdAt: Date.now(),
+    lastUsedAt: Date.now(),
+    abortController: new AbortController(),
+    cwd: cwdResult.value
+  };
+  deps.store.create(session);
+  return { response: { sessionId } };
+}
+var STORAGE_HINT = " \u2014 if running on serverless/multi-host infra, pass conversationStorage to Agent.create (see docs/recipes/conversation-storage-postgres.md)";
+async function handleLoadSession(params, deps) {
+  const cwdResult = resolveCwdOrError(params.cwd);
+  if (!cwdResult.ok) return { error: cwdResult.error };
+  if (deps.store.has(params.sessionId)) {
+    return {
+      error: {
+        code: ACP_ERR.INVALID_REQUEST,
+        message: `session ${params.sessionId} already loaded`
+      }
+    };
+  }
+  let agent;
+  try {
+    agent = await sdk.Agent.resume(params.sessionId, { local: { cwd: cwdResult.value } });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    deps.log(`[acp] load_session Agent.resume threw for ${params.sessionId}: ${msg}`);
+    return {
+      error: {
+        code: ACP_ERR.INVALID_SESSION,
+        message: `session not found: ${params.sessionId}${STORAGE_HINT}`
+      }
+    };
+  }
+  const session = {
+    sessionId: params.sessionId,
+    agent,
+    createdAt: Date.now(),
+    lastUsedAt: Date.now(),
+    abortController: new AbortController(),
+    cwd: cwdResult.value
+  };
+  deps.store.create(session);
+  return { response: {} };
+}
+async function handleForkSession(params, deps) {
+  const parent = deps.store.get(params.sessionId);
+  if (parent === void 0) {
+    return {
+      error: {
+        code: ACP_ERR.INVALID_SESSION,
+        message: `parent session not loaded: ${params.sessionId}`
+      }
+    };
+  }
+  parent.cwd;
+  if (typeof params.cwd === "string" && params.cwd.length > 0) {
+    const cwdResult = resolveCwdOrError(params.cwd);
+    if (!cwdResult.ok) return { error: cwdResult.error };
+    cwdResult.value;
+  }
+  return {
+    error: {
+      code: ACP_ERR.INVALID_REQUEST,
+      message: "session/fork is deferred to @theokit/acp v0.2 \u2014 current SDK fork is a one-shot sub-run, not a session split"
+    }
+  };
+}
+function handleListSessions(_params, store) {
+  const sessions = store.list().map((s) => ({
+    sessionId: s.sessionId,
+    cwd: s.cwd,
+    title: s.agent.agentId,
+    lastUpdatedAt: new Date(s.lastUsedAt).toISOString()
+  }));
+  return { sessions };
+}
+function handleCancel(params, deps) {
+  const session = deps.store.get(params.sessionId);
+  if (session === void 0) return;
+  session.lastUsedAt = Date.now();
+  if (!session.abortController.signal.aborted) {
+    session.abortController.abort("cancelled by ACP client");
+  }
+}
+
+// src/translator.ts
+var MAX_CONSECUTIVE_SEND_FAILURES = 10;
+function toolKind(name) {
+  const n = name.toLowerCase();
+  if (n === "read_file" || n === "list_dir" || n === "git_diff" || n === "search_text")
+    return "read";
+  if (n === "write_file" || n === "apply_patch") return "edit";
+  if (n === "run_command" || n === "run_vitest") return "execute";
+  if (n === "web_search" || n === "fetch_url") return "fetch";
+  return "other";
+}
+function mapToolStatus(sdkStatus) {
+  if (sdkStatus === "completed") return "completed";
+  if (sdkStatus === "error") return "failed";
+  return "in_progress";
+}
+function textChunk(text) {
+  return { type: "text", text };
+}
+async function safeNotify(conn, sessionId, update, state, log) {
+  if (state.bailed) return;
+  try {
+    await conn.sessionUpdate({ sessionId, update });
+    state.consecutiveFailures = 0;
+  } catch (err) {
+    state.consecutiveFailures += 1;
+    const msg = err instanceof Error ? err.message : String(err);
+    log(
+      `[acp] sessionUpdate failed (${state.consecutiveFailures}/${MAX_CONSECUTIVE_SEND_FAILURES}): ${msg}`
+    );
+    if (state.consecutiveFailures >= MAX_CONSECUTIVE_SEND_FAILURES) {
+      state.bailed = true;
+      log("[acp] translator bailing \u2014 too many consecutive sessionUpdate failures");
+    }
+  }
+}
+async function handleAssistant(msg, args, state) {
+  for (const content of msg.message.content) {
+    if (content.type === "text") {
+      await safeNotify(
+        args.conn,
+        args.sessionId,
+        { sessionUpdate: "agent_message_chunk", content: textChunk(content.text) },
+        state,
+        args.log
+      );
+    } else if (content.type === "tool_use") {
+      await safeNotify(
+        args.conn,
+        args.sessionId,
+        {
+          sessionUpdate: "tool_call",
+          toolCallId: content.id,
+          title: content.name,
+          kind: toolKind(content.name),
+          status: "in_progress"
+        },
+        state,
+        args.log
+      );
+    }
+  }
+}
+async function handleToolCall(msg, args, state) {
+  const content = [];
+  if (msg.result !== void 0 && msg.result !== null) {
+    const text = typeof msg.result === "string" ? msg.result : JSON.stringify(msg.result);
+    content.push({ type: "content", content: textChunk(text) });
+  }
+  await safeNotify(
+    args.conn,
+    args.sessionId,
+    {
+      sessionUpdate: "tool_call_update",
+      toolCallId: msg.call_id,
+      status: mapToolStatus(msg.status),
+      ...content.length > 0 ? { content } : {}
+    },
+    state,
+    args.log
+  );
+}
+async function handleThinking(msg, args, state) {
+  if (args.suppressThinking === true) return;
+  await safeNotify(
+    args.conn,
+    args.sessionId,
+    { sessionUpdate: "agent_thought_chunk", content: textChunk(msg.text) },
+    state,
+    args.log
+  );
+}
+async function translateStream(args) {
+  const state = { consecutiveFailures: 0, bailed: false };
+  for await (const msg of args.messages) {
+    if (args.signal.aborted) break;
+    if (state.bailed) break;
+    await dispatchMessage(msg, args, state);
+  }
+}
+async function dispatchMessage(msg, args, state) {
+  switch (msg.type) {
+    case "system":
+      return;
+    // no ACP equivalent
+    case "user":
+      return;
+    // echo, no ACP equivalent
+    case "assistant":
+      await handleAssistant(msg, args, state);
+      return;
+    case "thinking":
+      await handleThinking(msg, args, state);
+      return;
+    case "tool_call":
+      await handleToolCall(msg, args, state);
+      return;
+    case "status":
+      return;
+    // cloud-only
+    case "task":
+      return;
+    // milestones — skipped in v0.1
+    case "request":
+      return;
+    // permission requests routed via plugin
+    case "object_delta":
+      return;
+    // streamObject not used in plain prompt flow
+    default: {
+      const _exhaustive = msg;
+      throw new Error(`unhandled SDKMessage type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
+// src/permission-plugin.ts
+async function askWithTimeout(args, toolName) {
+  const toolCallId = `acp-perm-${crypto.randomUUID()}`;
+  const reqPromise = args.conn.requestPermission({
+    sessionId: args.sessionId,
+    toolCall: {
+      toolCallId,
+      title: toolName,
+      kind: toolKind(toolName),
+      status: "pending"
+    },
+    options: [
+      { optionId: "allow", name: "Allow", kind: "allow_once" },
+      { optionId: "deny", name: "Deny", kind: "reject_once" }
+    ]
+  });
+  let timeoutHandle;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      reject(new Error("permission_timeout"));
+    }, args.timeoutMs);
+  });
+  let response;
+  try {
+    response = await Promise.race([reqPromise, timeoutPromise]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg === "permission_timeout") {
+      return { block: true, message: `permission timed out after ${args.timeoutMs}ms` };
+    }
+    return { block: true, message: `permission request failed (client disconnected?): ${msg}` };
+  } finally {
+    if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+  }
+  const outcome = response.outcome;
+  if (outcome.outcome === "cancelled") {
+    return { block: true, message: "permission cancelled by client" };
+  }
+  if (outcome.outcome === "selected" && outcome.optionId === "deny") {
+    return { block: true, message: "denied by user" };
+  }
+  return void 0;
+}
+function installPermissionPlugin(agent, args) {
+  const plugin = sdk.definePlugin({
+    name: `acp-permission-${args.sessionId}`,
+    version: "1.0.0",
+    kind: "general",
+    register(ctx) {
+      ctx.on("pre_tool_call", async (rawCtx) => {
+        const event = rawCtx;
+        if (args.mode === "deny") {
+          return { block: true, message: "denied (permissionDefault=deny)" };
+        }
+        if (args.trustedTools.has(event.name)) {
+          return void 0;
+        }
+        return askWithTimeout(args, event.name);
+      });
+    }
+  });
+  const agentLike = agent;
+  const mgr = agentLike.pluginManager?.();
+  if (mgr === void 0) {
+    return;
+  }
+  if (typeof mgr.register === "function") {
+    mgr.register(plugin);
+  } else if (typeof mgr.initialize === "function") {
+    void mgr.initialize([plugin]);
+  }
+}
+
+// src/types.ts
+var PromptTooLargeError = class extends Error {
+  constructor(size, limit) {
+    super(`prompt exceeds ${limit} bytes (got ${size})`);
+    this.size = size;
+    this.limit = limit;
+  }
+  size;
+  limit;
+  name = "PromptTooLargeError";
+};
+
+// src/prompt-extract.ts
+function utf8Bytes(s) {
+  return Buffer.byteLength(s, "utf8");
+}
+function base64DecodedBytes(b64) {
+  return Math.floor(b64.length * 3 / 4);
+}
+function recordBytes(state, bytes) {
+  state.totalBytes += bytes;
+  if (state.totalBytes > state.maxBytes) {
+    throw new PromptTooLargeError(state.totalBytes, state.maxBytes);
+  }
+}
+function processBlock(block, state) {
+  switch (block.type) {
+    case "text":
+      recordBytes(state, utf8Bytes(block.text));
+      state.textParts.push(block.text);
+      return;
+    case "image": {
+      const data = block.data ?? "";
+      const bytes = base64DecodedBytes(data);
+      recordBytes(state, bytes);
+      state.attachments.push({ type: "image", mimeType: block.mimeType, data, bytes });
+      return;
+    }
+    case "audio": {
+      const data = block.data ?? "";
+      const bytes = base64DecodedBytes(data);
+      recordBytes(state, bytes);
+      state.attachments.push({ type: "audio", mimeType: block.mimeType, data, bytes });
+      return;
+    }
+    case "resource_link": {
+      const uri = block.uri ?? "";
+      const bytes = utf8Bytes(uri);
+      recordBytes(state, bytes);
+      state.attachments.push({ type: "resource_link", uri, bytes });
+      return;
+    }
+    case "resource": {
+      const bytes = utf8Bytes(JSON.stringify(block));
+      recordBytes(state, bytes);
+      state.attachments.push({ type: "embedded_resource", bytes });
+      return;
+    }
+    default: {
+      const _exhaustive = block;
+      throw new Error(`unknown ContentBlock type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function extractPrompt(blocks, maxBytes) {
+  const state = { textParts: [], attachments: [], totalBytes: 0, maxBytes };
+  for (const block of blocks) processBlock(block, state);
+  return { text: state.textParts.join("\n"), attachments: state.attachments };
+}
+
+// src/prompt-handler.ts
+function mapStopReason(runStatus, errorCode) {
+  if (errorCode === "aborted" || runStatus === "cancelled") return "cancelled";
+  if (errorCode === "safety_blocked") return "refusal";
+  if (errorCode === "context_length_exceeded" || errorCode === "max_tokens") return "max_tokens";
+  if (errorCode === "max_iterations") return "max_turn_requests";
+  if (runStatus === "finished") return "end_turn";
+  return "end_turn";
+}
+function isAbortError(err) {
+  if (!(err instanceof Error)) return false;
+  return err.name === "AbortError" || err.message.includes("aborted");
+}
+function extractOrError(params, deps) {
+  try {
+    const result = extractPrompt(params.prompt, deps.maxPromptBytes);
+    if (result.text.length === 0) {
+      return { ok: false, error: { code: ACP_ERR.INVALID_REQUEST, message: "empty prompt" } };
+    }
+    return { ok: true, text: result.text };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    deps.log(`[acp] prompt extract rejected: ${msg}`);
+    return { ok: false, error: { code: ACP_ERR.INVALID_REQUEST, message: msg } };
+  }
+}
+async function runPrompt(session, text, params, deps) {
+  const run = await session.agent.send(text, { signal: session.abortController.signal });
+  try {
+    await translateStream({
+      messages: run.stream(),
+      conn: deps.conn,
+      sessionId: params.sessionId,
+      signal: session.abortController.signal,
+      log: deps.log
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    deps.log(`[acp] translator threw mid-stream: ${msg}`);
+  }
+  const result = await run.wait();
+  const errorCode = result.status === "error" && result.error !== void 0 ? result.error.code ?? "" : "";
+  return mapStopReason(result.status, errorCode);
+}
+async function handlePrompt(params, deps) {
+  const session = deps.store.get(params.sessionId);
+  if (session === void 0) {
+    return {
+      error: { code: ACP_ERR.INVALID_SESSION, message: `unknown session: ${params.sessionId}` }
+    };
+  }
+  session.lastUsedAt = Date.now();
+  const extracted = extractOrError(params, deps);
+  if (!extracted.ok) return { error: extracted.error };
+  if (deps.permissionMode !== "auto") {
+    installPermissionPlugin(session.agent, {
+      conn: deps.conn,
+      sessionId: params.sessionId,
+      mode: deps.permissionMode,
+      trustedTools: deps.trustedTools,
+      timeoutMs: deps.permissionTimeoutMs
+    });
+  }
+  try {
+    const stopReason = await runPrompt(session, extracted.text, params, deps);
+    return { response: { stopReason } };
+  } catch (err) {
+    if (isAbortError(err)) return { response: { stopReason: "cancelled" } };
+    const msg = err instanceof Error ? err.message : String(err);
+    deps.log(`[acp] agent.send threw: ${msg}`);
+    return { error: { code: ACP_ERR.INTERNAL_ERROR, message: msg } };
+  }
+}
+
+// src/session-store.ts
+var SessionStore = class {
+  map = /* @__PURE__ */ new Map();
+  create(session) {
+    if (this.map.has(session.sessionId)) {
+      throw new Error(`duplicate sessionId: ${session.sessionId}`);
+    }
+    this.map.set(session.sessionId, session);
+  }
+  get(sessionId) {
+    return this.map.get(sessionId);
+  }
+  delete(sessionId) {
+    return this.map.delete(sessionId);
+  }
+  list() {
+    return [...this.map.values()];
+  }
+  size() {
+    return this.map.size;
+  }
+  has(sessionId) {
+    return this.map.has(sessionId);
+  }
+};
+
+// src/serve.ts
+var DEFAULT_MAX_PROMPT_BYTES = 2 * 1024 * 1024;
+var DEFAULT_PERMISSION_TIMEOUT_MS = 6e4;
+var DEFAULT_PERMISSION_MODE = "ask";
+async function serveAcp(options) {
+  const log = options.log ?? ((msg) => process.stderr.write(`${msg}
+`));
+  const factory = resolveAgentFactory(options.agent, { log });
+  const store = new SessionStore();
+  const maxPromptBytes = options.maxPromptBytes ?? DEFAULT_MAX_PROMPT_BYTES;
+  const permissionMode = options.permissionDefault ?? DEFAULT_PERMISSION_MODE;
+  const permissionTimeoutMs = options.permissionTimeoutMs ?? DEFAULT_PERMISSION_TIMEOUT_MS;
+  const trustedTools = new Set(options.trustedTools ?? []);
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const inputWeb = stream.Readable.toWeb(stdin);
+  const outputWeb = new WritableStream({
+    write(chunk) {
+      return new Promise((resolve, reject) => {
+        const ok = stdout.write(chunk, (err) => err ? reject(err) : void 0);
+        if (ok) resolve();
+        else stdout.once("drain", resolve);
+      });
+    }
+  });
+  const stream$1 = acp2__namespace.ndJsonStream(outputWeb, inputWeb);
+  const closedPromise = new Promise((resolve) => {
+    stdin.once("end", () => resolve());
+    stdin.once("close", () => resolve());
+  });
+  new acp2__namespace.AgentSideConnection((conn) => {
+    return {
+      initialize: async (params) => buildInitializeResponse(params, { capabilities: options.capabilities }),
+      authenticate: async (_params) => {
+        return {};
+      },
+      newSession: async (params) => {
+        const result = await handleNewSession(params, { factory, store, log });
+        if ("error" in result) {
+          throw new acp2__namespace.RequestError(result.error.code, result.error.message);
+        }
+        return result.response;
+      },
+      loadSession: async (params) => {
+        const result = await handleLoadSession(params, { store, log });
+        if ("error" in result) {
+          throw new acp2__namespace.RequestError(result.error.code, result.error.message);
+        }
+        return result.response;
+      },
+      unstable_forkSession: async (params) => {
+        const result = await handleForkSession(params, { store});
+        if ("error" in result) {
+          throw new acp2__namespace.RequestError(result.error.code, result.error.message);
+        }
+        return result.response;
+      },
+      listSessions: async (params) => handleListSessions(params, store),
+      cancel: async (params) => {
+        handleCancel(params, { store });
+      },
+      prompt: async (params) => {
+        const result = await handlePrompt(params, {
+          store,
+          conn,
+          maxPromptBytes,
+          permissionMode,
+          permissionTimeoutMs,
+          trustedTools,
+          log
+        });
+        if ("error" in result) {
+          throw new acp2__namespace.RequestError(result.error.code, result.error.message);
+        }
+        return result.response;
+      }
+    };
+  }, stream$1);
+  await closedPromise;
+  const sessions = store.list();
+  log(`[acp] stdin closed; disposing ${sessions.length} session(s)`);
+  await Promise.allSettled(
+    sessions.map(async (session) => {
+      try {
+        await session.agent.dispose();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`[acp] dispose of ${session.sessionId} threw: ${msg}`);
+      }
+    })
+  );
+}
+
+exports.PromptTooLargeError = PromptTooLargeError;
+exports.serveAcp = serveAcp;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map