@particle-academy/prism-acp 0.1.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Particle Academy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -109,6 +109,101 @@ 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
+`particle.academy/rate_limit` alongside a human-readable notice. It is a
+**declared type**, not a passthrough:
+
+```ts
+import { parseRateLimit, type ClaudeRateLimit } from '@particle-academy/prism-acp';
+
+const limit: ClaudeRateLimit | undefined = parseRateLimit(payload);
+const fiveHour = limit?.windows.five_hour;
+
+if (fiveHour !== undefined) {
+  const remaining = Math.max(0, 1 - fiveHour.utilization);
+  console.log(`${Math.round(remaining * 100)}% left, resets ${new Date(fiveHour.resetsAtMs)}`);
+}
+```
+
+The frame arrives **mid-turn with `status: "allowed"`**, not only once you are
+limited, and `utilization` moves as work is done — so remaining headroom is a
+real reading rather than a feature invented to fill a panel.
+
+Three things a consumer needs and cannot infer:
+
+- **`resetsAt` is epoch SECONDS on the wire.** `resetsAtMs` is this package's,
+  converted once. Read the provider's field as milliseconds and every reset
+  time lands in January 1970.
+- **`utilization` can exceed 1.** The frame models overage, so a window past
+  its allowance is a real state; the parse does not cap it, because a capped
+  figure would be one this package made up. Clamp where you draw the bar, next
+  to `isUsingOverage`.
+- **`status` and `overageStatus` are open string unions.** Every frame captured
+  says `"allowed"`; no breached frame has ever been captured, so the breached
+  spelling is unknown. Test `status !== 'allowed'`, and never match a specific
+  breach value.
+
+`parseRateLimit` returns `undefined` rather than a partial, and a payload it
+does not recognise gets **no `rate_limit` key at all** — the frame goes to
+`particle.academy/unmapped_frame` instead, **with the field that failed named**:
+
+```
+rate_limit: unifiedWindows.five_hour.utilization expected finite number >= 0, got null
+```
+
+That reason is load-bearing precisely because the refusal is total: one bad
+field rejects the whole payload, so this string is the only thing a human gets.
+Generic would mean a bug report of "the gauge vanished" rather than "they
+renamed `utilization`". `readRateLimit()` returns it to you directly
+(`{ ok: true, limit } | { ok: false, reason }`) if you would rather handle the
+refusal than check for `undefined`.
+
+A string value is described as `string(10)`, never quoted. This mapper sits on
+the same stream as prompts, file contents and credentials, and the type tells
+you a number became a string just as well as the digits would. That is the whole reason it is a
+parse and not an interface: an interface over `unknown` is a cast, so a renamed
+provider field would still read as `undefined`, and a gauge renders `undefined`
+as empty. An empty headroom gauge is read by a human as plenty of headroom.
+
 ## Using it
 
 ```ts
@@ -117,8 +212,7 @@ import { serve, ClaudeDriver } from '@particle-academy/prism-acp';
 serve({
   input: process.stdin,
   output: process.stdout,
-  driverFactory: (options, events) =>
-    new ClaudeDriver({ cwd: options.cwd, ...options }, events),
+  driverFactory: (options, events) => new ClaudeDriver(options, events),
 });
 ```
 

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

