zcode-acp-server 0.1.0 → 0.3.0

package/dist/handlers/replay.js

@@ -0,0 +1,252 @@
+/**
+ * Tail replay kernel — slicing, cursor pagination, and the `session/load`
+ * replay/`session/load_earlier` handlers (Proposal 0001 / ADR-0003).
+ *
+ * session/load replays history as session/update notifications; for long
+ * sessions that cost is O(full history) on every attach and reconnect. The
+ * helpers here slice the fetched messages into turn-aligned batches and page
+ * backwards with an opaque cursor. Batches are sent under the per-session
+ * replay lock (`withReplayBatch` in io.ts) so a batch never interleaves with
+ * live-turn updates for the same session; `replayMessages` is the one sender
+ * that bypasses the per-message lock — it only runs inside a batch.
+ */
+import { randomUUID } from "node:crypto";
+import { log } from "../utils.js";
+import { throwError, withReplayBatch } from "./io.js";
+/** Upper bound for a requested tail/page size (values above clamp to this). */
+export const MAX_REPLAY_LIMIT = 500;
+/** Page size for `session/load_earlier` when the request omits `limit`. */
+export const DEFAULT_EARLIER_LIMIT = 50;
+/**
+ * Indices where a turn starts: every user message, plus 0 so leading
+ * non-user messages (system preambles) belong to the first turn.
+ */
+function turnStarts(messages) {
+    const starts = messages.length > 0 ? [0] : [];
+    messages.forEach((m, i) => {
+        if (m.info?.role === "user" && i > 0)
+            starts.push(i);
+    });
+    return starts;
+}
+/** Count of turn starts inside [start, end). */
+function turnsInRange(starts, start, end) {
+    return starts.filter((s) => s >= start && s < end).length;
+}
+function encodeCursor(messages, index, totalTurns) {
+    const anchor = messages[index]?.info?.id;
+    const payload = { v: 1, index, totalTurns };
+    if (anchor)
+        payload.id = anchor;
+    return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+function decodeCursor(before) {
+    try {
+        const raw = JSON.parse(Buffer.from(before, "base64url").toString("utf8"));
+        if (raw?.v !== 1 ||
+            !Number.isInteger(raw.index) ||
+            raw.index < 0 ||
+            !Number.isInteger(raw.totalTurns)) {
+            throw new Error("bad shape");
+        }
+        return raw;
+    }
+    catch {
+        // Garbage or foreign cursors are indistinguishable from expired ones.
+        return throwError(-32602, "cursor expired");
+    }
+}
+function buildSlice(messages, starts, start, end) {
+    const totalTurns = starts.length;
+    return {
+        batch: messages.slice(start, end),
+        meta: {
+            cursor: encodeCursor(messages, start, totalTurns),
+            hasMore: start > 0,
+            replayedMessages: end - start,
+            replayedTurns: turnsInRange(starts, start, end),
+            totalMessages: messages.length,
+            totalTurns,
+        },
+    };
+}
+/** The greatest turn start at or before `pos` (0 when none — starts include 0). */
+function alignToTurnStart(starts, pos) {
+    let aligned = 0;
+    for (const s of starts) {
+        if (s <= pos)
+            aligned = s;
+        else
+            break;
+    }
+    return aligned;
+}
+function clampLimit(limit) {
+    return Math.max(0, Math.min(Math.floor(limit), MAX_REPLAY_LIMIT));
+}
+/**
+ * Slice the last `limit` messages, aligned back to the start of the turn
+ * containing the oldest one — never a mid-turn cut. `limit: 0` attaches with
+ * metadata only (cursor anchors at the end of history).
+ */
+export function sliceTail(messages, limit) {
+    const starts = turnStarts(messages);
+    const clamped = clampLimit(limit);
+    if (clamped === 0) {
+        // Metadata-only attach: an empty batch whose cursor anchors at the end of
+        // history, so load_earlier pages the whole tail.
+        return buildSlice(messages, starts, messages.length, messages.length);
+    }
+    if (clamped >= messages.length)
+        return buildSlice(messages, starts, 0, messages.length);
+    const start = alignToTurnStart(starts, messages.length - clamped);
+    return buildSlice(messages, starts, start, messages.length);
+}
+/** Full-history slice (no `_meta.zcode.limit` on session/load). */
+export function fullSlice(messages) {
+    return buildSlice(messages, turnStarts(messages), 0, messages.length);
+}
+/**
+ * Slice up to `limit` messages strictly older than the `before` cursor.
+ * The cursor points into a prefix of history, so turns appended after it was
+ * minted keep it valid; only a history that shrank (compaction/truncation)
+ * throws `cursor expired` — clients map that to a full re-`session/load`.
+ */
+export function sliceBefore(messages, before, limit) {
+    const starts = turnStarts(messages);
+    const cur = decodeCursor(before);
+    if (cur.index > messages.length || cur.totalTurns > starts.length) {
+        return throwError(-32602, "cursor expired");
+    }
+    if (cur.id != null && cur.index < messages.length && messages[cur.index].info?.id !== cur.id) {
+        return throwError(-32602, "cursor expired");
+    }
+    const end = cur.index;
+    if (end === 0)
+        return buildSlice(messages, starts, 0, 0);
+    const clamped = clampLimit(limit);
+    const start = clamped === 0 ? end : alignToTurnStart(starts, Math.max(0, end - clamped));
+    return buildSlice(messages, starts, start, end);
+}
+/**
+ * Read the tail limit from `session/load`'s `_meta.zcode.limit`. The SDK's
+ * zod params schema strips unknown top-level keys, so bridge extensions ride
+ * in `_meta` (ADR-0003). Returns null when absent/non-finite = full replay.
+ */
+export function readTailLimit(params) {
+    const zcode = params._meta?.zcode;
+    const raw = zcode?.limit;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return null;
+    return clampLimit(raw);
+}
+/** Fetch session/messages from zcode (the bridge's only history source). */
+export async function fetchMessages(server, zcodeSid) {
+    const backend = server.ensureBackend();
+    const resp = await backend.request(server.nextId(), "session/messages", { sessionId: zcodeSid }, 8000);
+    if (resp.error)
+        return [];
+    const result = (resp.result ?? {});
+    return result.messages ?? [];
+}
+/**
+ * Strip harness-injected reminder blocks from user text. The agent runtime
+ * appends `<system-reminder>…</system-reminder>` blocks (TodoWrite nudges,
+ * context handoffs) to user turns as context plumbing — they are not user
+ * speech, and replaying them verbatim makes clients render them as user input.
+ */
+function stripSystemReminders(text) {
+    return text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "").trim();
+}
+/**
+ * Replay messages as session/update notifications, oldest → newest.
+ *
+ * MUST run inside `withReplayBatch` for the session: this is the one sender
+ * that bypasses the per-message lock in sendSessionUpdate (the batch already
+ * holds it), which is what makes the batch atomic against live dispatch.
+ */
+export async function replayMessages(cx, acpSid, messages) {
+    let replayed = 0;
+    for (const m of messages) {
+        const info = m.info ?? {};
+        const role = info.role;
+        const mid = info.id ?? `hist_${randomUUID().slice(0, 12)}`;
+        for (const p of m.parts ?? []) {
+            if (!p || typeof p !== "object")
+                continue;
+            const ptype = p.type;
+            if (ptype === "text") {
+                let text = p.text ?? "";
+                if (!text)
+                    continue;
+                if (role === "user") {
+                    text = stripSystemReminders(text);
+                    if (!text)
+                        continue;
+                }
+                await cx.notify("session/update", {
+                    sessionId: acpSid,
+                    update: {
+                        sessionUpdate: role === "user" ? "user_message_chunk" : "agent_message_chunk",
+                        content: { type: "text", text },
+                        messageId: mid,
+                    },
+                });
+            }
+            else if (ptype === "reasoning") {
+                const rp = p;
+                const text = rp.text ?? rp.content ?? "";
+                if (text) {
+                    await cx.notify("session/update", {
+                        sessionId: acpSid,
+                        update: {
+                            sessionUpdate: "agent_thought_chunk",
+                            content: { type: "text", text },
+                            messageId: `thought_${mid}`,
+                        },
+                    });
+                }
+            }
+            else if (ptype === "tool") {
+                const tp = p;
+                const title = tp.title ?? tp.tool ?? "tool call";
+                const histToolName = tp.tool ?? "";
+                await cx.notify("session/update", {
+                    sessionId: acpSid,
+                    update: {
+                        sessionUpdate: "tool_call",
+                        toolCallId: tp.id ?? `histtool_${randomUUID().slice(0, 8)}`,
+                        title,
+                        kind: "other",
+                        status: tp.status ?? "completed",
+                        ...(histToolName ? { _meta: { claudeCode: { toolName: histToolName } } } : {}),
+                    },
+                });
+            }
+            // patch / step-start / other: skipped (history replay focuses on text + tool summary)
+        }
+        replayed += 1;
+    }
+    return replayed;
+}
+/**
+ * `session/load_earlier` — deliver one page of history strictly older than
+ * the `before` cursor, oldest → newest (clients prepend). Requires the
+ * session to already be attached in this bridge; pagination never triggers
+ * an implicit backend resume.
+ */
+export async function loadEarlier(server, params, cx) {
+    const acpSid = params.sessionId;
+    const zcodeSid = server.resolveSid(acpSid);
+    if (!zcodeSid) {
+        return throwError(-32602, "session not registered — attach via session/load first");
+    }
+    if (!params.before)
+        return throwError(-32602, "before (cursor) required");
+    const messages = await fetchMessages(server, zcodeSid);
+    const slice = sliceBefore(messages, params.before, params.limit ?? DEFAULT_EARLIER_LIMIT);
+    await withReplayBatch(acpSid, () => replayMessages(cx, acpSid, slice.batch));
+    log(`session/load_earlier: ${slice.meta.replayedMessages} messages before cursor`);
+    return { replayMeta: slice.meta };
+}
+//# sourceMappingURL=replay.js.map

