@particle-academy/prism-acp 0.0.0-stage → 0.2.0

package/dist/claude/driver.d.ts

@@ -0,0 +1,140 @@
+import { NdjsonFramer } from '../ndjson.js';
+import { type AcpUpdate, ClaudeToAcp } from './to-acp.js';
+/** ACP permission modes map onto the CLI's own `--permission-mode` values. */
+export type ClaudePermissionMode = 'acceptEdits' | 'auto' | 'bypassPermissions' | 'manual' | 'dontAsk' | 'plan';
+export interface ClaudeDriverOptions {
+    /** Working directory for the agent. */
+    readonly cwd: string;
+    /** Binary to run. Overridable for tests and unusual installs. */
+    readonly binary?: string;
+    /** Parent environment to build the child's from. Defaults to `process.env`. */
+    readonly parentEnv?: Readonly<Record<string, string | undefined>>;
+    /** Extra environment names to pass through to the child. */
+    readonly allowEnv?: readonly string[];
+    /** Resume an existing CLI session instead of starting a new one. */
+    readonly resumeSessionId?: string;
+    readonly permissionMode?: ClaudePermissionMode;
+    /** Tool names the agent may use. Omitted means the CLI's own default. */
+    readonly allowedTools?: readonly string[];
+    readonly disallowedTools?: readonly string[];
+}
+export interface ClaudeDriverEvents {
+    /** One ACP `session/update` payload. */
+    readonly onUpdate?: (update: AcpUpdate) => void;
+    /**
+     * A line the CLI wrote to stderr.
+     *
+     * Surfaced rather than discarded, because the most valuable diagnostic this
+     * CLI produces arrives here and nowhere else:
+     *
+     *   > claude.ai connectors are disabled because ANTHROPIC_API_KEY or another
+     *   > auth source is set and takes precedence over your claude.ai login
+     *
+     * A driver that dropped stderr would turn the clearest possible explanation
+     * of a billing or auth problem into silence followed by a 401.
+     */
+    readonly onStderr?: (line: string) => void;
+    /** A frame that arrived but could not be framed or parsed. */
+    readonly onProtocolError?: (problem: string) => void;
+    readonly onExit?: (code: number | null, signal: NodeJS.Signals | null) => void;
+    /**
+     * One turn finished.
+     *
+     * Separate from onExit because with `--input-format stream-json` the CLI
+     * stays alive ACROSS turns -- the process exiting and a turn ending are
+     * different events, and a server that conflated them would resolve every
+     * prompt only when the agent shut down.
+     */
+    readonly onTurnEnd?: (outcome: TurnOutcome) => void;
+}
+/**
+ * Build the CLI arguments.
+ *
+ * Every flag here is load-bearing and was verified against the binary rather
+ * than recalled:
+ *
+ * - `--print` with `--output-format stream-json` and `--input-format
+ *   stream-json` gives a bidirectional structured stream, which is what makes
+ *   this possible without a third-party adapter.
+ * - `--verbose` is REQUIRED for `stream-json` output; without it the CLI
+ *   refuses the combination.
+ * - `--include-partial-messages` is what produces the deltas that become
+ *   `agent_message_chunk` and `agent_thought_chunk`. Without it the reply
+ *   arrives in one lump and the whole point of a streaming transport is lost.
+ */
+export declare function claudeArgs(options: ClaudeDriverOptions): string[];
+/**
+ * Encode one user turn for `--input-format stream-json`.
+ *
+ * The CLI expects the same message envelope it emits, not a bare string.
+ */
+export declare function promptLine(text: string): string;
+/** ACP's five stop reasons. No sixth, and no "unknown". */
+export type StopReason = 'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled';
+export interface TurnOutcome {
+    /** Null when the turn did not finish cleanly -- see {@link turnOutcomeOf}. */
+    readonly stopReason: StopReason | null;
+    readonly isError: boolean;
+    /** The CLI's own reason string, kept even when it maps to nothing. */
+    readonly raw: string | null;
+}
+/**
+ * Read a turn's outcome from a `result` frame, or null if it is not one.
+ *
+ * `stopReason` comes back **null** when the CLI reported an error or a reason
+ * ACP has no literal for. That is deliberate and it is the whole reason this
+ * returns a structure rather than a string: ACP's five reasons all describe a
+ * turn that FINISHED, and none of them describes a crash. Answering `end_turn`
+ * for a failed turn would report a clean finish, and `refusal` would report a
+ * decision the agent never made. A caller that cannot name the stop reason
+ * should fail the request instead of inventing one.
+ */
+export declare function turnOutcomeOf(frame: unknown): TurnOutcome | null;
+/**
+ * The CLI's own session id, from its `init` frame.
+ *
+ * Needed for `--resume`, which is how ACP's `session/load` is served. Captured
+ * from the stream rather than invented, because the two ids are not the same
+ * thing: ACP's sessionId is ours to choose, the CLI's is the CLI's.
+ */
+export declare function cliSessionIdOf(frame: unknown): string | null;
+/**
+ * Turn framed output into ACP updates, separating what mapped from what failed
+ * to frame.
+ *
+ * Extracted from the driver so the wiring has a test that does not require
+ * spawning anything. The framer and the mapper are each covered thoroughly on
+ * their own, but "the framer's output reaches the mapper and both kinds of
+ * result reach the caller" is its own claim, and the only other place it could
+ * be checked is an opt-in live test that does not run in CI.
+ */
+export declare function updatesFromFrames(frames: readonly ReturnType<NdjsonFramer['push']>[number][], mapper: ClaudeToAcp): {
+    updates: AcpUpdate[];
+    problems: string[];
+};
+export declare class ClaudeDriver {
+    #private;
+    /** Names of credentials withheld from the child, available after start(). */
+    withheldCredentials: readonly string[];
+    /**
+     * The CLI's own session id, once it has announced one.
+     *
+     * Not the same thing as an ACP sessionId: that one is ours to choose, this
+     * one is the CLI's, and `--resume` wants the CLI's. Conflating them is how a
+     * resume silently starts a fresh conversation.
+     */
+    cliSessionId: string | null;
+    constructor(options: ClaudeDriverOptions, events?: ClaudeDriverEvents);
+    /** Frames the mapper could not place. */
+    get unmapped(): readonly unknown[];
+    get running(): boolean;
+    start(): void;
+    /** Send a user turn. */
+    prompt(text: string): void;
+    /** Close stdin, which tells the CLI no more turns are coming. */
+    endInput(): void;
+    /** Stop the child. */
+    kill(signal?: NodeJS.Signals): void;
+    /** Everything the CLI has written to stderr so far. */
+    get stderr(): string;
+}

