@particle-academy/prism-acp 0.2.0 → 0.4.0

package/README.md

@@ -109,6 +109,74 @@ 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.
+
+### Refusing an unknown id at load, not a turn later
+
+Pass `probeSession` and an id naming **no** conversation is refused by
+`session/load` itself, instead of starting an agent that fails on its first
+prompt:
+
+```ts
+import { probeSessionStore } from '@particle-academy/prism-acp';
+
+const probeSession = (sessionId: string) => probeSessionStore(sessionId);
+```
+
+Pass that to `serve` beside `driverFactory` — see [Using it](#using-it).
+
+It costs a directory listing, not a turn. The obvious probe -- resuming with a
+throwaway prompt -- refuses a bad id for free but **answers** a good one, so it
+would spend a real turn on every successful load.
+
+**It can decline to answer, and that matters more than the refusal.** The result
+is `present`, `absent` or `indeterminate`, and only `absent` refuses. The store's
+layout is undocumented, so a store the probe cannot read -- a relocated home, a
+permissions problem, a future CLI version -- reports `indeterminate` and the load
+proceeds exactly as it did before. Calling a real session absent would refuse a
+resume that would have worked, which is worse than the late error this replaces;
+that error is still there as the backstop.
+
+`probeSession` is yours to supply because the answer belongs to the agent being
+driven, not to ACP: `probeSessionStore` reads claude's session store, and a Codex
+driver would resolve the same question through `thread/resume`. Omit it and
+`session/load` behaves as it always did.
+
 ## 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
@@ -176,6 +244,7 @@ serve({
   input: process.stdin,
   output: process.stdout,
   driverFactory: (options, events) => new ClaudeDriver(options, events),
+  probeSession,
 });
 ```
 

package/dist/acp/agent.d.ts

@@ -54,8 +54,22 @@ export type DriverFactory = (options: {
     readonly cwd: string;
     readonly resumeSessionId?: string;
 }, events: DriverEvents) => AgentDriver;
+/**
+ * Whether a session id names a conversation that can be resumed.
+ *
+ * Injected, and for two reasons. Tests must not read the developer's real
+ * session store; and the answer is a property of the AGENT being driven, not of
+ * ACP -- a Codex driver resolves it through `thread/resume`, not through
+ * claude's `~/.claude/projects` layout. Omit it and `session/load` behaves as it
+ * did before: it accepts the id and the agent reports the problem later.
+ */
+export type SessionProbe = (sessionId: string) => {
+    readonly existence: 'present' | 'absent' | 'indeterminate';
+    readonly detail: string;
+};
 export interface AcpAgentOptions {
     readonly driverFactory: DriverFactory;
+    readonly probeSession?: SessionProbe;
     readonly agentInfo?: {
         readonly name: string;
         readonly title?: string;

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,77 @@ 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.`);
+        }
+        // REFUSE an id that names no conversation, here rather than a turn later.
+        //
+        // Without this the agent starts, `session/load` returns success, and the
+        // CLI's "No conversation found with session ID" arrives when the first
+        // prompt runs -- a real error, but one a client cannot tell from any other
+        // late failure, and one that lands after it has been told it holds a
+        // resumed session. A consumer reported this as the only thing standing
+        // between a bad id and a lost conversation.
+        //
+        // `indeterminate` deliberately PROCEEDS. The probe reads a store whose
+        // layout is undocumented, so a store it cannot read must not be allowed to
+        // refuse a resume that would have worked; the late error is still there as
+        // the backstop it always was. Only a positive `absent` refuses.
+        const probe = this.#options.probeSession?.(sessionId);
+        if (probe?.existence === 'absent') {
+            throw new RpcError(RPC_INVALID_PARAMS, `cannot resume ${sessionId}: ${probe.detail}`);
         }
         this.#open(sessionId, cwd, sessionId);
         // The spec's result is an empty object; history arrives as session/update

package/dist/claude/session-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Three states, and the third is the point.
+ *
+ * `indeterminate` means the store could not be read -- a different CLI version,
+ * a relocated home, a permissions problem, a layout change. It must never be
+ * treated as `absent`: this check exists to turn a late failure into an early
+ * one, and it is not worth refusing a resume that would have worked.
+ */
+export type SessionExistence = 'present' | 'absent' | 'indeterminate';
+export interface SessionProbe {
+    readonly existence: SessionExistence;
+    /** Why, in terms a client can act on. Empty for `present`. */
+    readonly detail: string;
+}
+export interface SessionStoreOptions {
+    /** Overridable so tests never read the developer's real sessions. */
+    readonly home?: string;
+}
+export declare function probeSessionStore(sessionId: string, options?: SessionStoreOptions): SessionProbe;

package/dist/claude/session-store.js

