@particle-academy/prism-acp 0.2.0 → 0.3.0

package/README.md

@@ -109,6 +109,43 @@ implementations of one protocol disagree without anyone noticing. So:
   line here can carry a prompt, a file or a credential, and a framing error is
   not a reason to copy it into a log.
 
+## Resuming a session: use the CLI's id, not ACP's
+
+`session/load` works, and `initialize` reports `loadSession: true`. The trap is
+which id to pass.
+
+**ACP's `sessionId` is not resumable.** `session/new` returns an id this server
+minted; the CLI has its own session id, a UUID, and `claude --resume` accepts
+only that one (or a session title). The two are deliberately separate, and the
+CLI's is published on the **first** `session/update` of every session:
+
+```ts
+import { META_CLI_SESSION_ID } from '@particle-academy/prism-acp';
+
+// on the first session/update of a session
+const cliSessionId = update._meta?.[META_CLI_SESSION_ID];
+// store this against your own record -- it is what survives a restart
+```
+
+Then after a crash, a kill, or a restart:
+
+```
+session/load { sessionId: <the cli session id>, cwd: <absolute> }
+```
+
+Pass the ACP id instead and you get an error naming the key above, rather than a
+success followed by a dead first prompt. That refusal exists because the CLI's
+own complaint arrives one turn too late: it does error on an id it cannot
+resume -- verified against claude 2.1.292 for both a non-UUID and a well-formed
+UUID that does not exist, and it never silently starts a fresh conversation --
+but by then `session/load` has already returned `{}` and you believe you have a
+resumed session.
+
+A session whose agent has **exited** is loadable; one whose agent is **still
+running** is refused, by either id. No history is replayed on load, because the
+CLI replays none -- `session/load` returning `{}` with no `session/update`
+notifications is the honest report of that, not an omission.
+
 ## Rate limits are a gauge, not just a breach event
 
 ACP has no field for a rate limit, so the detail rides in `_meta` under

package/dist/acp/agent.js

@@ -22,13 +22,25 @@
  * reported absent rather than optimistically.
  */
 import { RPC_INVALID_PARAMS, RPC_INTERNAL_ERROR, RpcError } from '../jsonrpc.js';
+import { META_CLI_SESSION_ID } from '../meta.js';
 /** The protocol version this agent speaks. */
 export const PROTOCOL_VERSION = 1;