package/dist/claude/driver.js

@@ -0,0 +1,266 @@
+/**
+ * Spawn the Claude CLI and turn its `stream-json` output into ACP updates.
+ *
+ * This is the piece that joins the others: {@link childEnv} builds the
+ * environment, {@link NdjsonFramer} splits the output, {@link ClaudeToAcp}
+ * translates it. Each of those is tested on its own, so what is left here is
+ * process handling -- which is the part that cannot be unit-tested, and
+ * therefore the part worth keeping small.
+ *
+ * The argv and the stdin encoding are exported as pure functions for exactly
+ * that reason. A driver whose flags could only be checked by spawning something
+ * would have its most mistake-prone surface covered by its least reliable test.
+ */
+import { spawn } from 'node:child_process';
+import { childEnv } from '../env.js';
+import { NdjsonFramer, encodeLine } from '../ndjson.js';
+import { ClaudeToAcp } from './to-acp.js';
+/**
+ * Build the CLI arguments.
+ *
+ * Every flag here is load-bearing and was verified against the binary rather
+ * than recalled:
+ *
+ * - `--print` with `--output-format stream-json` and `--input-format
+ *   stream-json` gives a bidirectional structured stream, which is what makes
+ *   this possible without a third-party adapter.
+ * - `--verbose` is REQUIRED for `stream-json` output; without it the CLI
+ *   refuses the combination.
+ * - `--include-partial-messages` is what produces the deltas that become
+ *   `agent_message_chunk` and `agent_thought_chunk`. Without it the reply
+ *   arrives in one lump and the whole point of a streaming transport is lost.
+ */
+export function claudeArgs(options) {
+    const args = [
+        '--print',
+        '--output-format',
+        'stream-json',
+        '--input-format',
+        'stream-json',
+        '--verbose',
+        '--include-partial-messages',
+    ];
+    if (options.resumeSessionId !== undefined)
+        args.push('--resume', options.resumeSessionId);
+    if (options.permissionMode !== undefined)
+        args.push('--permission-mode', options.permissionMode);
+    if (options.allowedTools !== undefined && options.allowedTools.length > 0) {
+        args.push('--allowed-tools', options.allowedTools.join(','));
+    }
+    if (options.disallowedTools !== undefined && options.disallowedTools.length > 0) {
+        args.push('--disallowed-tools', options.disallowedTools.join(','));
+    }
+    return args;
+}
+/**
+ * Encode one user turn for `--input-format stream-json`.
+ *
+ * The CLI expects the same message envelope it emits, not a bare string.
+ */
+export function promptLine(text) {
+    return encodeLine({
+        type: 'user',
+        message: { role: 'user', content: [{ type: 'text', text }] },
+    });
+}
+/**
+ * ACP stop reasons the CLI reports under the same names.
+ *
+ * Shared vocabulary for the common cases, which is luck rather than design, so
+ * it is written as a map instead of passed through. A pass-through would import
+ * every future CLI value into a closed ACP enum silently.
+ */
+const STOP_REASONS = {
+    end_turn: 'end_turn',
+    max_tokens: 'max_tokens',
+    max_turn_requests: 'max_turn_requests',
+    refusal: 'refusal',
+    cancelled: 'cancelled',
+    canceled: 'cancelled',
+};
+/**
+ * Read a turn's outcome from a `result` frame, or null if it is not one.
+ *
+ * `stopReason` comes back **null** when the CLI reported an error or a reason
+ * ACP has no literal for. That is deliberate and it is the whole reason this
+ * returns a structure rather than a string: ACP's five reasons all describe a
+ * turn that FINISHED, and none of them describes a crash. Answering `end_turn`
+ * for a failed turn would report a clean finish, and `refusal` would report a
+ * decision the agent never made. A caller that cannot name the stop reason
+ * should fail the request instead of inventing one.
+ */
+export function turnOutcomeOf(frame) {
+    if (!isObject(frame) || frame.type !== 'result')
+        return null;
+    const raw = typeof frame.stop_reason === 'string' ? frame.stop_reason : null;
+    const isError = frame.is_error === true || frame.subtype === 'error';
+    const mapped = raw === null ? undefined : STOP_REASONS[raw];
+    return { stopReason: isError || mapped === undefined ? null : mapped, isError, raw };
+}
+/**
+ * The CLI's own session id, from its `init` frame.
+ *
+ * Needed for `--resume`, which is how ACP's `session/load` is served. Captured
+ * from the stream rather than invented, because the two ids are not the same
+ * thing: ACP's sessionId is ours to choose, the CLI's is the CLI's.
+ */
+export function cliSessionIdOf(frame) {
+    if (!isObject(frame) || frame.type !== 'system' || frame.subtype !== 'init')
+        return null;
+    return typeof frame.session_id === 'string' ? frame.session_id : null;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Turn framed output into ACP updates, separating what mapped from what failed
+ * to frame.
+ *
+ * Extracted from the driver so the wiring has a test that does not require
+ * spawning anything. The framer and the mapper are each covered thoroughly on
+ * their own, but "the framer's output reaches the mapper and both kinds of
+ * result reach the caller" is its own claim, and the only other place it could
+ * be checked is an opt-in live test that does not run in CI.
+ */
+export function updatesFromFrames(frames, mapper) {
+    const updates = [];
+    const problems = [];
+    for (const frame of frames) {
+        if (!frame.ok) {
+            problems.push(frame.error.message);
+            continue;
+        }
+        updates.push(...mapper.frame(frame.value));
+    }
+    return { updates, problems };
+}
+export class ClaudeDriver {
+    #options;
+    #events;
+    #framer = new NdjsonFramer();
+    #mapper = new ClaudeToAcp();
+    #child = null;
+    #stderr = '';
+    #pendingOutcome = null;
+    /** Names of credentials withheld from the child, available after start(). */
+    withheldCredentials = [];
+    /**
+     * The CLI's own session id, once it has announced one.
+     *
+     * Not the same thing as an ACP sessionId: that one is ours to choose, this
+     * one is the CLI's, and `--resume` wants the CLI's. Conflating them is how a
+     * resume silently starts a fresh conversation.
+     */
+    cliSessionId = null;
+    constructor(options, events = {}) {
+        this.#options = options;
+        this.#events = events;
+    }
+    /** Frames the mapper could not place. */
+    get unmapped() {
+        return this.#mapper.unmapped;
+    }
+    get running() {
+        return this.#child !== null && this.#child.exitCode === null;
+    }
+    start() {
+        if (this.#child !== null)
+            throw new Error('driver already started');
+        const { env, withheld } = childEnv(this.#options.parentEnv ?? process.env, {
+            allow: [
+                // The CLI finds the user's own login through these, so they are allowed
+                // explicitly rather than inherited wholesale.
+                'CLAUDE_CONFIG_DIR',
+                'XDG_CONFIG_HOME',
+                ...(this.#options.allowEnv ?? []),
+            ],
+        });
+        this.withheldCredentials = withheld;
+        const child = spawn(this.#options.binary ?? 'claude', claudeArgs(this.#options), {
+            cwd: this.#options.cwd,
+            env,
+            // On Windows the binary is a `.cmd` shim, which cannot be executed
+            // directly. The shim re-entering whatever `node` is on PATH is a real
+            // hazard for a JS entry point; for the CLI itself the shim IS the
+            // documented entry, so the shell is the right way to reach it.
+            shell: process.platform === 'win32',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.#child = child;
+        child.stdout?.on('data', (chunk) => this.#onStdout(chunk));
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => this.#onStderr(chunk));
+        child.on('error', (cause) => {
+            // A spawn failure (ENOENT for a missing binary) arrives here and nowhere
+            // else. Reported as a protocol error so a caller cannot mistake "the CLI
+            // is not installed" for "the agent said nothing".
+            this.#events.onProtocolError?.(`failed to spawn: ${cause.message}`);
+        });
+        child.on('close', (code, signal) => {
+            // Flush first: a frame can be complete without its trailing newline, and
+            // the LAST frame of a turn is the `result` that carries the outcome.
+            this.#emit(this.#framer.end());
+            this.#events.onExit?.(code, signal);
+        });
+    }
+    /** Send a user turn. */
+    prompt(text) {
+        const stdin = this.#child?.stdin;
+        if (stdin === null || stdin === undefined) {
+            throw new Error('driver is not started, or its stdin has closed');
+        }
+        stdin.write(promptLine(text));
+    }
+    /** Close stdin, which tells the CLI no more turns are coming. */
+    endInput() {
+        this.#child?.stdin?.end();
+    }
+    /** Stop the child. */
+    kill(signal = 'SIGTERM') {
+        this.#child?.kill(signal);
+    }
+    /** Everything the CLI has written to stderr so far. */
+    get stderr() {
+        return this.#stderr;
+    }
+    #onStdout(chunk) {
+        this.#emit(this.#framer.push(chunk));
+    }
+    #emit(frames) {
+        // Raw frames are inspected for turn boundaries and the CLI's session id
+        // BEFORE mapping, because neither survives translation: the `result` frame
+        // becomes a usage_update and the `init` frame maps to nothing at all.
+        for (const frame of frames) {
+            if (!frame.ok)
+                continue;
+            const cliSessionId = cliSessionIdOf(frame.value);
+            if (cliSessionId !== null)
+                this.cliSessionId = cliSessionId;
+            const outcome = turnOutcomeOf(frame.value);
+            if (outcome !== null)
+                this.#pendingOutcome = outcome;
+        }
+        const { updates, problems } = updatesFromFrames(frames, this.#mapper);
+        for (const problem of problems)
+            this.#events.onProtocolError?.(problem);
+        for (const update of updates)
+            this.#events.onUpdate?.(update);
+        // Fired AFTER the updates, so a caller resolving a turn on this signal has
+        // already received everything the turn produced -- including the
+        // usage_update that the same `result` frame generates. Firing first would
+        // resolve session/prompt before its own usage arrived.
+        if (this.#pendingOutcome !== null) {
+            const outcome = this.#pendingOutcome;
+            this.#pendingOutcome = null;
+            this.#events.onTurnEnd?.(outcome);
+        }
+    }
+    #onStderr(chunk) {
+        this.#stderr += chunk;
+        // Line-wise, so a caller can match on a whole message rather than on
+        // whatever happened to land in one chunk.
+        const lines = chunk.split(/\r?\n/).filter((line) => line.trim().length > 0);
+        for (const line of lines)
+            this.#events.onStderr?.(line);
+    }
+}

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;