package/dist/handlers/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/handlers/replay.ts"],"names":[],"mappings":"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"}

package/dist/handlers/server-requests.d.ts

@@ -16,19 +16,35 @@
  */
 import type * as acp from "@agentclientprotocol/sdk";
 import type { ZcodeBackend } from "../backend/client.js";
-import type { ZcodeInteractionResponse } from "../backend/types.js";
+import type { ZcodeInteractionResponse, ZcodeInteractionUserInputParams } from "../backend/types.js";
 import type { PendingTurn, ZcodeAcpServer } from "../server.js";
 /** A dedup entry tracking reannounced zcode ids + the cached result. */
 interface DedupEntry {
-    zcodeIds: number[];
+    zcodeIds: Array<number | string>;
     result?: ZcodeInteractionResponse;
 }
 /** Per-server reannounce dedup state (lazy-initialised). */
 export declare function getPendingInteractions(server: ZcodeAcpServer): Map<string, DedupEntry>;
 /**
- * Drain and handle all pending zcode server→client requests. Returns true if
- * any were handled (used by the turn loop to refresh the no-progress timer).
+ * Drain and handle pending zcode server→client requests for THIS session only.
+ * Returns true if any were handled (used by the turn loop to refresh the
+ * no-progress timer).
+ *
+ * The backend's `serverRequests` queue is shared across all sessions (a single
+ * subprocess serves them all). Without filtering, session A's turn loop could
+ * pop session B's permission request and forward it to A's client — the popup
+ * lands in the wrong session. When `turn` is available we filter by
+ * `params.sessionId` so each turn loop only consumes its own requests; others
+ * are re-queued for their owner. Without `turn` (tests / non-turn callers) we
+ * process everything (legacy behaviour).
  */
 export declare function handleServerRequests(server: ZcodeAcpServer, backend: ZcodeBackend, cx: acp.AgentContext, acpSid: string, turn?: PendingTurn): Promise<boolean>;
