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

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# prism-acp (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Speak the [Agent Client Protocol](https://agentclientprotocol.com) to a
+coding-agent CLI **the user has already authenticated**.
+
+A client — an editor, a terminal UI, an orchestrator — gets structured state
+from an agent instead of guessing it from bytes on a pseudo-terminal: session
+state, streaming assistant output with thought content separable, tool calls
+with status, a plan that changes in place, mid-turn permission requests it can
+answer, token usage and cost.
+
+```sh
+npm install @particle-academy/prism-acp
+```
+
+**Zero runtime dependencies.** It drives the agent CLI already on the machine,
+so the user's existing subscription login is the authentication — there is no
+API key to supply and no adapter program to install.
+
+## Status
+
+Early, but a client can talk to it. `initialize`, `session/new`,
+`session/load`, `session/prompt` and `session/cancel` work over a pipe, driving
+the Claude CLI, proven end to end against an authenticated binary. The mapping
+is tested against **captured traffic** rather than a hand-written fixture.
+
+Missing: `session/set_mode`, the client-side `fs/*` and `terminal/*` calls an
+agent can make back, and the Codex driver. The surface will change.
+
+| piece | state |
+|---|---|
+| NDJSON framing | built |
+| child-environment construction | built |
+| JSON-RPC peer | built |
+| extension-field policy (`_meta`) | built |
+| Claude `stream-json` → ACP mapping | built |
+| Claude process driver | built |
+| ACP server surface + stdio | built |
+| `session/load` resume | built, and **proven** to remember the first turn |
+| `session/set_mode`, `fs/*`, `terminal/*` | not yet |
+| Codex driver (`app-server`) | not yet |
+
+**It maps 7 of ACP's 19 `session/update` kinds**, and that number is asserted by
+a test rather than described here, so raising it means moving it. The twelve it
+does not map each carry a measured reason — most notably the three plan kinds:
+the CLI emits **no plan frame at all**. A captured turn that built a three-item
+plan produced it entirely as `TaskCreate` / `TaskUpdate` tool calls, so ACP's
+plan kinds could only ever be *synthesised* here, and that is a decision to take
+deliberately rather than a mapping to add casually. Until then a plan is not
+lost — it is visible as the tool calls that built it.
+
+## Why drive a CLI rather than call an API
+
+Because of the authentication, and it is the whole reason this package exists.
+
+A provider **API** client needs an API key and bills per token. A user who pays
+for a subscription already has working credentials — in the CLI's own store, not
+in any protocol — and the way to use them is to run the CLI they belong to. So
+this package spawns the agent binary and translates, rather than reimplementing
+the agent against an HTTP API the user has no key for.
+
+That also keeps the credential out of this package entirely. It never reads one,
+never holds one, and never puts one on a wire.
+
+## The environment is built, not inherited
+
+`childEnv` constructs the spawned CLI's environment **allow-list-first**, and
+withholds credentials that would outrank the CLI's own login:
+
+```ts
+import { childEnv } from '@particle-academy/prism-acp';
+
+const { env, withheld } = childEnv(process.env);
+// withheld: ['ANTHROPIC_API_KEY']  -- names only; values are never read
+```
+
+This matters more than it looks. The SDK behind these CLIs resolves credentials
+from an **ordered** list, and `ANTHROPIC_API_KEY` is first — so an inherited key
+does not lose to the subscription, it **outranks** it:
+
+- a **valid** inherited key bills per token while the interface reports a
+  subscription session;
+- an **invalid** one makes every call fail `401 authentication_failed` and retry
+  to exhaustion. It does **not** fall back to the working login, because
+  precedence is resolved before validity is tested — so the 401 points at the
+  account, one layer below the actual cause.
+
+An allow-list rather than a deny-list, deliberately: a deny-list naming today's
+credential variables is one new provider variable away from being wrong again,
+in the direction that spends money silently. Names are compared
+case-insensitively, because Windows environment names are case-insensitive and
+`anthropic_api_key` reaches a child exactly as the uppercase spelling does.
+
+Nothing here mutates `process.env`. A workspace may hold an API key on purpose —
+other consumers beside this one legitimately bill per token — so the child's
+environment is constructed and the ambient one is left alone.
+
+## Framing is pinned, not inferred
+
+This package exists in three languages, and framing is where three
+implementations of one protocol disagree without anyone noticing. So:
+
+- a trailing `\r` is **stripped**, not left to each language's JSON parser to
+  tolerate;
+- `MAX_LINE_BYTES` is **1,000,000** in every port, because a cap that differs
+  per language means one implementation dies where another succeeds on the same
+  stream;
+- an oversized or unparseable line reports its **size, never its content** — a
+  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.
+
+## Using it
+
+```ts
+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),
+});
+```
+
+A client then speaks ACP on those pipes. Several sessions run at once, each with
+its own agent process, its own in-flight turn and its own updates — tagged with
+the session they belong to, because a room of agents shares one stream.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+MIT