@@ -0,0 +1,141 @@
+/**
+ * The rate-limit payload the Claude CLI reports, declared and narrowed.
+ *
+ * ## Why a parse and not just an interface
+ *
+ * This shipped as `input.rate_limit_info ?? input` -- passed through verbatim,
+ * with nothing in the `.d.ts` naming a field. A consumer building a headroom
+ * gauge then has to guess the provider's field names off a captured frame, and
+ * the failure mode when the provider renames one is the worst available: the
+ * read yields `undefined`, the gauge renders empty, and a human reads an empty
+ * gauge as PLENTY OF HEADROOM. A wrong answer delivered confidently.
+ *
+ * An interface alone does not fix that. The payload crosses a pipe as JSON, so
+ * it arrives as `unknown`, and an interface over `unknown` is a cast: a rename
+ * still produces the same silent `undefined`, only now with a type annotation
+ * standing behind it. What makes a rename LOUD is {@link parseRateLimit}
+ * refusing the shape, so the mapper can emit no gauge at all and say what it
+ * actually received instead. Absent and explained beats zero and plausible.
+ *
+ * ## Where the shape came from
+ *
+ * Three independently captured turns in `test/fixtures`, which agree on every
+ * key. Nothing here is inferred from a schema, because no schema for this frame
+ * was available -- the same provenance rule as the rest of this mapper.
+ *
+ * ## What the captures do NOT tell us
+ *
+ * Every captured frame says `status: "allowed"`. **No breached frame has ever
+ * been captured**, so how a breach is spelled is genuinely unknown, and so are
+ * the `overageStatus` values beyond `"rejected"`. Those stay open string unions
+ * on purpose -- see {@link ClaudeRateLimit.status}.
+ */
+/** One rate-limit window, as the provider reports it. */
+export interface ClaudeRateLimitWindow {
+    /**
+     * The fraction of this window consumed -- `0.12` is 12% used.
+     *
+     * **This can exceed 1.** The frame models overage (`isUsingOverage`,
+     * `overageStatus`), so a window consumed past its allowance is a real state
+     * and not a corrupt reading. {@link parseRateLimit} therefore accepts any
+     * finite value `>= 0` and does NOT cap it at 1: a capped figure would be a
+     * number this package made up. Clamp for a progress bar if you like, but
+     * clamp at the point of display, where a reader can also see
+     * `isUsingOverage`.
+     */
+    readonly utilization: number;
+    /** When this window resets, in epoch MILLISECONDS. See {@link ClaudeRateLimit.resetsAtMs}. */
+    readonly resetsAtMs: number;
+}
+/** The structured rate-limit detail carried under `particle.academy/rate_limit`. */
+export interface ClaudeRateLimit {
+    /**
+     * `"allowed"` in every frame captured so far.
+     *
+     * The union is OPEN (`'allowed' | (string & {})`) deliberately, which keeps
+     * the known literal in autocomplete while accepting any string. A closed
+     * union would be the same silent-failure class inverted: it would break a
+     * consumer's BUILD the first time a real breach arrived, which is worse than
+     * the problem it was guarding against. Test `status !== 'allowed'` for "not
+     * allowed"; never match a specific breach spelling, because nobody here has
+     * seen one.
+     */
+    readonly status: 'allowed' | (string & {});
+    /**
+     * When the binding window resets, in epoch MILLISECONDS.
+     *
+     * **The provider sends SECONDS**, in a field named `resetsAt` that gives no
+     * hint of its unit. This field is named for its unit and converted exactly
+     * once, here, because the alternative is every consumer deciding
+     * independently and one of them rendering January 1970.
+     *
+     * No seconds-vs-milliseconds heuristic is applied. A range sniff would
+     * silently absorb a unit change by the provider; the conversion is
+     * unconditional so `test/rate-limit.test.ts` fails instead -- it pins the
+     * captured values to their real dates.
+     */
+    readonly resetsAtMs: number;
+    /** Which window the provider currently treats as binding, e.g. `"five_hour"`. */
+    readonly rateLimitType: string;
+    /** Open union for the same reason as {@link ClaudeRateLimit.status}: only `"rejected"` has been seen. */
+    readonly overageStatus?: string;
+    readonly overageDisabledReason?: string;
+    readonly isUsingOverage?: boolean;
+    /** Every window the frame reported, keyed as the provider keys them (`five_hour`, `seven_day`). */
+    readonly windows: Readonly<Record<string, ClaudeRateLimitWindow>>;
+    /**
+     * The provider's object, verbatim.
+     *
+     * Kept ON the typed value rather than beside it, so one `_meta` key always
+     * carries both views. It covers the case a refusal cannot: a field the
+     * provider ADDS still parses, and would otherwise be dropped by a type that
+     * does not know about it yet. `src/meta.ts` is explicit that nothing is
+     * silently dropped, and a narrowing parse is exactly where that rule would
+     * otherwise be quietly broken.
+     */
+    readonly raw: Record<string, unknown>;
+}
+/**
+ * The result of reading a payload: the value, or WHY it was refused.
+ *
+ * The reason exists because the refusal is total. Since one bad field rejects
+ * the whole payload, the explanation is the ONLY thing a human gets when the
+ * provider changes shape -- so "not recognised" would turn a bug report into
+ * somebody diffing a frame by hand. Raised by prism-acp's first external
+ * reviewer, against this exact design.
+ */
+export type RateLimitRead = {
+    readonly ok: true;
+    readonly limit: ClaudeRateLimit;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Narrow an unknown rate-limit payload, or refuse it.
+ *
+ * Returns `undefined` rather than a partial value. A partial is the thing worth
+ * refusing hardest: a gauge built from half a payload looks like a reading.
+ *
+ * **One malformed window refuses the WHOLE payload.** Dropping the bad window
+ * and keeping the rest would mean a consumer whose `five_hour` figure went
+ * malformed silently renders the `seven_day` one in its place -- a healthy
+ * number, off the wrong window, with nothing to indicate the substitution.
+ */
+export declare function parseRateLimit(value: unknown): ClaudeRateLimit | undefined;
+/**
+ * The same read, but saying WHY when it refuses.
+ *
+ * {@link parseRateLimit} is the convenience; this is what the mapper uses,
+ * because the mapper is what has to explain itself to a human.
+ */
+export declare function readRateLimit(value: unknown): RateLimitRead;
+/**
+ * The sentence a human reads, built from the figures rather than from nothing.
+ *
+ * The notice this goes on used to say only "The provider reported a rate
+ * limit." -- true, and actionable by no one. The structured half is for a
+ * client; this half is for the person watching, and it should carry the two
+ * numbers they would otherwise have to open a debugger to see.
+ */
+export declare function rateLimitNotice(limit: ClaudeRateLimit): string;

package/dist/claude/rate-limit.js

@@ -0,0 +1,163 @@
+/**
+ * The rate-limit payload the Claude CLI reports, declared and narrowed.
+ *
+ * ## Why a parse and not just an interface
+ *
+ * This shipped as `input.rate_limit_info ?? input` -- passed through verbatim,
+ * with nothing in the `.d.ts` naming a field. A consumer building a headroom
+ * gauge then has to guess the provider's field names off a captured frame, and
+ * the failure mode when the provider renames one is the worst available: the
+ * read yields `undefined`, the gauge renders empty, and a human reads an empty
+ * gauge as PLENTY OF HEADROOM. A wrong answer delivered confidently.
+ *
+ * An interface alone does not fix that. The payload crosses a pipe as JSON, so
+ * it arrives as `unknown`, and an interface over `unknown` is a cast: a rename
+ * still produces the same silent `undefined`, only now with a type annotation
+ * standing behind it. What makes a rename LOUD is {@link parseRateLimit}
+ * refusing the shape, so the mapper can emit no gauge at all and say what it
+ * actually received instead. Absent and explained beats zero and plausible.
+ *
+ * ## Where the shape came from
+ *
+ * Three independently captured turns in `test/fixtures`, which agree on every
+ * key. Nothing here is inferred from a schema, because no schema for this frame
+ * was available -- the same provenance rule as the rest of this mapper.
+ *
+ * ## What the captures do NOT tell us
+ *
+ * Every captured frame says `status: "allowed"`. **No breached frame has ever
+ * been captured**, so how a breach is spelled is genuinely unknown, and so are
+ * the `overageStatus` values beyond `"rejected"`. Those stay open string unions
+ * on purpose -- see {@link ClaudeRateLimit.status}.
+ */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A finite number at or above `minimum`, or `undefined`. */
+function finite(value, minimum) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= minimum
+        ? value
+        : undefined;
+}
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Describe what arrived, WITHOUT quoting it.
+ *
+ * A number, boolean, null or undefined is reported as itself -- those are the
+ * cases that identify a shape change and none of them can carry content. A
+ * STRING is reported as its type and length only, because this module sits on
+ * the same stream as prompts, file contents and credentials, and this package
+ * already refuses to put a framing error's content in a log (see
+ * `MAX_LINE_BYTES` in the README). "expected finite number, got string(10)"
+ * identifies a provider switching a number to a string just as well as the
+ * digits would, and cannot leak anything if a future frame puts something else
+ * in that field.
+ */
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return `string(${value.length})`;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    if (typeof value === 'object')
+        return 'object';
+    return typeof value;
+}
+function refuse(path, expected, got) {
+    return { ok: false, reason: `rate_limit: ${path} expected ${expected}, got ${describe(got)}` };
+}
+/**
+ * Narrow an unknown rate-limit payload, or refuse it.
+ *
+ * Returns `undefined` rather than a partial value. A partial is the thing worth
+ * refusing hardest: a gauge built from half a payload looks like a reading.
+ *
+ * **One malformed window refuses the WHOLE payload.** Dropping the bad window
+ * and keeping the rest would mean a consumer whose `five_hour` figure went
+ * malformed silently renders the `seven_day` one in its place -- a healthy
+ * number, off the wrong window, with nothing to indicate the substitution.
+ */
+export function parseRateLimit(value) {
+    const read = readRateLimit(value);
+    return read.ok ? read.limit : undefined;
+}
+/**
+ * The same read, but saying WHY when it refuses.
+ *
+ * {@link parseRateLimit} is the convenience; this is what the mapper uses,
+ * because the mapper is what has to explain itself to a human.
+ */
+export function readRateLimit(value) {
+    if (!isObject(value))
+        return refuse('payload', 'an object', value);
+    const status = optionalString(value.status);
+    if (status === undefined)
+        return refuse('status', 'string', value.status);
+    const rateLimitType = optionalString(value.rateLimitType);
+    if (rateLimitType === undefined)
+        return refuse('rateLimitType', 'string', value.rateLimitType);
+    const resetsAtSeconds = finite(value.resetsAt, Number.MIN_VALUE);
+    if (resetsAtSeconds === undefined) {
+        return refuse('resetsAt', 'finite number > 0 (epoch seconds)', value.resetsAt);
+    }
+    // An absent `unifiedWindows` is refused, not treated as "no windows": it is
+    // the only part of this payload that answers "how much is left", so a
+    // consumer receiving a typed value without it would have a reset time and no
+    // gauge, which is the shape this type exists to stop being ambiguous.
+    if (!isObject(value.unifiedWindows)) {
+        return refuse('unifiedWindows', 'an object', value.unifiedWindows);
+    }
+    const windows = {};
+    for (const [name, window] of Object.entries(value.unifiedWindows)) {
+        if (!isObject(window))
+            return refuse(`unifiedWindows.${name}`, 'an object', window);
+        const utilization = finite(window.utilization, 0);
+        if (utilization === undefined) {
+            return refuse(`unifiedWindows.${name}.utilization`, 'finite number >= 0', window.utilization);
+        }
+        const windowResetsAtSeconds = finite(window.resetsAt, Number.MIN_VALUE);
+        if (windowResetsAtSeconds === undefined) {
+            return refuse(`unifiedWindows.${name}.resetsAt`, 'finite number > 0 (epoch seconds)', window.resetsAt);
+        }
+        windows[name] = { utilization, resetsAtMs: windowResetsAtSeconds * 1000 };
+    }
+    const isUsingOverage = typeof value.isUsingOverage === 'boolean' ? value.isUsingOverage : undefined;
+    return {
+        ok: true,
+        limit: {
+            status,
+            resetsAtMs: resetsAtSeconds * 1000,
+            rateLimitType,
+            ...(optionalString(value.overageStatus) === undefined
+                ? {}
+                : { overageStatus: value.overageStatus }),
+            ...(optionalString(value.overageDisabledReason) === undefined
+                ? {}
+                : { overageDisabledReason: value.overageDisabledReason }),
+            ...(isUsingOverage === undefined ? {} : { isUsingOverage }),
+            windows,
+            raw: value,
+        },
+    };
+}
+/**
+ * The sentence a human reads, built from the figures rather than from nothing.
+ *
+ * The notice this goes on used to say only "The provider reported a rate
+ * limit." -- true, and actionable by no one. The structured half is for a
+ * client; this half is for the person watching, and it should carry the two
+ * numbers they would otherwise have to open a debugger to see.
+ */
+export function rateLimitNotice(limit) {
+    const binding = limit.windows[limit.rateLimitType];
+    const resetsAtMs = binding?.resetsAtMs ?? limit.resetsAtMs;
+    const used = binding === undefined ? '' : ` at ${Math.round(binding.utilization * 100)}% used`;
+    return `Rate limit: ${limit.rateLimitType} window${used}, resets ${new Date(resetsAtMs).toISOString()}.`;
+}

