zcode-acp-server 0.1.0 → 0.2.0

package/dist/handlers/session.d.ts

@@ -1,18 +1,35 @@
 /**
  * Session lifecycle handlers: initialize, new, list, resume, load, prompt, cancel.
  *
- * These map ACP session methods to ZCode app-server calls. `session/prompt` runs
- * the event-driven turn loop (subscribe-before-send ordering, no-progress
- * timeout, stall reconciliation). ZCode events are translated via
- * EventTranslator and dispatched as ACP `session/update` notifications.
+ * These map ACP session methods to ZCode app-server calls. `session/new` is
+ * lazy: it returns a placeholder id and defers zcode `session/create` to the
+ * session's first use (`ensureRealSession`), so an editor startup that never
+ * prompts leaves no empty session in the backend or the App's task index.
+ * `session/prompt` runs the event-driven turn loop (subscribe-before-send
+ * ordering, no-progress timeout, stall reconciliation). ZCode events are
+ * translated via EventTranslator and dispatched as ACP `session/update`
+ * notifications.
  */
 import type * as acp from "@agentclientprotocol/sdk";
 import type { ZcodeAcpServer } from "../server.js";
-/** `session/new` → zcode `session/create` (mode hardcoded yolo). */
+/**
+ * `session/new` → local placeholder id. The real zcode `session/create` is
+ * deferred to first use (`ensureRealSession`) so an editor startup that never
+ * sends a message leaves no empty session in the backend or the App's task
+ * index. The created session uses mode yolo (hardcoded).
+ */
 export declare function newSession(server: ZcodeAcpServer, params: acp.NewSessionRequest): Promise<acp.NewSessionResponse>;
+/**
+ * Materialize a lazy `session/new` placeholder into a real backend session on
+ * first use (prompt / set_config_option / extension methods). Idempotent:
+ * returns the existing mapping for already-created sessions, and concurrent
+ * first-uses share a single `session/create` via the pending entry's `creating`
+ * promise. Unknown ids throw.
+ */
+export declare function ensureRealSession(server: ZcodeAcpServer, acpSid: string): Promise<string>;
 /** `session/list` → zcode `session/list`. */
 export declare function listSessions(server: ZcodeAcpServer, params: acp.ListSessionsRequest): Promise<acp.ListSessionsResponse>;
-/** `session/resume` → zcode `session/resume` (with runtimeModel overlay for resumed sessions). */
+/** `session/resume` → zcode `session/resume` (with runtimeModel overlay). */
 export declare function resumeSession(server: ZcodeAcpServer, params: acp.ResumeSessionRequest, cx: acp.AgentContext): Promise<acp.ResumeSessionResponse>;
 /**
  * `session/load` → zcode `session/resume` + stream conversation history back as
@@ -27,12 +44,89 @@ export declare function prompt(server: ZcodeAcpServer, params: acp.PromptRequest
  */
 export declare function setConfigOptionHandler(server: ZcodeAcpServer, params: acp.SetSessionConfigOptionRequest, cx: acp.AgentContext): Promise<acp.SetSessionConfigOptionResponse>;
 /**
- * `session/cancel` → mark the pending turn cancelled. The turn loop observes
- * the flag and forwards `session/stop` itself (mirrors Python: cancel only
- * sets the flag; stop is sent by `_run_event_turn`). Eagerly sending stop
- * here would race with a turn that already completed.
+ * `session/cancel` → stop the in-flight turn immediately. Mirrors the ZCode
+ * App's stop button, which sends a stop command directly (there is no
+ * "cancel" concept on the client — only stop).
+ *
+ * We fire `session/stop` here instead of deferring it to the turn loop. The
+ * loop is blocked for seconds at a time behind awaits (handleServerRequests
+ * waiting on a permission popup; dispatchEvent running per-event; the
+ * tool-result path awaiting dispatchEditDiff/dispatchPlanIfChanged backend
+ * calls with up to 8s timeouts). A deferred stop only fires once the loop
+ * finishes whatever await it is stuck in, so the user's press of stop can lag
+ * by the full remaining await window — the turn visibly "keeps running".
+ * `session/stop` is fire-and-forget and fully idempotent (the backend no-ops
+ * on a session with no active turn, and on a turn already aborted), so firing
+ * it eagerly is safe; the loop's `stopSent` guard prevents a second send.
+ *
+ * `turn.cancelled` is still set so the turn loop switches to its silent-drain
+ * path (translate to detect turnDone, but discard every internal event — no
+ * text/tool/usage is pushed after the user stopped).
  */
 export declare function cancel(server: ZcodeAcpServer, params: acp.CancelNotification): Promise<void>;
