@agentsky/acp 0.1.0 → 0.2.0

package/README.md

@@ -1,27 +1,33 @@
 # @agentsky/acp
 
 `agentsky-acp` runs an [AgentSky](https://agentsky.dev) cloud agent as a local
-**ACP agent** (Agent Client Protocol, JSON-RPC over stdio). Any ACP client can
-spawn it in place of a local harness; it proxies every turn to your always-on
-AgentSky session over the public `/api/v1` API. Built for
-[block/buzz](https://github.com/block/buzz)'s `buzz-acp` harness.
+**ACP agent** (Agent Client Protocol v1, JSON-RPC over stdio). Any ACP client can
+spawn it in place of a local harness; it proxies every turn to your AgentSky
+session over the public `/api/v1` API. Built for
+[Kylon Custom (ACP)](https://docs.kylon.io/agents/acp-agent-contract),
+[block/buzz](https://github.com/block/buzz)'s `buzz-acp` harness, Zed, and any
+other ACP v1 client.
 
-Why: buzz's local harnesses die with the laptop and forget on every session
+Why: local ACP harnesses die with the laptop and forget on every session
 rotation. An AgentSky agent is a persistent cloud pod — the bridge maps every
-ACP session (buzz makes one per channel, and rotates them freely) onto the same
-durable conversation, so your agent stays online and never loses memory.
+ACP session onto a durable cloud conversation, so your agent stays online and
+never loses memory.
 
-```
-relay ◄─WS─ buzz-acp (ACP client) ─ACP/stdio→ agentsky-acp ─HTTPS→ agentsky.dev/api/v1
-                                               └─ posts replies via `buzz messages send`
-```
-
-## Setup
+## Kylon setup
 
 ```sh
 npm install -g @agentsky/acp
 # get a token: https://agentsky.dev/settings?tab=tokens  (or `sky auth login`)
 
+kylon agent configure <agent-id> --env SKY_API_TOKEN=ast_… -- agentsky-acp @handle
+```
+
+The agent defaults to `sky` (the Sky orchestrator). Pass any handle or
+`sess-<id>` to target a specific agent.
+
+## Buzz setup
+
+```sh
 export SKY_API_TOKEN=ast_…
 export BUZZ_ACP_AGENT_COMMAND=agentsky-acp
 export BUZZ_ACP_AGENT_ARGS=<your-agent-slug>
@@ -44,28 +50,54 @@ Or as a buzz desktop custom harness (`<app-data>/custom_harnesses/agentsky.json`
 | env | meaning |
 |---|---|
 | `SKY_API_TOKEN` | AgentSky API token (`ast_…`), required |
-| `SKY_API_URL` | API base, default `https://agentsky.dev` |
+| `SKY_API_URL` | API base, default `https://api.agentsky.dev/v1` |
 | `SKY_AGENT` | agent spec slug or `sess-…` session id (alternative to argv) |
 | `SKY_UNIVERSE` | universe slug (sent as `X-Universe`) |
 | `SKY_ACP_NO_REPLY_POST=1` | don't post replies to buzz channels via the buzz CLI |
 | `SKY_ACP_BUZZ_BIN` | buzz CLI binary, default `buzz` |
 | `SKY_ACP_TURN_TIMEOUT_MS` | per-turn safety timeout, default 3600000 |
+| `SKY_ACP_REQUEST_TIMEOUT_MS` | how long to wait for a permission answer before applying the D5 fallback, default 120000 |
+| `SKY_ACP_MCP_BRIDGE=0` | don't forward stdio MCP servers from `session/new` (they are forwarded through the relay bridge by default) |
+
+## CLI flags
+
+| flag | meaning |
+|---|---|
+| `--session per-acp` | one AgentSky session per ACP session (default outside buzz) |
+| `--session agent` | all ACP sessions share one AgentSky session (default under buzz) |
+| `--context-block none` | send all prompt text blocks as `user.message` instead of treating the first block as `system.message` |
+| `--budget-cents <n>` | root budget cap in US cents |
 
 ## Behavior notes
 
-- **Session mapping**: on start the adapter resolves the agent's default
-  session (creating one if the spec has none). All ACP sessions map to it —
-  channel context and thread history arrive in each prompt, so replies stay
-  channel-correct while the agent keeps one continuous memory.
-- **Reply posting**: buzz-acp does not forward the ACP response text to the
-  channel; agents are expected to post via the buzz CLI. The cloud pod has no
-  buzz CLI or Nostr key, so the adapter posts the completed reply itself with
-  `buzz messages send --channel <uuid>` (channel parsed from the prompt's
-  `[Context]` section; env `BUZZ_RELAY_URL`/`BUZZ_PRIVATE_KEY` are inherited
-  from buzz-acp). A bridge note in each forwarded prompt tells the agent to
-  reply in plain text instead of attempting buzz commands.
-- **Reliability**: `Idempotency-Key` on every message post (safe restarts),
-  standing SSE with liveness watchdog + reconnect, events-ledger catch-up
-  deduped by event id, `session/cancel` → interrupt.
-- `mcpServers` from `session/new` are ignored (local stdio sidecars can't
-  reach the cloud pod).
+- **Protocol v1**: accepts `initialize` with `protocolVersion: 1` only; returns
+  `-32000` for any other version or a missing `SKY_API_TOKEN`.
+- **Session modes**:
+  - `per-acp` (default outside buzz): one AgentSky session per ACP session,
+    created lazily on the first prompt so the handshake stays inside 60 s.
+  - `agent` (default under buzz, detected via `BUZZ_RELAY_URL`): all ACP sessions
+    share one durable AgentSky session — channel context arrives in every prompt
+    and the agent keeps one continuous memory.
+- **Context block** (item 3): the first text block of the first prompt is sent as
+  a `system.message` event right after the turn's `user.message`, in the same post (operating context per RFC-0149 §5 D6); subsequent
+  blocks are `user.message`. `--context-block none` disables this.
+- **MCP server forwarding** (item 2): HTTP entries in `session/new`.`mcpServers`
+  are forwarded as a `mcp_servers` overlay on the created AgentSky session. Stdio entries
+  (Kylon's `kylon` server among them) are spawned locally, registered as a
+  bridge server via `POST /api/v1/bridges` and `POST /api/v1/bridges/{id}/servers`,
+  and the relay long-poll (`GET /api/v1/desktop/requests?wait=25`) proxies
+  MCP JSON-RPC to the local process. `SKY_ACP_MCP_BRIDGE=0` turns the stdio
+  bridge off. Both degrade to a log note when the platform answers 404.
+- **Task request forwarding** (item 4): open task requests are forwarded to the
+  ACP client as `session/request_permission`; if the client doesn't answer within
+  `SKY_ACP_REQUEST_TIMEOUT_MS` or declines, the RFC-0149 D5 fallback is applied
+  (`approval`/`spend` → decline; `question` → best-judgement instruction).
+- **Cancel**: `session/cancel` interrupts the running turn and settles with
+  `stopReason: "cancelled"` within 5 s.
+- **loadSession**: advertised `true` in `agent` mode (session is always resumable);
+  `false` in `per-acp` mode.
+- **Reply posting** (buzz only): the adapter posts the completed reply to the
+  buzz channel with `buzz messages send --channel <uuid>` (channel UUID parsed
+  from the prompt's `[Context]` section).
+- **Reliability**: `Idempotency-Key` on every message post, standing SSE with
+  liveness watchdog + reconnect, events-ledger catch-up deduped by event id.

package/dist/index.js

@@ -16,9 +16,10 @@ var SkyApi = class {
   }
   config;
   headers() {
-    const headers = {
-      authorization: `Bearer ${this.config.token}`
-    };
+    const headers = {};
+    if (this.config.token) {
+      headers["authorization"] = `Bearer ${this.config.token}`;
+    }
     if (this.config.universe) headers["x-universe"] = this.config.universe;
     return headers;
   }
@@ -45,7 +46,8 @@ var SkyApi = class {
       }
       throw new ApiError(res.status, code, message);
     }
-    return await res.json();
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
   }
   /** Resolve the agent ref to the one session this adapter drives: an
    *  explicit `sess-…` id, else the spec's default session, else a freshly
@@ -53,38 +55,86 @@ var SkyApi = class {
   async resolveSession() {
     const ref = this.config.agent;
     if (ref.startsWith("sess-")) return ref;
-    const { agent } = await this.request("GET", `/api/v1/agents/${encodeURIComponent(ref)}`);
+    const { agent } = await this.request("GET", `/agents/${encodeURIComponent(ref)}`);
     if (agent.defaultSessionId) return agent.defaultSessionId;
     const { session } = await this.request(
       "POST",
-      "/api/v1/sessions",
+      "/sessions",
       { agent: ref, title: "buzz (acp bridge)" }
     );
     return session.id;
   }
+  /** Create a new session for per-acp mode with optional budget and mcp overlay. */
+  async createSession(options) {
+    const body = {
+      agent: this.config.agent,
+      title: options.title ?? "acp session",
+      // The first prompt boots the sandbox, after any bridged MCP servers
+      // have been added to the overlay (setMcpServers).
+      provision: "deferred"
+    };
+    if (options.budgetCents !== void 0) {
+      body["budget"] = {
+        type: "limit",
+        max_list_cost: { amount: String(options.budgetCents), currency: "USD" }
+      };
+    }
+    if (options.mcpServers && options.mcpServers.length > 0) {
+      body["mcp_servers"] = options.mcpServers;
+    }
+    const { session } = await this.request("POST", "/sessions", body);
+    return {
+      id: session.id,
+      taskId: session.taskId ?? session.task_id ?? null,
+      canReopen: session.canReopen ?? false
+    };
+  }
+  /** Replace the session's MCP server overlay (PATCH /sessions/{id}). */
+  async setMcpServers(sessionId, servers) {
+    await this.request("PATCH", `/sessions/${encodeURIComponent(sessionId)}`, { mcp_servers: servers });
+  }
   async sendMessage(sessionId, text, idempotencyKey) {
     await this.request(
       "POST",
-      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
-      { parts: [{ type: "text", index: 0, text }] },
+      `/sessions/${encodeURIComponent(sessionId)}/events`,
+      { events: [{ type: "user.message", content: [{ type: "text", text }] }] },
+      { "idempotency-key": idempotencyKey }
+    );
+  }
+  /** Send a turn whose operating context (D6) rides as a system.message.
+   *  The platform accepts a system.message only right after a user.message,
+   *  so both go in one post, user first. */
+  async sendMessageWithContext(sessionId, text, context, idempotencyKey) {
+    await this.request(
+      "POST",
+      `/sessions/${encodeURIComponent(sessionId)}/events`,
+      {
+        events: [
+          { type: "user.message", content: [{ type: "text", text }] },
+          { type: "system.message", content: [{ type: "text", text: context }] }
+        ]
+      },
       { "idempotency-key": idempotencyKey }
     );
   }
   async interrupt(sessionId) {
-    await this.request("POST", `/api/v1/sessions/${encodeURIComponent(sessionId)}/interrupt`);
+    await this.request("POST", `/sessions/${encodeURIComponent(sessionId)}/interrupt`);
   }
+  /** Catch-up over the ChatMessage-backed history: user.message /
+   *  agent.message / session.status_idle events only — per-part events
+   *  (agent.reasoning, agent.tool_use, …) are live-stream-only. */
   async listEvents(sessionId, cursor, limit = 500) {
     const params = new URLSearchParams({ limit: String(limit) });
     if (cursor !== null) params.set("cursor", cursor);
     return this.request(
       "GET",
-      `/api/v1/sessions/${encodeURIComponent(sessionId)}/events?${params}`
+      `/sessions/${encodeURIComponent(sessionId)}/events?${params}`
     );
   }
   /** Open the standing SSE stream. Returns the body; caller parses/aborts. */
   async openStream(sessionId, signal) {
     const res = await fetch(
-      `${this.config.apiBase}/api/v1/sessions/${encodeURIComponent(sessionId)}/stream`,
+      `${this.config.apiBase}/sessions/${encodeURIComponent(sessionId)}/stream`,
       { headers: { ...this.headers(), accept: "text/event-stream" }, signal }
     );
     if (!res.ok) {
@@ -93,32 +143,156 @@ var SkyApi = class {
     if (!res.body) throw new ApiError(502, "no_body", "stream returned no body");
     return res.body;
   }
+  /** Fetch open requests for a task from GET /tasks/{id}.
+   *  The task id is the root session id; task.requests[] contains the open
+   *  requests addressed to the caller. Returns [] on 404 (task not yet created). */
+  async listOpenRequests(taskId) {
+    try {
+      const data = await this.request("GET", `/tasks/${encodeURIComponent(taskId)}`);
+      return data.task.requests ?? [];
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) return [];
+      throw error;
+    }
+  }
+  async answerRequest(taskId, requestId, answer) {
+    await this.request(
+      "POST",
+      `/tasks/${encodeURIComponent(taskId)}/requests/${encodeURIComponent(requestId)}/answer`,
+      answer
+    );
+  }
+  /** POST /api/v1/bridges — returns 404 when lane B not yet landed.
+   *  Real shape: {bridge: {id, name, …}, connect_token: "brc_…"} — connect_token
+   *  is at the TOP level, same convention as Mac machines (bridge PR #3314). */
+  async createBridge(name) {
+    try {
+      const data = await this.request("POST", "/bridges", { name });
+      const token = data.connect_token ?? data.bridge.connect_token ?? "";
+      return { id: data.bridge.id, connectToken: token };
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) return null;
+      throw error;
+    }
+  }
+  /** POST /api/v1/bridges/{id}/servers — returns null on 404.
+   *  Requires the bridge connect token as bearer (not the workspace API key).
+   *  session_id must be a public sess_… id.
+   *  Real shape: {server: {id, bridge_id, name, mcp_url, created_at}} */
+  async registerBridgeServer(bridgeId, name, connectToken, sessionId) {
+    try {
+      const body = { name };
+      if (sessionId) body["session_id"] = sessionId;
+      const data = await this.request("POST", `/bridges/${encodeURIComponent(bridgeId)}/servers`, body, {
+        authorization: `Bearer ${connectToken}`
+      });
+      return { id: data.server.id, mcpUrl: data.server.mcp_url };
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) return null;
+      throw error;
+    }
+  }
+  /** GET /api/v1/desktop/requests?wait=25 — long-poll for relay requests. */
+  async longPollDesktopRequests(connectToken, signal) {
+    try {
+      const data = await this.request("GET", "/desktop/requests?wait=25", void 0, {
+        authorization: `Bearer ${connectToken}`,
+        "x-skip-universe": "1"
+      });
+      return (data.requests ?? []).map((r) => ({
+        id: r.id,
+        serverId: relayServerKey(r.mount_id),
+        method: r.method,
+        body: r.body
+      }));
+    } catch (error) {
+      if (signal.aborted) return [];
+      if (error instanceof ApiError && (error.status === 404 || error.status === 408)) return [];
+      throw error;
+    }
+  }
+  /** Answer one relay request with the HTTP response the pod receives. */
+  async answerDesktopRequest(requestId, response, connectToken) {
+    await this.request(
+      "POST",
+      `/desktop/requests/${encodeURIComponent(requestId)}/response`,
+      { status: response.status, headers: response.headers ?? {}, body: response.body ?? null },
+      { authorization: `Bearer ${connectToken}` }
+    );
+  }
 };
+function relayServerKey(id) {
+  return id.replace(/^(dmt|brs)_/, "");
+}
 
 // src/agent.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 
 // src/buzz.ts
 import { execFile } from "child_process";
 
 // src/config.ts
+function isBuzz() {
+  return Boolean(process.env.BUZZ_RELAY_URL || process.env.BUZZ_ACP_BIN);
+}
+function parseSessionMode(raw, defaultMode) {
+  if (raw === "per-acp" || raw === "agent") return raw;
+  if (raw !== void 0) {
+    process.stderr.write(
+      `[agentsky-acp] unknown --session value "${raw}"; using "${defaultMode}"
+`
+    );
+  }
+  return defaultMode;
+}
 function loadConfig(argv) {
-  const agent = argv[0] ?? process.env.SKY_AGENT;
-  const token = process.env.SKY_API_TOKEN;
-  if (!agent || !token) {
+  const args = [...argv];
+  let sessionModeArg;
+  let contextBlockArg = true;
+  let budgetCents;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--session") {
+      sessionModeArg = args[++i];
+    } else if (a.startsWith("--session=")) {
+      sessionModeArg = a.slice("--session=".length);
+    } else if (a === "--context-block") {
+      const v = args[++i];
+      if (v === "none") contextBlockArg = false;
+    } else if (a.startsWith("--context-block=")) {
+      contextBlockArg = a.slice("--context-block=".length) !== "none";
+    } else if (a === "--budget-cents") {
+      budgetCents = Number(args[++i]);
+    } else if (a.startsWith("--budget-cents=")) {
+      budgetCents = Number(a.slice("--budget-cents=".length));
+    } else {
+      positional.push(a);
+    }
+  }
+  const agent = positional[0] ?? process.env.SKY_AGENT ?? "sky";
+  const token = process.env.SKY_API_TOKEN || void 0;
+  if (!agent) {
     process.stderr.write(
-      "usage: SKY_API_TOKEN=ast_\u2026 agentsky-acp <agent-slug>\n  env: SKY_API_URL (default https://agentsky.dev), SKY_AGENT (alternative to argv),\n       SKY_UNIVERSE, SKY_ACP_NO_REPLY_POST=1, SKY_ACP_BUZZ_BIN (default buzz),\n       SKY_ACP_TURN_TIMEOUT_MS (default 3600000)\n"
+      "usage: SKY_API_TOKEN=ast_\u2026 agentsky-acp [--session per-acp|agent] [--context-block none] [--budget-cents N] <agent-id>\n  env: SKY_API_URL (default https://api.agentsky.dev/v1), SKY_AGENT (alternative to argv),\n       SKY_UNIVERSE, SKY_ACP_NO_REPLY_POST=1, SKY_ACP_BUZZ_BIN (default buzz),\n       SKY_ACP_TURN_TIMEOUT_MS (default 3600000), SKY_ACP_REQUEST_TIMEOUT_MS (default 120000),\n       SKY_ACP_MCP_BRIDGE=0 (disable the stdio MCP bridge; on by default)\n"
     );
     process.exit(2);
   }
+  const defaultMode = isBuzz() ? "agent" : "per-acp";
+  const sessionMode = parseSessionMode(sessionModeArg, defaultMode);
   return {
-    apiBase: (process.env.SKY_API_URL ?? "https://agentsky.dev").replace(/\/$/, ""),
+    apiBase: (process.env.SKY_API_URL ?? "https://api.agentsky.dev/v1").replace(/\/$/, ""),
     token,
     agent,
     universe: process.env.SKY_UNIVERSE,
     replyPost: process.env.SKY_ACP_NO_REPLY_POST !== "1",
     buzzBin: process.env.SKY_ACP_BUZZ_BIN ?? "buzz",
-    turnTimeoutMs: Number(process.env.SKY_ACP_TURN_TIMEOUT_MS ?? 36e5)
+    turnTimeoutMs: Number(process.env.SKY_ACP_TURN_TIMEOUT_MS ?? 36e5),
+    sessionMode,
+    contextBlock: contextBlockArg,
+    budgetCents,
+    requestTimeoutMs: Number(process.env.SKY_ACP_REQUEST_TIMEOUT_MS ?? 12e4),
+    mcpBridge: process.env.SKY_ACP_MCP_BRIDGE !== "0"
   };
 }
 function log(message) {
@@ -279,20 +453,38 @@ var RpcEndpoint = class {
   input;
   output;
   handlers = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  nextId = 1;
   on(method, handler) {
     this.handlers.set(method, handler);
   }
   notify(method, params) {
     this.write({ jsonrpc: "2.0", method, params });
   }
+  /** Send a JSON-RPC request to the client and wait for a response. */
+  async request(method, params, timeoutMs) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+      this.write({ jsonrpc: "2.0", id, method, params });
+      if (timeoutMs !== void 0) {
+        setTimeout(() => {
+          if (this.pendingRequests.has(id)) {
+            this.pendingRequests.delete(id);
+            reject(new Error(`request ${method} timed out after ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+      }
+    });
+  }
   /** Consume stdin until EOF, dispatching requests and notifications. */
   async run() {
     const lines = createInterface({ input: this.input, crlfDelay: Infinity });
     for await (const line of lines) {
       if (!line.trim()) continue;
-      let request;
+      let frame;
       try {
-        request = JSON.parse(line);
+        frame = JSON.parse(line);
       } catch {
         this.write({
           jsonrpc: "2.0",
@@ -301,6 +493,20 @@ var RpcEndpoint = class {
         });
         continue;
       }
+      if (!("method" in frame) && "id" in frame && frame.id !== null && frame.id !== void 0) {
+        const response = frame;
+        const pending = this.pendingRequests.get(response.id);
+        if (pending) {
+          this.pendingRequests.delete(response.id);
+          if (response.error) {
+            pending.reject(new RpcError(response.error.code, response.error.message, response.error.data));
+          } else {
+            pending.resolve(response.result);
+          }
+        }
+        continue;
+      }
+      const request = frame;
       void this.dispatch(request);
     }
   }
@@ -336,59 +542,333 @@ var RpcEndpoint = class {
   }
 };
 
+// src/bridge.ts
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+var MAX_CLAIMS = 4;
+var McpBridge = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  servers = /* @__PURE__ */ new Map();
+  // name → live server
+  aborts = /* @__PURE__ */ new Map();
+  // serverId → relay abort
+  bridgeId = null;
+  connectToken = null;
+  /** Spawn and register all stdio entries. Returns mcp_urls keyed by name.
+   *  HTTP entries are passed through unchanged. Failures are logged, not thrown. */
+  async setup(entries, sessionId) {
+    const result = /* @__PURE__ */ new Map();
+    if (!this.bridgeId) {
+      const bridge = await this.api.createBridge(`acp-${randomUUID().slice(0, 8)}`);
+      if (!bridge) {
+        log("mcp bridge endpoints not available (lane B not yet landed); stdio servers ignored");
+        return result;
+      }
+      this.bridgeId = bridge.id;
+      this.connectToken = bridge.connectToken;
+    }
+    for (const entry of entries) {
+      try {
+        const mcpUrl = await this.spawnAndRegister(entry, sessionId);
+        if (mcpUrl) result.set(entry.name, mcpUrl);
+      } catch (error) {
+        log(
+          `failed to start mcp server "${entry.name}": ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    return result;
+  }
+  async spawnAndRegister(entry, sessionId) {
+    const existing = this.servers.get(entry.name);
+    if (existing) {
+      log(`reusing existing bridge server "${entry.name}"`);
+      return null;
+    }
+    const child = spawn(entry.command, entry.args ?? [], {
+      env: { ...process.env, ...entry.env },
+      stdio: ["pipe", "pipe", "inherit"]
+    });
+    await new Promise((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+      setTimeout(() => reject(new Error("spawn timed out")), 5e3);
+    });
+    const server = await this.api.registerBridgeServer(
+      this.bridgeId,
+      entry.name,
+      this.connectToken,
+      sessionId
+    );
+    if (!server) {
+      child.kill();
+      return null;
+    }
+    const live = {
+      process: child,
+      serverId: server.id,
+      connectToken: this.connectToken
+    };
+    this.servers.set(entry.name, live);
+    log(`registered bridge server "${entry.name}" \u2192 ${server.mcpUrl}`);
+    const ac = new AbortController();
+    this.aborts.set(server.id, ac);
+    void this.relayLoop(live, ac.signal).catch(
+      (error) => log(`relay loop "${entry.name}" error: ${error instanceof Error ? error.message : String(error)}`)
+    );
+    return server.mcpUrl;
+  }
+  /** Long-poll loop: claim relay requests, proxy to stdio, answer back. */
+  async relayLoop(live, signal) {
+    const inflight = /* @__PURE__ */ new Set();
+    while (!signal.aborted) {
+      let batch;
+      try {
+        batch = await this.api.longPollDesktopRequests(live.connectToken, signal);
+      } catch (error) {
+        if (signal.aborted) break;
+        log(`relay poll error: ${error instanceof Error ? error.message : String(error)}`);
+        await new Promise((resolve) => setTimeout(resolve, 2e3));
+        continue;
+      }
+      for (const item of batch) {
+        if (item.serverId !== relayServerKey(live.serverId)) continue;
+        if (inflight.size >= MAX_CLAIMS) continue;
+        if (inflight.has(item.id)) continue;
+        inflight.add(item.id);
+        void this.handleOne(item, live, signal).finally(
+          () => inflight.delete(item.id)
+        );
+      }
+    }
+  }
+  async handleOne(item, live, signal) {
+    const json = { "content-type": "application/json" };
+    if (item.method !== "POST") {
+      await this.answer(item.id, { status: 405, headers: { allow: "POST" } }, live);
+      return;
+    }
+    let request = null;
+    try {
+      request = JSON.parse(item.body ?? "");
+    } catch {
+      await this.answer(item.id, { status: 400, headers: json, body: JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }) }, live);
+      return;
+    }
+    if (request && request.id === void 0) {
+      live.process.stdin?.write(`${JSON.stringify(request)}
+`);
+      await this.answer(item.id, { status: 202 }, live);
+      return;
+    }
+    try {
+      const response = await this.proxyToStdio(live.process, request, signal);
+      if (!signal.aborted) await this.answer(item.id, { status: 200, headers: json, body: JSON.stringify(response) }, live);
+    } catch (error) {
+      if (signal.aborted) return;
+      const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: request?.id ?? null,
+        error: { code: -32603, message: error instanceof Error ? error.message : String(error) }
+      });
+      await this.answer(item.id, { status: 200, headers: json, body }, live);
+    }
+  }
+  async answer(requestId, response, live) {
+    await this.api.answerDesktopRequest(requestId, response, live.connectToken).catch((e) => log(`answer relay error: ${e instanceof Error ? e.message : String(e)}`));
+  }
+  /** Send JSON-RPC to the stdio process and wait for the matching response. */
+  proxyToStdio(child, request, signal) {
+    return new Promise((resolve, reject) => {
+      const reqId = request?.id;
+      let buffered = "";
+      const onData = (chunk) => {
+        buffered += chunk.toString();
+        let nl;
+        while ((nl = buffered.indexOf("\n")) !== -1) {
+          const line2 = buffered.slice(0, nl).trim();
+          buffered = buffered.slice(nl + 1);
+          if (!line2) continue;
+          try {
+            const frame = JSON.parse(line2);
+            if (frame.id === reqId) {
+              cleanup();
+              resolve(frame);
+            }
+          } catch {
+          }
+        }
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+      const onAbort = () => {
+        cleanup();
+        reject(new Error("aborted"));
+      };
+      const cleanup = () => {
+        child.stdout?.removeListener("data", onData);
+        child.removeListener("error", onError);
+        signal.removeEventListener("abort", onAbort);
+      };
+      child.stdout?.on("data", onData);
+      child.on("error", onError);
+      signal.addEventListener("abort", onAbort, { once: true });
+      const line = JSON.stringify(request) + "\n";
+      child.stdin?.write(line, (err) => {
+        if (err) {
+          cleanup();
+          reject(err);
+        }
+      });
+    });
+  }
+  stop() {
+    for (const ac of this.aborts.values()) ac.abort();
+    for (const live of this.servers.values()) {
+      live.process.kill();
+    }
+    this.servers.clear();
+    this.aborts.clear();
+  }
+};
+
 // src/agent.ts
-var VERSION = "0.1.0";
-var PROTOCOL_VERSION = 2;
+var VERSION = "0.2.0";
+var PROTOCOL_VERSION = 1;
 var BRIDGE_NOTE = "[Bridge note] You are connected to this Buzz workspace through the AgentSky bridge. The `buzz` CLI and Nostr relay are NOT available in your environment \u2014 do not attempt to run `buzz` commands. Write your reply as plain response text; the bridge posts it to the correct channel for you.";
 var AcpAgent = class {
   constructor(config, api, rpc) {
     this.config = config;
     this.api = api;
     this.rpc = rpc;
+    this.bridge = new McpBridge(api);
   }
   config;
   api;
   rpc;
-  sessionId = null;
-  bus = null;
-  initPromise = null;
+  // per-acp mode: ACP session id → AgentSky session state (populated lazily)
+  perAcpSessions = /* @__PURE__ */ new Map();
+  // per-acp mode: ACP session id → pending params from session/new
+  pendingNewParams = /* @__PURE__ */ new Map();
+  // agent mode: the single shared session
+  sharedState = null;
+  sharedInitPromise = null;
   turnChain = Promise.resolve();
   inflight = false;
+  interruptRequested = false;
   acpSessionCounter = 0;
+  bridge;
   register() {
-    this.rpc.on("initialize", () => ({
+    this.rpc.on("initialize", (params) => this.initialize(params));
+    this.rpc.on("authenticate", () => ({}));
+    this.rpc.on("session/new", (params) => this.newSession(params));
+    this.rpc.on("session/prompt", (params) => this.prompt(params));
+    this.rpc.on("session/cancel", () => this.cancel());
+  }
+  initialize(params) {
+    const requested = params?.protocolVersion;
+    if (requested !== void 0 && requested !== PROTOCOL_VERSION) {
+      throw new RpcError(
+        -32602,
+        `unsupported protocol version ${requested}; this adapter supports version ${PROTOCOL_VERSION}`
+      );
+    }
+    if (!this.config.token) {
+      throw new RpcError(-32e3, "SKY_API_TOKEN is not set; set it with --env SKY_API_TOKEN=ast_\u2026");
+    }
+    return {
       protocolVersion: PROTOCOL_VERSION,
       agentCapabilities: {
-        loadSession: false,
+        loadSession: this.config.sessionMode === "agent",
         promptCapabilities: { image: false, audio: false, embeddedContext: false }
       },
       authMethods: [],
       agentInfo: { name: "agentsky-acp", version: VERSION }
-    }));
-    this.rpc.on("authenticate", () => ({}));
-    this.rpc.on("session/new", () => this.newSession());
-    this.rpc.on("session/prompt", (params) => this.prompt(params));
-    this.rpc.on("session/cancel", () => this.cancel());
+    };
   }
-  /** Resolve the AgentSky session and start the event pipeline, once. */
-  ensureReady() {
-    this.initPromise ??= (async () => {
-      const sessionId = await this.api.resolveSession();
-      this.sessionId = sessionId;
-      const bus = new EventBus(this.api, sessionId);
-      await bus.primeCursor().catch((error) => {
-        log(`cursor prime failed (continuing live-only): ${String(error)}`);
-      });
-      void bus.run();
-      this.bus = bus;
-      log(`attached to session ${sessionId}`);
-    })();
-    return this.initPromise;
+  async newSession(params) {
+    const acpSessionId = `sky-acp-${++this.acpSessionCounter}-${randomUUID2().slice(0, 8)}`;
+    if (this.config.sessionMode === "agent") {
+      void this.ensureShared();
+    } else {
+      this.pendingNewParams.set(acpSessionId, params);
+    }
+    return { sessionId: acpSessionId };
+  }
+  // ── Session resolution ────────────────────────────────────────────────────
+  ensureShared() {
+    this.sharedInitPromise ??= this.createSharedState();
+    return this.sharedInitPromise;
+  }
+  async createSharedState() {
+    const sessionId = await this.api.resolveSession();
+    const bus = new EventBus(this.api, sessionId);
+    await bus.primeCursor().catch((error) => {
+      log(`cursor prime failed (continuing live-only): ${String(error)}`);
+    });
+    void bus.run();
+    this.sharedState = { skySessionId: sessionId, taskId: null, bus, canReopen: true };
+    log(`attached to shared session ${sessionId}`);
+    return this.sharedState;
+  }
+  async ensurePerAcp(acpSessionId) {
+    const existing = this.perAcpSessions.get(acpSessionId);
+    if (existing) return existing;
+    const params = this.pendingNewParams.get(acpSessionId) ?? {};
+    const httpOverlay = [];
+    const stdioEntries = [];
+    for (const srv of params.mcpServers ?? []) {
+      const isHttp = srv.type === "http" || srv.type === "sse" || srv.url && !srv.command;
+      if (isHttp && srv.url) {
+        httpOverlay.push({ name: srv.name, url: srv.url });
+      } else if (srv.command) {
+        stdioEntries.push({ name: srv.name, command: srv.command, args: srv.args, env: srv.env });
+      }
+    }
+    const { id: skySessionId, taskId, canReopen } = await this.api.createSession({
+      title: `acp-${acpSessionId}`,
+      budgetCents: this.config.budgetCents,
+      mcpServers: httpOverlay.length > 0 ? httpOverlay : void 0
+    });
+    if (this.config.mcpBridge && stdioEntries.length > 0) {
+      const urlMap = await this.bridge.setup(stdioEntries, skySessionId);
+      if (urlMap.size > 0) {
+        const bridged = [...urlMap].map(([name, url]) => ({ name, url }));
+        await this.api.setMcpServers(skySessionId, [...httpOverlay, ...bridged]);
+      }
+      if (urlMap.size < stdioEntries.length) {
+        const missing = stdioEntries.filter((e) => !urlMap.has(e.name)).map((e) => e.name).join(", ");
+        log(`stdio mcp server(s) not registered: ${missing}`);
+      }
+    } else if (!this.config.mcpBridge && stdioEntries.length > 0) {
+      log(
+        `stdio mcp servers ignored (SKY_ACP_MCP_BRIDGE=0): ${stdioEntries.map((e) => e.name).join(", ")}`
+      );
+    }
+    const bus = new EventBus(this.api, skySessionId);
+    await bus.primeCursor().catch((error) => {
+      log(`cursor prime failed (continuing live-only): ${String(error)}`);
+    });
+    void bus.run();
+    const state = { skySessionId, taskId, bus, canReopen };
+    this.perAcpSessions.set(acpSessionId, state);
+    this.pendingNewParams.delete(acpSessionId);
+    log(`created per-acp session ${skySessionId} for acp session ${acpSessionId}`);
+    return state;
   }
-  async newSession() {
-    await this.ensureReady();
-    return { sessionId: `sky-acp-${++this.acpSessionCounter}-${randomUUID().slice(0, 8)}` };
+  async resolveState(acpSessionId) {
+    if (this.config.sessionMode === "agent") {
+      return this.ensureShared();
+    }
+    if (!acpSessionId) throw new RpcError(-32602, "sessionId required in per-acp mode");
+    return this.ensurePerAcp(acpSessionId);
   }
+  // ── Turns ─────────────────────────────────────────────────────────────────
   prompt(params) {
     const turn = this.turnChain.then(
       () => this.runTurn(params),
@@ -398,16 +878,29 @@ var AcpAgent = class {
     return turn;
   }
   async runTurn(params) {
-    await this.ensureReady();
-    const sessionId = this.sessionId;
-    const bus = this.bus;
-    if (!sessionId || !bus) throw new RpcError(-32603, "adapter not initialized");
-    const text = (params.prompt ?? []).filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n\n");
-    if (!text.trim()) return { stopReason: "end_turn" };
-    const channelId = extractChannelId(text);
+    const state = await this.resolveState(params.sessionId);
+    const { skySessionId: sessionId, bus, taskId } = state;
+    const blocks = params.prompt ?? [];
+    const textBlocks = blocks.filter(
+      (block) => block.type === "text" && typeof block.text === "string"
+    );
+    if (textBlocks.length === 0) return { stopReason: "end_turn" };
     const acpSessionId = params.sessionId;
+    const channelId = extractChannelId(
+      textBlocks.map((b) => b.text).join("\n")
+    );
+    let systemText = null;
+    let userText;
+    if (this.config.contextBlock && textBlocks.length > 1) {
+      systemText = textBlocks[0].text;
+      userText = textBlocks.slice(1).map((b) => b.text).join("\n\n");
+    } else {
+      userText = textBlocks.map((b) => b.text).join("\n\n");
+    }
+    if (!userText.trim() && !systemText) return { stopReason: "end_turn" };
     let replyText = "";
     let sawTurnActivity = false;
+    this.interruptRequested = false;
     let settle;
     let fail;
     const done = new Promise((resolve, reject) => {
@@ -416,10 +909,6 @@ var AcpAgent = class {
     });
     const unsubscribe = bus.onEvent((event) => {
       switch (event.type) {
-        case "user.message":
-        case "turn.accepted":
-          sawTurnActivity = true;
-          break;
         case "agent.message": {
           sawTurnActivity = true;
           const chunk = typeof event.text === "string" ? event.text : "";
@@ -448,7 +937,7 @@ var AcpAgent = class {
           const part = event.part;
           this.update(acpSessionId, {
             sessionUpdate: "tool_call",
-            toolCallId: part?.call_id ?? randomUUID(),
+            toolCallId: part?.call_id ?? randomUUID2(),
             title: part?.tool_name ?? "tool",
             kind: "other",
             status: "in_progress"
@@ -467,21 +956,18 @@ var AcpAgent = class {
           }
           break;
         }
-        case "turn.status_idle":
-          if (sawTurnActivity) settle("end_turn");
+        case "session.status_idle":
+          if (sawTurnActivity) settle(this.interruptRequested ? "cancelled" : "end_turn");
           break;
-        case "turn.interrupted":
-          settle("cancelled");
-          break;
-        case "error": {
-          const code = typeof event.code === "string" ? event.code : "";
-          if (code === "enqueue_failed") {
-            fail(new Error("turn enqueue failed \u2014 pod unavailable"));
-          } else {
-            log(`stream error event: ${code} ${String(event.message ?? "")}`);
-          }
+        case "session.error": {
+          const error = event.error;
+          const retry = typeof error?.retry_status === "string" ? ` (${error.retry_status})` : "";
+          log(`session error: ${String(error?.type ?? "")} ${String(error?.message ?? "")}${retry}`);
           break;
         }
+        case "session.status_terminated":
+          fail(new Error("session terminated"));
+          break;
         case "session.deleted":
           fail(new Error("session deleted"));
           break;
@@ -490,46 +976,177 @@ var AcpAgent = class {
     this.inflight = true;
     const timeout = setTimeout(() => {
       log(`turn timeout after ${this.config.turnTimeoutMs}ms \u2014 interrupting`);
+      this.interruptRequested = true;
       this.api.interrupt(sessionId).catch(() => void 0);
       settle("cancelled");
     }, this.config.turnTimeoutMs);
+    let requestPollStop = null;
+    if (taskId) {
+      requestPollStop = this.startRequestPoll(acpSessionId, taskId, done);
+    }
     try {
       await Promise.race([
         bus.waitConnected(),
         new Promise((resolve) => setTimeout(resolve, 1e4))
       ]);
-      await this.api.sendMessage(sessionId, `${text}
+      const turnKey = randomUUID2();
+      const messageText = this.config.replyPost && channelId ? `${userText}
 
-${BRIDGE_NOTE}`, randomUUID());
+${BRIDGE_NOTE}` : userText;
+      if (systemText) {
+        await this.api.sendMessageWithContext(sessionId, messageText, systemText, turnKey);
+      } else {
+        await this.api.sendMessage(sessionId, messageText, turnKey);
+      }
+      sawTurnActivity = true;
       const stopReason = await done;
       if (this.config.replyPost && channelId && replyText.trim()) {
         await postReply(this.config.buzzBin, channelId, replyText.trim());
-      } else if (!channelId && replyText.trim()) {
+      } else if (!channelId && replyText.trim() && this.config.replyPost) {
         log("no channel UUID found in prompt \u2014 reply not posted to buzz");
       }
       return { stopReason };
     } catch (error) {
       if (error instanceof ApiError) {
+        if (error.status === 401 || error.status === 403) {
+          throw new RpcError(-32e3, `authentication failed: ${error.message}`);
+        }
         throw new RpcError(-32603, `agentsky api error (${error.code}): ${error.message}`);
       }
       throw error instanceof RpcError ? error : new RpcError(-32603, error instanceof Error ? error.message : String(error));
     } finally {
       clearTimeout(timeout);
       unsubscribe();
+      requestPollStop?.();
       this.inflight = false;
     }
   }
+  // ── Task request forwarding (item 4) ─────────────────────────────────────
+  startRequestPoll(acpSessionId, taskId, turnDone) {
+    let stopped = false;
+    const stop = () => {
+      stopped = true;
+    };
+    void (async () => {
+      const POLL_INTERVAL_MS = 3e3;
+      const handledRequests = /* @__PURE__ */ new Set();
+      while (!stopped) {
+        await Promise.race([
+          new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS)),
+          turnDone
+        ]);
+        if (stopped) break;
+        let openRequests;
+        try {
+          openRequests = await this.api.listOpenRequests(taskId);
+        } catch {
+          continue;
+        }
+        for (const req of openRequests) {
+          if (handledRequests.has(req.id)) continue;
+          handledRequests.add(req.id);
+          void this.handleTaskRequest(acpSessionId, taskId, req);
+        }
+      }
+    })();
+    return stop;
+  }
+  async handleTaskRequest(acpSessionId, taskId, req) {
+    const permissionType = this.mapKindToPermission(req.kind);
+    let granted = false;
+    try {
+      const response = await this.rpc.request(
+        "session/request_permission",
+        {
+          sessionId: acpSessionId ?? "",
+          permission: {
+            type: permissionType,
+            title: req.subject ?? req.kind,
+            description: req.question ?? "",
+            options: req.options,
+            allowFreeText: req.allow_free_text,
+            requestId: req.id
+          }
+        },
+        this.config.requestTimeoutMs
+      );
+      granted = response?.granted === true;
+    } catch (error) {
+      log(
+        `permission request timed out or failed for ${req.id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      granted = false;
+    }
+    const answer = granted ? { decision: "approved" } : this.d5Fallback(req);
+    try {
+      await this.api.answerRequest(taskId, req.id, answer);
+    } catch (error) {
+      log(
+        `failed to answer request ${req.id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  mapKindToPermission(kind) {
+    switch (kind) {
+      case "approval":
+        return "execute";
+      case "spend":
+        return "spend";
+      case "connect_app":
+        return "connect";
+      case "connect_account":
+        return "connect";
+      case "question":
+        return "question";
+      default:
+        return kind;
+    }
+  }
+  d5Fallback(req) {
+    switch (req.kind) {
+      case "approval":
+      case "spend":
+        return { decision: "declined", reason: "ACP harness did not grant permission" };
+      case "connect_app":
+      case "connect_account":
+        return {
+          decision: "declined",
+          reason: "ACP harness did not grant permission",
+          link: req.link ?? null
+        };
+      case "question":
+        return {
+          decision: "answered",
+          answer: "No one can answer here; proceed on your best judgement and state what you assumed"
+        };
+      default:
+        return { decision: "declined", reason: "ACP harness did not grant permission" };
+    }
+  }
+  // ── Cancel ────────────────────────────────────────────────────────────────
   async cancel() {
-    if (!this.sessionId || !this.inflight) return;
-    await this.api.interrupt(this.sessionId).catch((error) => {
+    if (!this.inflight) return;
+    this.interruptRequested = true;
+    let sessionId = null;
+    if (this.config.sessionMode === "agent" && this.sharedState) {
+      sessionId = this.sharedState.skySessionId;
+    } else {
+      const last = [...this.perAcpSessions.values()].at(-1);
+      if (last) sessionId = last.skySessionId;
+    }
+    if (!sessionId) return;
+    await this.api.interrupt(sessionId).catch((error) => {
       log(`interrupt failed: ${error instanceof Error ? error.message : String(error)}`);
     });
+    await new Promise((resolve) => setTimeout(resolve, 5e3));
   }
   update(sessionId, update) {
     this.rpc.notify("session/update", { sessionId: sessionId ?? "", update });
   }
   shutdown() {
-    this.bus?.stop();
+    for (const state of this.perAcpSessions.values()) state.bus.stop();
+    this.sharedState?.bus.stop();
+    this.bridge.stop();
   }
 };
 
@@ -545,7 +1162,9 @@ async function main() {
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
-  log(`agentsky-acp ${VERSION} \u2014 agent ${config.agent} via ${config.apiBase}`);
+  log(
+    `agentsky-acp ${VERSION} \u2014 agent ${config.agent} via ${config.apiBase} (session=${config.sessionMode}, context-block=${config.contextBlock})`
+  );
   await rpc.run();
   shutdown();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsky/acp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "agentsky-acp — ACP (Agent Client Protocol) adapter: run an AgentSky cloud agent as a local ACP agent over stdio.",
   "license": "MIT",
   "type": "module",