package/dist/acp/agent.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The ACP agent surface: `initialize`, `session/new`, `session/load`,
+ * `session/prompt`, `session/cancel`.
+ *
+ * This is the half a client talks to. Underneath, each ACP session owns one
+ * driver, which owns one agent-CLI process.
+ *
+ * ## Several sessions, not one
+ *
+ * Sessions live in a map from the start, and that is a requirement rather than
+ * tidiness. The first consumer of this package needs a room holding SEVERAL
+ * agents at once, each its own process with its own in-flight turn and pending
+ * approvals. A design that assumed one session per server works perfectly for
+ * the first agent and has to be taken apart for the second, so it is not worth
+ * writing even as a step.
+ *
+ * ## Capabilities are claims, so they are reported honestly
+ *
+ * `initialize` declares what this agent can do, and a client plans around the
+ * answer. `loadSession` is reported true only because `session/load` is
+ * implemented on top of the CLI's own `--resume`; anything not implemented is
+ * reported absent rather than optimistically.
+ */
+import { JsonRpcPeer } from '../jsonrpc.js';
+import type { AcpUpdate } from '../claude/to-acp.js';
+import type { TurnOutcome } from '../claude/driver.js';
+/** The protocol version this agent speaks. */
+export declare const PROTOCOL_VERSION = 1;
+/** What a driver must offer the agent surface, whichever CLI it drives. */
+export interface AgentDriver {
+    start(): void;
+    prompt(text: string): void;
+    endInput(): void;
+    kill(signal?: NodeJS.Signals): void;
+    readonly cliSessionId: string | null;
+    readonly withheldCredentials: readonly string[];
+}
+export interface DriverEvents {
+    readonly onUpdate?: (update: AcpUpdate) => void;
+    readonly onTurnEnd?: (outcome: TurnOutcome) => void;
+    readonly onProtocolError?: (problem: string) => void;
+    readonly onStderr?: (line: string) => void;
+    readonly onExit?: (code: number | null, signal: NodeJS.Signals | null) => void;
+}
+/**
+ * Builds a driver for one session.
+ *
+ * Injected rather than hardcoded because this surface is meant to front more
+ * than one CLI -- Codex's `app-server` is the next one -- and because a server
+ * that could only be tested by spawning a real agent would have its session
+ * bookkeeping covered by nothing.
+ */
+export type DriverFactory = (options: {
+    readonly cwd: string;
+    readonly resumeSessionId?: string;
+}, events: DriverEvents) => AgentDriver;
+export interface AcpAgentOptions {
+    readonly driverFactory: DriverFactory;
+    readonly agentInfo?: {
+        readonly name: string;
+        readonly title?: string;
+        readonly version: string;
+    };
+    /** Generate a session id. Injected so tests can assert on stable ids. */
+    readonly newSessionId?: () => string;
+    readonly onStderr?: (sessionId: string, line: string) => void;
+    readonly onProtocolError?: (sessionId: string, problem: string) => void;
+}
+export declare class AcpAgent {
+    #private;
+    constructor(peer: JsonRpcPeer, options: AcpAgentOptions);
+    /** Session ids currently open. */
+    get sessionIds(): readonly string[];
+    /** Stop every session's process. */
+    closeAll(): void;
+}

package/dist/acp/agent.js