+/**
+ * The shape `#sessionNew` mints: `sess_<counter>_<epoch ms>`.
+ *
+ * Deliberately narrow. A broader "does not look like a UUID" test would refuse
+ * a session TITLE, which the CLI accepts alongside a UUID -- so this refuses
+ * only the ids this server is known to have handed out and which provably
+ * cannot resume.
+ */
+const MINTED_SESSION_ID = /^sess_\d+_\d+$/;
 export class AcpAgent {
     #peer;
     #options;
     #sessions = new Map();
     #counter = 0;
+    /** Ids this process handed out via session/new. See the refusal in #sessionLoad. */
+    #minted = new Set();
     constructor(peer, options) {
         this.#peer = peer;
         this.#options = options;
@@ -95,6 +107,7 @@ export class AcpAgent {
     #sessionNew(params) {
         const cwd = requireAbsoluteCwd(params);
         const id = this.#options.newSessionId?.() ?? `sess_${++this.#counter}_${Date.now()}`;
+        this.#minted.add(id);
         this.#open(id, cwd, undefined);
         return { sessionId: id };
     }
@@ -108,8 +121,60 @@ export class AcpAgent {
         // Resuming an id this server already has open would leave two processes
         // writing updates for one session, and the second would look like the
         // first stuttering.
-        if (this.#sessions.has(sessionId)) {
-            throw new RpcError(RPC_INVALID_PARAMS, `session ${sessionId} is already open`);
+        // Refused only while the session is genuinely LIVE. A session whose agent
+        // process has exited is the main thing anyone resumes -- a crashed or
+        // killed agent, or one lost to a restart -- and refusing that as "already
+        // open" described the map rather than reality: an exited session is never
+        // removed from it, only flagged. The old check made the one case resume
+        // exists for the one case it rejected.
+        const existing = this.#sessions.get(sessionId);
+        if (existing !== undefined && !existing.exited) {
+            throw new RpcError(RPC_INVALID_PARAMS, `session ${sessionId} is already open and its agent is still running`);
+        }
+        // The same refusal, by the CLI's id rather than ACP's.
+        //
+        // The sessions map is keyed by the ACP session id, so a lookup for a CLI id
+        // never matched a session opened by `session/new` -- meaning a client
+        // resuming a conversation whose agent was STILL RUNNING got a second agent
+        // on the same conversation, with no collision reported. That was
+        // unreachable while nothing could obtain a CLI id to resume with, and
+        // publishing the id is exactly what makes it reachable. Fixing the one
+        // without the other would have traded a dead end for two processes writing
+        // updates for one conversation.
+        for (const session of this.#sessions.values()) {
+            if (!session.exited && session.driver?.cliSessionId === sessionId) {
+                throw new RpcError(RPC_INVALID_PARAMS, `session ${sessionId} is already open as ${session.id} and its agent is still running`);
+            }
+        }
+        // REFUSE an id this server minted, because `--resume` provably cannot take
+        // it: `session/new` returns an id of OUR making, the CLI has its own UUID,
+        // and only the CLI's works. A client that stored the id it was handed and
+        // passed it back here was the obvious thing to do and could never have
+        // worked.
+        //
+        // Refused HERE rather than left to the CLI, even though the CLI does error
+        // on it (verified: "is not a UUID and does not match any session title",
+        // and "No conversation found with session ID" for a well-formed one that
+        // does not exist -- it never silently starts a fresh conversation). That
+        // error arrives when the FIRST PROMPT runs, by which point `session/load`
+        // has already returned success and the client believes it has a resumed
+        // session. Moving the refusal to the load makes the failure land where the
+        // mistake was made, and the message can say what to pass instead -- which
+        // the CLI's cannot, because the CLI has never heard of ACP.
+        // Two tests, because neither alone is enough. The PATTERN catches the
+        // default mint and survives a restart, which is the case that matters most
+        // -- but an embedder supplying its own `newSessionId` is not covered by it.
+        // The SET catches any id this process actually handed out, whatever its
+        // shape, and does not survive a restart.
+        //
+        // Nothing covers "an id minted by a previous process using an injected
+        // generator", and nothing can: this server cannot tell such a string from a
+        // CLI session title by inspection. That residue is exactly why the CLI's
+        // own id is published in `_meta` rather than left to be guessed at.
+        if (MINTED_SESSION_ID.test(sessionId) || this.#minted.has(sessionId)) {
+            throw new RpcError(RPC_INVALID_PARAMS, `${sessionId} is an ACP session id minted by this server, which 'claude --resume' cannot accept. ` +
+                `Resume with the CLI's own session id, sent as '${META_CLI_SESSION_ID}' in the _meta of the first ` +
+                `session/update of the original session.`);
         }
         this.#open(sessionId, cwd, sessionId);
         // The spec's result is an empty object; history arrives as session/update

package/dist/claude/to-acp.js

@@ -21,7 +21,7 @@
  * `{"index": 0, "delta": {...}}` and have no idea whether that is prose,
  * reasoning, or the arguments to a command about to run.
  */
-import { META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, withMeta, } from '../meta.js';
+import { META_CLI_SESSION_ID, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, withMeta, } from '../meta.js';
 import { rateLimitNotice, readRateLimit } from './rate-limit.js';
 /**
  * ACP's ten tool kinds.
@@ -237,7 +237,24 @@ export class ClaudeToAcp {
                 return [
                     withMeta({ sessionUpdate: 'notice', notice: { level: 'debug', message: 'thinking' } }, { [META_THINKING_TOKENS_ESTIMATE]: input.estimated_tokens ?? null }),
                 ];
-            case 'init':
+            case 'init': {
+                // The init frame carries the CLI's OWN session id, and that is the only
+                // string `--resume` accepts -- so it is the only string `session/load`
+                // can work with. It used to be recorded as unmapped, which meant the
+                // driver captured it, kept it correctly separate from ACP's sessionId,
+                // and then nothing handed it to the client. Resume was a method the
+                // client could not supply an argument for.
+                //
+                // Emitted on the FIRST frame of a session rather than at the end of a
+                // turn: a session that fails early still needs to be resumable, and a
+                // client cannot store what it was never sent.
+                const cliSessionId = asString(input.session_id);
+                if (cliSessionId === undefined)
+                    return this.#unknown(input);
+                return [
+                    withMeta({ sessionUpdate: 'notice', notice: { level: 'debug', message: 'session started' } }, { [META_CLI_SESSION_ID]: cliSessionId }),
+                ];
+            }
             case 'status':
             case 'api_retry':
                 // Not mapped, but RECORDED. api_retry especially: it is how an

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { BASE_ALLOW, OUTRANKING_CREDENTIALS, childEnv } from './env.js';
 export type { ChildEnvOptions, ChildEnvResult } from './env.js';
 export { JsonRpcPeer, RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, RpcError, } from './jsonrpc.js';
 export type { JsonRpcPeerOptions, NotificationHandler, RequestHandler, RpcId, } from './jsonrpc.js';
-export { META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
+export { META_CLI_SESSION_ID, META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
 export { ClaudeToAcp } from './claude/to-acp.js';
 export type { AcpUpdate, ToolStatus } from './claude/to-acp.js';
 export { parseRateLimit, rateLimitNotice, readRateLimit } from './claude/rate-limit.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { MAX_LINE_BYTES, NdjsonFramer, encodeLine, parseLine } from './ndjson.js';
 export { BASE_ALLOW, OUTRANKING_CREDENTIALS, childEnv } from './env.js';
 export { JsonRpcPeer, RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, RpcError, } from './jsonrpc.js';
-export { META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
+export { META_CLI_SESSION_ID, META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
 export { ClaudeToAcp } from './claude/to-acp.js';
 export { parseRateLimit, rateLimitNotice, readRateLimit } from './claude/rate-limit.js';
 export { ClaudeDriver, claudeArgs, promptLine, updatesFromFrames } from './claude/driver.js';

package/dist/meta.d.ts

@@ -71,6 +71,25 @@ export declare const META_THINKING_TOKENS_ESTIMATE: string;
 export declare const META_RATE_LIMIT: string;
 /** The CLI frame a mapping could not place, kept so nothing is lost unseen. */
 export declare const META_UNMAPPED_FRAME: string;
+/**
+ * The CLI's OWN session id -- the only string `session/load` can resume with.
+ *
+ * This exists because its absence was a hole in the middle of resume. ACP's
+ * `sessionId` is minted by this server; the CLI has a different id of its own,
+ * a UUID, and `--resume` wants that one. The two were kept correctly separate
+ * inside the driver and then **never handed to the client**, so a client that
+ * stored the id `session/new` returned and passed it back to `session/load`
+ * was passing a string the CLI cannot resume.
+ *
+ * ACP has no field for a provider's internal session id, which is precisely
+ * what `_meta` is for. It rides on the `init` frame's notice, so it is the
+ * first thing a client learns about a session -- a client that only reads it
+ * after the first turn would miss it on a session that fails early.
+ *
+ * Store it against your own record of the session. It is what you pass to
+ * `session/load` after a restart, and ACP's own `sessionId` is not.
+ */
+export declare const META_CLI_SESSION_ID: string;
 /**
  * Attach `_meta` entries to an ACP object without disturbing its own fields.
  *

package/dist/meta.js

@@ -83,6 +83,25 @@ export const META_THINKING_TOKENS_ESTIMATE = metaKey('thinking_tokens_estimate')
 export const META_RATE_LIMIT = metaKey('rate_limit');
 /** The CLI frame a mapping could not place, kept so nothing is lost unseen. */
 export const META_UNMAPPED_FRAME = metaKey('unmapped_frame');
+/**
+ * The CLI's OWN session id -- the only string `session/load` can resume with.
+ *
+ * This exists because its absence was a hole in the middle of resume. ACP's
+ * `sessionId` is minted by this server; the CLI has a different id of its own,
+ * a UUID, and `--resume` wants that one. The two were kept correctly separate
+ * inside the driver and then **never handed to the client**, so a client that
+ * stored the id `session/new` returned and passed it back to `session/load`
+ * was passing a string the CLI cannot resume.
+ *
+ * ACP has no field for a provider's internal session id, which is precisely
+ * what `_meta` is for. It rides on the `init` frame's notice, so it is the
+ * first thing a client learns about a session -- a client that only reads it
+ * after the first turn would miss it on a session that fails early.
+ *
+ * Store it against your own record of the session. It is what you pass to
+ * `session/load` after a restart, and ACP's own `sessionId` is not.
+ */
+export const META_CLI_SESSION_ID = metaKey('cli_session_id');
 /**
  * Attach `_meta` entries to an ACP object without disturbing its own fields.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-acp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Speak the Agent Client Protocol to a coding-agent CLI the user has already authenticated. No API key, no third-party adapter.",
   "license": "MIT",
   "repository": {