package/dist/claude/to-acp.js

@@ -21,7 +21,8 @@
  * `{"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.
  *
@@ -236,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
@@ -273,11 +291,35 @@ export class ClaudeToAcp {
     #rateLimit(input) {
         // A notice because it is genuinely user-facing, AND _meta so a client can
         // act on the reset times rather than parse a sentence.
+        //
+        // The payload is NARROWED rather than passed through. A rename by the
+        // provider used to reach the consumer as a field it could not read, which
+        // a gauge renders as empty -- and an empty headroom gauge reads as plenty
+        // of headroom. So an unrecognised payload now emits no rate-limit value at
+        // all and keeps the frame under `unmapped_frame` instead: absent and
+        // explained, rather than zero and plausible.
+        //
+        // The refusal NAMES THE FIELD, because the refusal is total: one bad field
+        // rejects the whole payload, so this reason is the only thing a human gets.
+        // A generic "not recognised" would turn a bug report from "they renamed
+        // utilization" into "the gauge vanished", and someone diffing a frame by
+        // hand to tell the difference.
+        const read = readRateLimit(input.rate_limit_info ?? input);
+        if (!read.ok) {
+            return [
+                withMeta({
+                    sessionUpdate: 'notice',
+                    notice: { level: 'warning', message: 'The provider reported a rate limit.' },
+                }, {
+                    [META_UNMAPPED_FRAME]: { reason: read.reason, frame: input },
+                }),
+            ];
+        }
         return [
             withMeta({
                 sessionUpdate: 'notice',
-                notice: { level: 'warning', message: 'The provider reported a rate limit.' },
-            }, { [META_RATE_LIMIT]: input.rate_limit_info ?? input }),
+                notice: { level: 'warning', message: rateLimitNotice(read.limit) },
+            }, { [META_RATE_LIMIT]: read.limit }),
         ];
     }
     /**

package/dist/index.d.ts

@@ -4,9 +4,11 @@ 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';
+export type { ClaudeRateLimit, ClaudeRateLimitWindow, RateLimitRead } from './claude/rate-limit.js';
 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';

package/dist/index.js

@@ -1,8 +1,9 @@
 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 { serve } from './acp/stdio.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.1.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": {
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",