@@ -0,0 +1,264 @@
+/**
+ * The ACP agent surface: `initialize`, `session/new`, `session/load`,
+ * `session/prompt`, `session/cancel`.
+ *
+ * This is the half a client talks to. Underneath, each ACP session owns one
+ * driver, which owns one agent-CLI process.
+ *
+ * ## Several sessions, not one
+ *
+ * Sessions live in a map from the start, and that is a requirement rather than
+ * tidiness. The first consumer of this package needs a room holding SEVERAL
+ * agents at once, each its own process with its own in-flight turn and pending
+ * approvals. A design that assumed one session per server works perfectly for
+ * the first agent and has to be taken apart for the second, so it is not worth
+ * writing even as a step.
+ *
+ * ## Capabilities are claims, so they are reported honestly
+ *
+ * `initialize` declares what this agent can do, and a client plans around the
+ * answer. `loadSession` is reported true only because `session/load` is
+ * implemented on top of the CLI's own `--resume`; anything not implemented is
+ * reported absent rather than optimistically.
+ */
+import { RPC_INVALID_PARAMS, RPC_INTERNAL_ERROR, RpcError } from '../jsonrpc.js';
+/** The protocol version this agent speaks. */
+export const PROTOCOL_VERSION = 1;
+export class AcpAgent {
+    #peer;
+    #options;
+    #sessions = new Map();
+    #counter = 0;
+    constructor(peer, options) {
+        this.#peer = peer;
+        this.#options = options;
+        peer
+            .handle('initialize', (params) => this.#initialize(params))
+            .handle('authenticate', () => this.#authenticate())
+            .handle('session/new', (params) => this.#sessionNew(params))
+            .handle('session/load', (params) => this.#sessionLoad(params))
+            .handle('session/prompt', async (params) => await this.#sessionPrompt(params));
+        peer.onNotify('session/cancel', (params) => this.#sessionCancel(params));
+    }
+    /** Session ids currently open. */
+    get sessionIds() {
+        return [...this.#sessions.keys()];
+    }
+    /** Stop every session's process. */
+    closeAll() {
+        for (const session of this.#sessions.values())
+            session.driver.kill();
+        this.#sessions.clear();
+    }
+    #initialize(params) {
+        const requested = asObject(params)?.protocolVersion;
+        // The spec negotiates: an agent answers with the version it will speak. We
+        // speak 1, and say so whatever was asked, rather than echoing a number we
+        // do not implement back at the client.
+        void requested;
+        return {
+            protocolVersion: PROTOCOL_VERSION,
+            agentInfo: this.#options.agentInfo ?? {
+                name: '@particle-academy/prism-acp',
+                title: 'Prism ACP',
+                version: '0.1.0',
+            },
+            // Empty because this agent needs no authentication STEP: the CLI it
+            // drives is already authenticated by the user, and no credential ever
+            // travels in this protocol. Empty is the honest answer, not a placeholder.
+            authMethods: [],
+            agentCapabilities: {
+                // True, and PROVEN rather than wired. A live test stores a number in
+                // one turn, resumes, and asks for it back -- an assertion a fresh
+                // conversation cannot satisfy. That test exists because a wrong resume
+                // does not error: it starts a new conversation while the caller
+                // believes it continued one, so the flag being set proves nothing on
+                // its own. A capability reported optimistically is worse than one
+                // reported absent, because a client plans around the answer.
+                loadSession: true,
+                promptCapabilities: {
+                    // Text only, for now. Reported as false rather than omitted, because
+                    // for these two the client needs to know we will not accept them.
+                    image: false,
+                    audio: false,
+                    embeddedContext: false,
+                },
+            },
+        };
+    }
+    #authenticate() {
+        // Reachable only if a client ignores the empty authMethods above. Answering
+        // null rather than erroring keeps a confused client working, since there is
+        // genuinely nothing to authenticate.
+        return null;
+    }
+    #sessionNew(params) {
+        const cwd = requireAbsoluteCwd(params);
+        const id = this.#options.newSessionId?.() ?? `sess_${++this.#counter}_${Date.now()}`;
+        this.#open(id, cwd, undefined);
+        return { sessionId: id };
+    }
+    #sessionLoad(params) {
+        const object = asObject(params);
+        const cwd = requireAbsoluteCwd(params);
+        const sessionId = asString(object?.sessionId);
+        if (sessionId === undefined) {
+            throw new RpcError(RPC_INVALID_PARAMS, 'session/load requires a sessionId');
+        }
+        // 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`);
+        }
+        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
+        // -- claiming otherwise by returning early would be a silent lie about what
+        // a client is about to receive.
+        return {};
+    }
+    #open(id, cwd, resumeSessionId) {
+        const session = {
+            id,
+            cwd,
+            driver: undefined,
+            turn: null,
+            exited: false,
+        };
+        const driver = this.#options.driverFactory({ cwd, ...(resumeSessionId === undefined ? {} : { resumeSessionId }) }, {
+            onUpdate: (update) => {
+                this.#peer.notify('session/update', { sessionId: id, update });
+            },
+            onTurnEnd: (outcome) => {
+                const turn = session.turn;
+                session.turn = null;
+                turn?.settle(outcome);
+            },
+            onStderr: (line) => this.#options.onStderr?.(id, line),
+            onProtocolError: (problem) => this.#options.onProtocolError?.(id, problem),
+            onExit: (code) => {
+                session.exited = true;
+                // A turn still in flight when the process dies must be settled, or
+                // session/prompt never returns and the client waits forever on an
+                // agent that no longer exists.
+                const turn = session.turn;
+                session.turn = null;
+                turn?.settle({
+                    stopReason: null,
+                    isError: true,
+                    raw: `agent exited with code ${String(code)}`,
+                });
+            },
+        });
+        session.driver = driver;
+        this.#sessions.set(id, session);
+        driver.start();
+        return session;
+    }
+    async #sessionPrompt(params) {
+        const object = asObject(params);
+        const sessionId = asString(object?.sessionId);
+        if (sessionId === undefined) {
+            throw new RpcError(RPC_INVALID_PARAMS, 'session/prompt requires a sessionId');
+        }
+        const session = this.#sessions.get(sessionId);
+        if (session === undefined) {
+            throw new RpcError(RPC_INVALID_PARAMS, `no such session: ${sessionId}`);
+        }
+        if (session.exited) {
+            throw new RpcError(RPC_INTERNAL_ERROR, `session ${sessionId} has exited`);
+        }
+        if (session.turn !== null) {
+            // One turn at a time per session. Interleaving two would mix their
+            // updates on one stream with nothing to tell them apart.
+            throw new RpcError(RPC_INVALID_PARAMS, `session ${sessionId} already has a turn in flight`);
+        }
+        const text = promptText(object?.prompt);
+        if (text === undefined) {
+            throw new RpcError(RPC_INVALID_PARAMS, 'session/prompt requires a prompt of content blocks');
+        }
+        const outcome = await new Promise((resolve) => {
+            session.turn = { settle: resolve, cancelled: false };
+            try {
+                session.driver.prompt(text);
+            }
+            catch (cause) {
+                session.turn = null;
+                resolve({ stopReason: null, isError: true, raw: messageOf(cause) });
+            }
+        });
+        // ACP's five stop reasons all describe a turn that FINISHED. None of them
+        // describes a crash, so a failed turn is reported as an ERROR rather than
+        // given the nearest-looking reason: `end_turn` would claim a clean finish
+        // and `refusal` would claim a decision the agent never made.
+        if (outcome.stopReason === null) {
+            throw new RpcError(RPC_INTERNAL_ERROR, `turn did not complete${outcome.raw === null ? '' : `: ${outcome.raw}`}`);
+        }
+        return { stopReason: outcome.stopReason };
+    }
+    #sessionCancel(params) {
+        const sessionId = asString(asObject(params)?.sessionId);
+        if (sessionId === undefined)
+            return;
+        const session = this.#sessions.get(sessionId);
+        if (session === undefined)
+            return;
+        if (session.turn !== null) {
+            session.turn.cancelled = true;
+            const turn = session.turn;
+            session.turn = null;
+            // `cancelled` is a real ACP stop reason, so a cancelled turn RESOLVES
+            // rather than erroring. The client asked for this outcome; it is not a
+            // failure.
+            turn.settle({ stopReason: 'cancelled', isError: false, raw: 'cancelled' });
+        }
+        session.driver.kill();
+        session.exited = true;
+    }
+}
+/** ACP requires an absolute cwd, and says so with a MUST. */
+function requireAbsoluteCwd(params) {
+    const cwd = asString(asObject(params)?.cwd);
+    if (cwd === undefined) {
+        throw new RpcError(RPC_INVALID_PARAMS, 'cwd is required and MUST be an absolute path');
+    }
+    if (!isAbsolute(cwd)) {
+        // Enforced rather than resolved against our own cwd. The spec makes cwd the
+        // session's filesystem boundary, and silently anchoring a relative path to
+        // wherever this process happens to be running would put the agent
+        // somewhere the client never named.
+        throw new RpcError(RPC_INVALID_PARAMS, `cwd MUST be an absolute path: ${cwd}`);
+    }
+    return cwd;
+}
+/** Absolute on either platform, without importing node:path for one check. */
+function isAbsolute(path) {
+    return path.startsWith('/') || /^[A-Za-z]:[\\/]/.test(path);
+}
+/** Flatten ACP content blocks into the text a CLI prompt wants. */
+function promptText(prompt) {
+    if (!Array.isArray(prompt))
+        return undefined;
+    const parts = [];
+    for (const block of prompt) {
+        const object = asObject(block);
+        if (object?.type === 'text' && typeof object.text === 'string')
+            parts.push(object.text);
+    }
+    // An empty array is not a prompt, and neither is an array of blocks we cannot
+    // render. Refusing is better than sending an empty turn the agent will answer
+    // with something unrelated.
+    return parts.length === 0 ? undefined : parts.join('\n');
+}
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function messageOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/acp/stdio.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Serve the ACP agent over a pipe.
+ *
+ * ACP runs over stdio: the client spawns the agent and they exchange NDJSON on
+ * its stdin and stdout. This is the fifteen lines that join {@link NdjsonFramer},
+ * {@link JsonRpcPeer} and {@link AcpAgent} to a pair of streams.
+ *
+ * Streams are parameters rather than `process.stdin`/`process.stdout` reached
+ * for directly, so the whole surface can be driven end to end in a test over a
+ * pair of in-memory streams -- no spawning, no pipes, no timing.
+ */
+import type { Readable, Writable } from 'node:stream';
+import { JsonRpcPeer } from '../jsonrpc.js';
+import { AcpAgent, type AcpAgentOptions } from './agent.js';
+export interface ServeOptions extends AcpAgentOptions {
+    readonly input: Readable;
+    readonly output: Writable;
+    /** A frame that arrived but was not usable. */
+    readonly onProtocolError?: (sessionId: string, problem: string) => void;
+}
+export interface Served {
+    readonly agent: AcpAgent;
+    readonly peer: JsonRpcPeer;
+    /** Resolves when the input stream ends. */
+    readonly closed: Promise<void>;
+}
+export declare function serve(options: ServeOptions): Served;