@@ -0,0 +1,87 @@
+// Does a CLI session id name a conversation that exists?
+//
+// `session/load` used to answer this by trying. It spawned the agent with
+// `--resume <id>` and the CLI's refusal -- `No conversation found with session
+// ID: <id>` -- arrived when the FIRST PROMPT ran, by which point `session/load`
+// had already returned success and the client believed it held a resumed
+// session. The failure was real but indistinguishable from any other late
+// error, and a consumer reported it as the only thing standing between a bad id
+// and a lost conversation.
+//
+// WHY NOT PROBE WITH THE CLI. The obvious probe is
+// `claude --resume <id> -p x`, which does refuse a bad id for free. On a GOOD
+// id it resumes the conversation and answers "x" -- a real turn, real tokens,
+// on every successful load. A probe that costs a turn on the happy path is
+// worse than the problem it solves.
+//
+// So this reads the session store instead, which costs a directory listing.
+//
+// WHY SCAN RATHER THAN DERIVE THE PATH. Sessions live at
+// `~/.claude/projects/<slug>/<uuid>.jsonl`, where `<slug>` is the project's cwd
+// with its separators and punctuation replaced by `-`. Deriving that slug means
+// reimplementing an undocumented rule, and getting it wrong would mean looking
+// in a directory that does not exist and calling a VALID session absent --
+// refusing a resume that would have worked, which is a worse failure than the
+// late error this replaces. A session id is a UUID and therefore unique across
+// every project, so looking for the FILE is enough and needs no slug at all.
+import { readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The CLI accepts a UUID, or a session TITLE, and nothing else. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function probeSessionStore(sessionId, options = {}) {
+    // A non-UUID is refused by the CLI outright -- verified against claude
+    // 2.1.292: "Provided value ... is not a UUID and does not match any session
+    // title." Reported as absent without touching the disk, because the store
+    // cannot contain it under any layout.
+    //
+    // This is narrower than it looks: the CLI also accepts a session TITLE, and a
+    // title is not a UUID. It is reported absent anyway, because this server
+    // publishes the CLI's UUID as the thing to resume with and a client passing a
+    // human-chosen title is working from something else.
+    if (!UUID.test(sessionId)) {
+        return {
+            existence: 'absent',
+            detail: `${sessionId} is not a session id the CLI can resume: it is not a UUID.`,
+        };
+    }
+    const root = join(options.home ?? homedir(), '.claude', 'projects');
+    let projects;
+    try {
+        if (!statSync(root).isDirectory()) {
+            return { existence: 'indeterminate', detail: `${root} is not a directory` };
+        }
+        projects = readdirSync(root);
+    }
+    catch (error) {
+        return { existence: 'indeterminate', detail: `${root} could not be read: ${error.message}` };
+    }
+    // An EMPTY store is indeterminate rather than absent. A store with no
+    // projects in it is far more likely to be the wrong store than a genuine
+    // record that this conversation never existed.
+    if (projects.length === 0) {
+        return { existence: 'indeterminate', detail: `${root} lists no projects` };
+    }
+    const wanted = `${sessionId}.jsonl`;
+    let readable = 0;
+    for (const project of projects) {
+        let entries;
+        try {
+            entries = readdirSync(join(root, project));
+        }
+        catch {
+            continue; // One unreadable project does not settle the question.
+        }
+        readable++;
+        if (entries.includes(wanted))
+            return { existence: 'present', detail: '' };
+    }
+    // Every project directory failed to open. Absence has not been established.
+    if (readable === 0) {
+        return { existence: 'indeterminate', detail: `no project directory under ${root} could be read` };
+    }
+    return {
+        existence: 'absent',
+        detail: `no conversation with session id ${sessionId} exists in this installation's session store.`,
+    };
+}

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';
@@ -12,7 +12,9 @@ export type { ClaudeRateLimit, ClaudeRateLimitWindow, RateLimitRead } from './cl
 export { ClaudeDriver, claudeArgs, promptLine, updatesFromFrames } from './claude/driver.js';
 export type { ClaudeDriverEvents, ClaudeDriverOptions, ClaudePermissionMode, } from './claude/driver.js';
 export { AcpAgent, PROTOCOL_VERSION } from './acp/agent.js';
-export type { AcpAgentOptions, AgentDriver, DriverEvents, DriverFactory, } from './acp/agent.js';
+export type { AcpAgentOptions, AgentDriver, DriverEvents, DriverFactory, SessionProbe as AcpSessionProbe, } from './acp/agent.js';
+export { probeSessionStore } from './claude/session-store.js';
+export type { SessionExistence, SessionProbe, SessionStoreOptions } from './claude/session-store.js';
 export { serve } from './acp/stdio.js';
 export type { Served, ServeOptions } from './acp/stdio.js';
 export { cliSessionIdOf, turnOutcomeOf } from './claude/driver.js';

package/dist/index.js

@@ -1,10 +1,11 @@
 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';
 export { AcpAgent, PROTOCOL_VERSION } from './acp/agent.js';
+export { probeSessionStore } from './claude/session-store.js';
 export { serve } from './acp/stdio.js';
 export { cliSessionIdOf, turnOutcomeOf } 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.4.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": {