@particle-academy/prism-acp 0.3.0 → 0.4.1

package/README.md

@@ -146,6 +146,54 @@ 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.
+
+**It looks where the CLI looks, including `CLAUDE_CONFIG_DIR`.** The CLI resolves
+its configuration home as that variable or, unset, `<home>/.claude`, and keeps
+`projects` under whichever it picked — so the probe does the same. This is not a
+detail: an installation that sets it does so because the stored subscription
+credential lives there, which is exactly the installation whose resumes matter,
+and reading the wrong store would report a real conversation `absent` and refuse
+a resume that would have worked.
+
+`childEnv` passes that variable through unchanged, so a driver spawned from this
+process resolves the same store the probe read, by construction. Hand the driver
+a `parentEnv` you built yourself and hand the same environment to the probe, or
+name the store outright:
+
+```ts
+const probeSession = (sessionId: string) => probeSessionStore(sessionId, { env: parentEnv });
+```
+
+`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 +261,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,34 @@
+/**
+ * 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;
+    /**
+     * The CLI's configuration home, naming the store directly. Outranks both
+     * {@link home} and the environment -- for a caller that knows where the store
+     * is, or that builds the driven CLI's environment itself.
+     */
+    readonly configDir?: string;
+    /**
+     * The environment the DRIVEN CLI will see, read for `CLAUDE_CONFIG_DIR`.
+     *
+     * Defaults to this process's own, which is correct by construction when the
+     * driver is spawned from here: `childEnv` passes `CLAUDE_CONFIG_DIR` through
+     * unchanged, so the probe and the child resolve one store. Hand the driver a
+     * `parentEnv` of your own and hand the same one here, or they will not.
+     */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export declare function probeSessionStore(sessionId: string, options?: SessionStoreOptions): SessionProbe;

package/dist/claude/session-store.js

@@ -0,0 +1,132 @@
+// 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 { isAbsolute, 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;
+/**
+ * WHERE THE STORE IS. The CLI resolves its configuration home as
+ * `CLAUDE_CONFIG_DIR` or, unset, `<home>/.claude`, and keeps `projects` under
+ * whichever it picked.
+ *
+ * Reading only the second was this probe's one serious bug (0.4.0). An
+ * installation that sets the variable -- Genie forwards it deliberately,
+ * because the stored subscription credential lives there and is what lets a
+ * child run with no API key at all -- had the probe read a store the CLI does
+ * not use, find nothing, and report `absent` for a conversation that exists.
+ * That refuses a resume that would have worked: the failure this whole
+ * three-state design exists to avoid, reintroduced by the check meant to
+ * prevent it.
+ *
+ * The variable names the configuration home ITSELF, so `projects` sits directly
+ * inside it and no `.claude` is appended. Resolving it as
+ * `home: dirname(CLAUDE_CONFIG_DIR)` instead would work only while the
+ * directory happens to be named `.claude`.
+ */
+function storeRoot(options) {
+    const configured = options.configDir ?? (options.env ?? process.env).CLAUDE_CONFIG_DIR;
+    const trimmed = configured?.trim();
+    // The CLI reads it with `||`, so an empty or blank value is no value. Taking
+    // it literally would resolve `projects` against this process's working
+    // directory.
+    if (trimmed === undefined || trimmed === '') {
+        return { root: join(options.home ?? homedir(), '.claude', 'projects') };
+    }
+    // The CLI refuses to run at all with a relative configuration home -- "the
+    // configuration home (CLAUDE_CONFIG_DIR) is not an absolute path" -- so there
+    // is no store to name, and resolving it against our own cwd would answer
+    // about a directory the CLI never looks in. It is also not a case for the
+    // `<home>/.claude` fallback: the CLI will not fall back either.
+    if (!isAbsolute(trimmed)) {
+        // The value itself stays out of the message. Every other `detail` here
+        // names the path it looked at, which is useful and harmless for a path we
+        // derived; this one is an environment value, and a detail string travels to
+        // the client.
+        return { reason: 'CLAUDE_CONFIG_DIR is not an absolute path, so the session store it names cannot be located' };
+    }
+    return { root: join(trimmed, 'projects') };
+}
+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 resolved = storeRoot(options);
+    if ('reason' in resolved)
+        return { existence: 'indeterminate', detail: resolved.reason };
+    const { root } = resolved;
+    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.1",
   "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": {