package/dist/acp/stdio.js

@@ -0,0 +1,40 @@
+import { JsonRpcPeer } from '../jsonrpc.js';
+import { NdjsonFramer, encodeLine } from '../ndjson.js';
+import { AcpAgent } from './agent.js';
+export function serve(options) {
+    const framer = new NdjsonFramer();
+    const peer = new JsonRpcPeer({
+        send: (message) => {
+            options.output.write(encodeLine(message));
+        },
+        onProtocolError: (problem) => options.onProtocolError?.('', problem),
+    });
+    const agent = new AcpAgent(peer, options);
+    const closed = new Promise((resolve) => {
+        options.input.on('data', (chunk) => {
+            for (const frame of framer.push(chunk))
+                deliver(frame);
+        });
+        options.input.on('end', () => {
+            // Flush before closing: a client can send its last message without a
+            // trailing newline, and on this transport the last message is the one
+            // that matters.
+            for (const frame of framer.end())
+                deliver(frame);
+            // Every session's child process outlives this stream unless it is told
+            // otherwise. A server that exited without killing them would leave an
+            // agent running with nobody listening.
+            agent.closeAll();
+            peer.fail(new Error('client disconnected'));
+            resolve();
+        });
+    });
+    function deliver(frame) {
+        if (!frame.ok) {
+            options.onProtocolError?.('', frame.error.message);
+            return;
+        }
+        void peer.receive(frame.value);
+    }
+    return { agent, peer, closed };
+}