+/**
+ * AskUserQuestion: sequential per-question, multi-select per-option.
+ *
+ * Single-select: one popup per question; Skip/cancel → overall decline.
+ * Multi-select: one Include/Skip popup per option; Include picks comma-joined.
+ */
+export declare function handleAskUserQuestion(server: ZcodeAcpServer, cx: acp.AgentContext, acpSid: string, params: ZcodeInteractionUserInputParams, turn?: PendingTurn): Promise<ZcodeInteractionResponse>;
 export {};
 //# sourceMappingURL=server-requests.d.ts.map

package/dist/handlers/server-requests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-requests.d.ts","sourceRoot":"","sources":["../../src/handlers/server-requests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAErD,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAEV,wBAAwB,EAEzB,MAAM,qBAAqB,CAAC;AAkB7B,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGhE,wEAAwE;AACxE,UAAU,UAAU;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,wBAAwB,CAAC;CACnC;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAQtF;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,GAAG,CAAC,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,OAAO,CAAC,CAUlB"}
+{"version":3,"file":"server-requests.d.ts","sourceRoot":"","sources":["../../src/handlers/server-requests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAErD,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAEV,wBAAwB,EACxB,+BAA+B,EAChC,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGhE,wEAAwE;AACxE,UAAU,UAAU;IAClB,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,wBAAwB,CAAC;CACnC;AAwCD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAQtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,GAAG,CAAC,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,OAAO,CAAC,CA8DlB;AA0JD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,EAAE,EAAE,GAAG,CAAC,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,+BAA+B,EACvC,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,wBAAwB,CAAC,CA0EnC"}