+/**
+ * Cancel any other in-flight turn for this zcodeSid: fire `session/stop` and
+ * signal the old turn to stop retrying, then return immediately.
+ *
+ * We do NOT wait for the old turn's runEventTurn to exit. Previously this spun
+ * on `pendingTurns` deletion (the old turn's finally), but that signal only
+ * proves "the old turn's loop returned" — NOT "the backend is ready for a new
+ * turn". Waiting on it blocked the new prompt in a long loading state while
+ * the backend's stop-recovery window elapsed, and it still didn't prevent the
+ * next send from racing the backend. The backend's prompt lock is the only
+ * authoritative readiness signal: the new prompt's `session/send` retries
+ * until the lock releases, so there is nothing useful to wait for here.
+ *
+ * The old turn's runEventTurn ends on its own once it sees a terminal event
+ * from the backend (turn.completed/turn.failed after stop). Until then it
+ * keeps dispatching whatever the backend sends for this session — which is
+ * correct, because within a single session the backend is the single source
+ * of truth and its events should reach the client.
+ *
+ * Exported for unit tests (multi-turn pendingTurns scenarios).
+ */
+export declare function preemptInFlightTurn(server: ZcodeAcpServer, zcodeSid: string, selfRequestId: number): boolean;
+/** Concatenate text from ACP ContentBlock[] into a prompt string.
+ *  Exported for unit testing (the resource_link path is easy to break). */
+export declare function extractPromptText(blocks: acp.ContentBlock[] | undefined): string;
+/**
+ * ACP `ContentBlock::Image` → zcode `session/send` attachment.
+ *
+ * zcode's per-attachment normalizer accepts either a `localPath` (absolute FS
+ * path, preferred) or `dataBase64` + `mimeType` (raw base64, no data: prefix).
+ * ACP `ImageContent` carries `data` (base64) and an optional `uri`; when the
+ * uri is a file:// pointer we send localPath so the backend streams from disk
+ * instead of re-encoding.
+ */
+export interface ImageAttachment {
+    kind: "image";
+    filename: string;
+    mimeType: string;
+    sizeBytes?: number;
+    dataBase64?: string;
+    localPath?: string;
+}
+/**
+ * Extract image attachments from ACP ContentBlock[]. Non-image blocks are
+ * ignored (text/resource_link/resource stay owned by `extractPromptText`).
+ * Exported for unit testing.
+ */
+export declare function extractAttachments(blocks: acp.ContentBlock[] | undefined): ImageAttachment[];
+/**
+ * Turn-attribution gate decision (pure, exported for tests): whether an event
+ * observed before this turn's own `turn.started` should be dropped as leftover
+ * residue of a prior turn.
+ *
+ * Residue only exists when this send preempted/cancelled another prompt (its
+ * finalising events land in the new listener's queue). Without preemption the
+ * queue can only carry events of a backend-owned turn already active at send
+ * time — e.g. the main-branch turn auto-resumed after a compaction — which
+ * this send was steered into and which emits no new `turn.started`; dropping
+ * those events would silently swallow the whole turn's output in the UI.
+ */
+export declare function shouldDropEventForTurnAttribution(ev: {
+    type: string;
+}, turnStarted: boolean, preempted: boolean): boolean;
 /**
  * Flatten the todos payload from `session/read`. Prefers the top-level `todos`;
  * when empty, flattens `todoGroups` — the real backend dump carries todos as a
@@ -43,4 +137,13 @@ export declare function flattenTodos(todos: unknown[] | undefined, todoGroups: A
     entries?: unknown[];
     todos?: unknown[];
 }> | undefined): unknown[];
+/**
+ * Re-read the authoritative session mode and, if it changed since the last
+ * value advertised to the client, emit `current_mode_update` +
+ * `config_option_update`. Covers in-turn mode switches performed by internal
+ * tools (EnterPlanMode/ExitPlanMode) that bypass `session/setMode` and thus
+ * emit no notification of their own. Best-effort: failures are logged and
+ * swallowed so they never break the turn-completion path.
+ */
+export declare function emitModeIfChanged(server: ZcodeAcpServer, cx: acp.AgentContext, acpSid: string, zcodeSid: string): Promise<void>;
 //# sourceMappingURL=session.d.ts.map

package/dist/handlers/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/handlers/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAuBrD,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,cAAc,CAAC;AAiBhE,oEAAoE;AACpE,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,iBAAiB,GAC5B,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAuCjC;AAED,6CAA6C;AAC7C,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,mBAAmB,GAC9B,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAmBnC;AAED,kGAAkG;AAClG,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,oBAAoB,EAChC,EAAE,EAAE,GAAG,CAAC,YAAY,GACnB,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CA6BpC;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,kBAAkB,EAC9B,EAAE,EAAE,GAAG,CAAC,YAAY,GACnB,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CA+FlC;AAED,gFAAgF;AAChF,wBAAsB,MAAM,CAC1B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,aAAa,EACzB,EAAE,EAAE,GAAG,CAAC,YAAY,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAgG7B;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,6BAA6B,EACzC,EAAE,EAAE,GAAG,CAAC,YAAY,GACnB,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAa7C;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,GAAG,CAAC,kBAAkB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAUf;AA0WD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EAAE,GAAG,SAAS,EAC5B,UAAU,EAAE,KAAK,CAAC;IAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,GAAG,SAAS,GACxE,OAAO,EAAE,CASX"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/handlers/session.ts"],"names":[],"mappings":"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"}