@particle-academy/prism-acp 0.3.0 → 0.4.0

package/README.md

@@ -146,6 +146,37 @@ 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
@@ -213,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

@@ -176,6 +176,23 @@ export class AcpAgent {
                 `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
         // notifications. We send none, because the CLI replays nothing on --resume

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/index.d.ts

@@ -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

@@ -6,5 +6,6 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-acp",
-  "version": "0.3.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": {