@arnilo/prism-acp-agent 0.2.8

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.2.8] - 2026-08-18
+
+### Added
+- First published cut with the 0.2.8 graph (plan 028 Task 10 / Task 18).
+
+## [0.2.7] - 2026-08-18
+
+### Added
+- Initial release: spawnable ACP agent entrypoint (plan 028 Task 10 / adoption F3). `prism-acp-agent` bin serves `createPrismAcpAgent` over stdio from a validated config file (`userId`, `cwd`, sqlite/memory session store, MCP allow-list, modes, config options, limits); `createSpawnableAgent`/`loadConfig`/`parseConfig`/`selectMcpServers` library surface; mock provider by default, real providers wire via the `provider` option.
+
+## [0.1.0] - 2026-08-09
+
+### Changed
+- Released with exact 0.1.0 graph.
+
+## [0.0.28] - 2026-08-08
+
+### Changed
+- Released with exact 0.0.28 graph.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prism contributors
+
+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

@@ -0,0 +1,69 @@
+# @arnilo/prism-acp-agent
+
+Spawnable ACP agent: a thin binary that serves [`createPrismAcpAgent`](https://github.com/ashiqrniloy/prism/tree/main/packages/ag-ui) over stdio from a config file.
+
+The binary is pure wiring — every protocol detail lives in `@arnilo/prism-ag-ui`. It wires the common seams for a single-workspace, single-local-user deployment:
+
+- `authorize` — single local user from config
+- `sessionFactory` — real Prism sessions backed by the [coding tools](https://github.com/ashiqrniloy/prism/tree/main/packages/coding-agent) (`shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`, `glob`, `delete`, `move`)
+- session store — in-memory or [SQLite](https://github.com/ashiqrniloy/prism/tree/main/packages/session-store-sqlite) (sessions, runs, checkpoints, leases)
+- MCP allow-list gate — http/sse servers must match a URL prefix; stdio servers require the `"stdio"` marker
+- modes and config options tables
+
+## Usage
+
+```sh
+npx prism-acp-agent [--config prism-acp-agent.json]
+```
+
+The agent speaks ACP over newline-delimited JSON on stdio. It serves until the client closes stdin.
+
+### Config file
+
+The config file is the trust boundary: unknown keys are rejected and invalid values fail closed with a clear error. Relative paths resolve against the config file's directory.
+
+```json
+{
+  "userId": "local",
+  "cwd": ".",
+  "sessionStore": { "type": "sqlite", "path": ".prism/sessions.db" },
+  "mcp": { "allow": ["https://mcp.example.com"] },
+  "modes": { "modes": [{ "id": "edit", "name": "Edit" }], "defaultModeId": "edit" },
+  "configOptions": [{ "type": "boolean", "id": "verbose", "name": "Verbose", "defaultValue": false }]
+}
+```
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `userId` | yes | Ownership user id for every session. |
+| `cwd` | yes | Workspace root the coding tools are bound to (must exist). |
+| `sessionStore` | no | `{ "type": "sqlite", "path" }` or `{ "type": "memory" }` (default). |
+| `mcp.allow` | no | URL prefixes allowed for http/sse MCP servers; the marker `"stdio"` allows stdio servers. |
+| `modes` | no | Mode table; `defaultModeId` must name a mode. |
+| `configOptions` | no | Boolean or select options with `defaultValue`. |
+| `limits` | no | AG-UI/ACP caps passthrough (see `AgUiLimitOptions`). |
+
+The served agent uses the mock provider by default (full lifecycle, no tokens). Wire a real provider programmatically:
+
+```ts
+import { createSpawnableAgent, loadConfig } from "@arnilo/prism-acp-agent";
+import { createOpenAIResponsesProvider } from "@arnilo/prism-provider-openai";
+
+const agent = createSpawnableAgent({
+  config: loadConfig("prism-acp-agent.json"),
+  provider: createOpenAIResponsesProvider({ apiKey: process.env.OPENAI_API_KEY }),
+});
+```
+
+## Library surface
+
+- `loadConfig(path)` / `parseConfig(text, baseDir)` — read and validate a config; throws `ConfigError` with a clear message.
+- `createSpawnableAgent({ config, provider? })` — build the ACP `AgentApp`.
+- `selectMcpServers(allow, servers)` — the allow-list gate (exported for reuse).
+
+## Development
+
+```sh
+npm run build --workspace @arnilo/prism-acp-agent
+npm test --workspace @arnilo/prism-acp-agent
+```

package/dist/bin/prism-acp-agent.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/prism-acp-agent.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Spawnable ACP agent entrypoint (0.2.8 Task 10 / adoption F3).
+ *
+ * Reads a config file (default `prism-acp-agent.json`, override with
+ * `--config <path>`), builds the ACP agent seams, and serves the protocol
+ * over stdio via the SDK's ndjson stream adapter. The process lives until
+ * the client closes stdin; EPIPE on stdout is a normal client disconnect.
+ */
+import { Readable, Writable } from "node:stream";
+import { parseArgs } from "node:util";
+import { ndJsonStream } from "@agentclientprotocol/sdk";
+import { createSpawnableAgent, loadConfig } from "../src/index.js";
+const { values } = parseArgs({
+    options: { config: { type: "string", short: "c" } },
+    allowPositionals: false,
+});
+let agent;
+try {
+    agent = createSpawnableAgent({ config: loadConfig(values.config ?? "prism-acp-agent.json") });
+}
+catch (error) {
+    console.error(`prism-acp-agent: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}
+const stream = ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));
+try {
+    const connection = await agent.connect(stream);
+    await connection?.closed;
+}
+catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    if (code !== "EPIPE")
+        console.error(`prism-acp-agent: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(code === "EPIPE" ? 0 : 1);
+}
+//# sourceMappingURL=prism-acp-agent.js.map

package/dist/src/config.d.ts

@@ -0,0 +1,37 @@
+import type { AgUiLimitOptions } from "@arnilo/prism-ag-ui";
+import type { AcpConfigOption, AcpSessionMode } from "@arnilo/prism-ag-ui/acp";
+export declare class ConfigError extends Error {
+    readonly code = "PRISM_ACP_AGENT_CONFIG";
+}
+export interface PrismAcpAgentMcpConfig {
+    /** URL prefixes allowed for http/sse MCP servers; the marker "stdio" allows stdio servers. */
+    readonly allow: readonly string[];
+}
+export interface PrismAcpAgentModesConfig {
+    readonly modes: readonly AcpSessionMode[];
+    readonly defaultModeId?: string;
+}
+export interface PrismAcpAgentConfigOptionsConfig {
+    readonly options: readonly AcpConfigOption[];
+}
+export interface PrismAcpAgentConfig {
+    /** Ownership user id for every ACP session (single-local-user authorization). */
+    readonly userId: string;
+    /** Workspace root the coding tools are bound to (resolved against the config dir). */
+    readonly cwd: string;
+    /** Durable store for Prism sessions/runs; default: in-memory. */
+    readonly sessionStore: {
+        readonly type: "sqlite";
+        readonly path: string;
+    } | {
+        readonly type: "memory";
+    };
+    readonly mcp?: PrismAcpAgentMcpConfig;
+    readonly modes?: PrismAcpAgentModesConfig;
+    readonly configOptions?: PrismAcpAgentConfigOptionsConfig;
+    /** AG-UI/ACP caps (see @arnilo/prism-ag-ui AgUiLimitOptions); optional passthrough. */
+    readonly limits?: AgUiLimitOptions;
+}
+export declare function loadConfig(path: string): PrismAcpAgentConfig;
+export declare function parseConfig(text: string, baseDir: string, source?: string): PrismAcpAgentConfig;
+export declare function validateConfig(raw: unknown, baseDir: string, source: string): PrismAcpAgentConfig;

package/dist/src/config.js

@@ -0,0 +1,164 @@
+/**
+ * Config parsing and validation for the spawnable ACP agent (0.2.8 Task 10).
+ *
+ * The config file is the trust boundary: every field is validated with a
+ * clear error, and unknown keys are rejected so a typo cannot silently
+ * disable a security-relevant option (fail closed). Paths in the config are
+ * resolved against the config file's directory, so the file is relocatable.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+export class ConfigError extends Error {
+    code = "PRISM_ACP_AGENT_CONFIG";
+}
+const KNOWN_KEYS = new Set(["userId", "cwd", "sessionStore", "mcp", "modes", "configOptions", "limits"]);
+const KNOWN_SESSION_STORE_KEYS = new Set(["type", "path"]);
+const KNOWN_MCP_KEYS = new Set(["allow"]);
+export function loadConfig(path) {
+    const resolved = resolve(path);
+    let text;
+    try {
+        text = readFileSync(resolved, "utf8");
+    }
+    catch (error) {
+        throw new ConfigError(`cannot read config file ${resolved}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseConfig(text, dirname(resolved), resolved);
+}
+export function parseConfig(text, baseDir, source = "config") {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError(`${source}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return validateConfig(raw, baseDir, source);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(source, message) {
+    throw new ConfigError(`${source}: ${message}`);
+}
+function requireString(value, source, field) {
+    if (typeof value !== "string" || value.length === 0)
+        fail(source, `${field} must be a non-empty string`);
+    return value;
+}
+function rejectUnknown(record, known, source) {
+    const unknown = Object.keys(record).filter((key) => !known.has(key));
+    if (unknown.length > 0)
+        fail(source, `unknown key(s): ${unknown.join(", ")}`);
+}
+export function validateConfig(raw, baseDir, source) {
+    if (!isRecord(raw))
+        fail(source, "config must be a JSON object");
+    rejectUnknown(raw, KNOWN_KEYS, source);
+    const userId = requireString(raw.userId, source, "userId");
+    const cwd = resolve(baseDir, requireString(raw.cwd, source, "cwd"));
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        fail(source, `cwd is not an existing directory: ${cwd}`);
+    let sessionStore = { type: "memory" };
+    if (raw.sessionStore !== undefined) {
+        if (!isRecord(raw.sessionStore))
+            fail(source, "sessionStore must be an object");
+        rejectUnknown(raw.sessionStore, KNOWN_SESSION_STORE_KEYS, `${source}.sessionStore`);
+        if (raw.sessionStore.type === "sqlite") {
+            const path = requireString(raw.sessionStore.path, `${source}.sessionStore`, "path");
+            sessionStore = { type: "sqlite", path: resolve(baseDir, path) };
+        }
+        else if (raw.sessionStore.type !== "memory") {
+            fail(source, `sessionStore.type must be "sqlite" or "memory", got ${JSON.stringify(raw.sessionStore.type)}`);
+        }
+    }
+    let mcp;
+    if (raw.mcp !== undefined) {
+        if (!isRecord(raw.mcp))
+            fail(source, "mcp must be an object");
+        rejectUnknown(raw.mcp, KNOWN_MCP_KEYS, `${source}.mcp`);
+        if (!Array.isArray(raw.mcp.allow) || raw.mcp.allow.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+            fail(source, "mcp.allow must be an array of non-empty strings");
+        }
+        mcp = { allow: raw.mcp.allow };
+    }
+    let modes;
+    if (raw.modes !== undefined) {
+        if (!isRecord(raw.modes))
+            fail(source, "modes must be an object");
+        const modeList = raw.modes.modes;
+        if (!Array.isArray(modeList) || modeList.length === 0)
+            fail(source, "modes.modes must be a non-empty array");
+        const ids = new Set();
+        for (const [index, mode] of modeList.entries()) {
+            if (!isRecord(mode))
+                fail(source, `modes.modes[${index}] must be an object`);
+            rejectUnknown(mode, new Set(["id", "name", "description"]), `${source}.modes.modes[${index}]`);
+            const id = requireString(mode.id, `${source}.modes.modes[${index}]`, "id");
+            requireString(mode.name, `${source}.modes.modes[${index}]`, "name");
+            if (ids.has(id))
+                fail(source, `duplicate mode id: ${id}`);
+            ids.add(id);
+        }
+        const defaultModeId = raw.modes.defaultModeId === undefined ? undefined : requireString(raw.modes.defaultModeId, `${source}.modes`, "defaultModeId");
+        if (defaultModeId !== undefined && !ids.has(defaultModeId))
+            fail(source, `defaultModeId '${defaultModeId}' is not a known mode`);
+        modes = {
+            modes: modeList,
+            ...(defaultModeId !== undefined ? { defaultModeId } : {}),
+        };
+    }
+    let configOptions;
+    if (raw.configOptions !== undefined) {
+        if (!isRecord(raw.configOptions))
+            fail(source, "configOptions must be an object");
+        const optionList = raw.configOptions.options;
+        if (!Array.isArray(optionList) || optionList.length === 0)
+            fail(source, "configOptions.options must be a non-empty array");
+        const ids = new Set();
+        for (const [index, option] of optionList.entries()) {
+            const at = `${source}.configOptions.options[${index}]`;
+            if (!isRecord(option))
+                fail(source, `${at} must be an object`);
+            rejectUnknown(option, new Set(["type", "id", "name", "description", "defaultValue", "options"]), at);
+            const type = option.type;
+            if (type !== "boolean" && type !== "select")
+                fail(source, `${at}.type must be "boolean" or "select"`);
+            const id = requireString(option.id, at, "id");
+            requireString(option.name, at, "name");
+            if (ids.has(id))
+                fail(source, `duplicate config option id: ${id}`);
+            ids.add(id);
+            if (type === "boolean" && typeof option.defaultValue !== "boolean")
+                fail(source, `${at}.defaultValue must be a boolean`);
+            if (type === "select") {
+                if (typeof option.defaultValue !== "string")
+                    fail(source, `${at}.defaultValue must be a string`);
+                if (!Array.isArray(option.options) || option.options.length === 0)
+                    fail(source, `${at}.options must be a non-empty array`);
+                for (const [choiceIndex, choice] of option.options.entries()) {
+                    if (!isRecord(choice) || typeof choice.value !== "string" || choice.value.length === 0) {
+                        fail(source, `${at}.options[${choiceIndex}].value must be a non-empty string`);
+                    }
+                }
+            }
+        }
+        configOptions = { options: optionList };
+    }
+    let limits;
+    if (raw.limits !== undefined) {
+        if (!isRecord(raw.limits))
+            fail(source, "limits must be an object");
+        limits = raw.limits;
+    }
+    return {
+        userId,
+        cwd,
+        sessionStore,
+        ...(mcp ? { mcp } : {}),
+        ...(modes ? { modes } : {}),
+        ...(configOptions ? { configOptions } : {}),
+        ...(limits ? { limits } : {}),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+import type { AgentApp, McpServer } from "@agentclientprotocol/sdk";
+import { type AIProvider } from "@arnilo/prism";
+import type { PrismAcpAgentConfig } from "./config.js";
+export type { PrismAcpAgentConfig } from "./config.js";
+export { ConfigError, loadConfig, parseConfig } from "./config.js";
+export interface CreateSpawnableAgentOptions {
+    readonly config: PrismAcpAgentConfig;
+    /** Model provider for the served Prism agent; default: mock (no tokens). */
+    readonly provider?: AIProvider;
+}
+/** MCP allow-list gate: http/sse servers must match an allow prefix; stdio needs the "stdio" marker. */
+export declare function selectMcpServers(allow: readonly string[], servers: readonly McpServer[]): boolean;
+export declare function createSpawnableAgent(options: CreateSpawnableAgentOptions): AgentApp;

package/dist/src/index.js

@@ -0,0 +1,70 @@
+/**
+ * Spawnable ACP agent (0.2.8 Task 10 / adoption F3).
+ *
+ * Thin wiring only: config parsing (src/config.ts) plus this seam builder.
+ * Every protocol detail lives in `createPrismAcpAgent` (@arnilo/prism-ag-ui);
+ * this package never re-implements ACP. The default provider is the mock
+ * provider so the lifecycle works out of the box; wire a real `AIProvider`
+ * (e.g. @arnilo/prism-provider-openai) for actual generation.
+ */
+import { randomUUID } from "node:crypto";
+import { createAgent, createAgentRunLifecycle, createMemoryCheckpointStore, createMemorySessionStore, createMockProvider, createToolRegistry, } from "@arnilo/prism";
+import { createPrismAcpAgent } from "@arnilo/prism-ag-ui/acp";
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+export { ConfigError, loadConfig, parseConfig } from "./config.js";
+/** MCP allow-list gate: http/sse servers must match an allow prefix; stdio needs the "stdio" marker. */
+export function selectMcpServers(allow, servers) {
+    return servers.every((server) => {
+        if ("type" in server) {
+            // acp transport is UNSTABLE v2 surface — never bridged.
+            return server.type !== "acp" && allow.some((entry) => server.url.startsWith(entry));
+        }
+        return allow.includes("stdio");
+    });
+}
+export function createSpawnableAgent(options) {
+    const { config } = options;
+    const ownership = { userId: config.userId };
+    let store;
+    let checkpoints;
+    if (config.sessionStore.type === "sqlite") {
+        const persistence = createSqlitePersistence({ filename: config.sessionStore.path });
+        store = persistence;
+        checkpoints = persistence.checkpoints;
+    }
+    else {
+        store = createMemorySessionStore();
+        checkpoints = createMemoryCheckpointStore();
+    }
+    const tools = createToolRegistry(createCodingTools(config.cwd));
+    const prismAgent = createAgent({
+        id: "prism-acp-agent",
+        model: { provider: "mock", model: "mock" },
+        provider: options.provider ?? createMockProvider(),
+        store,
+        tools,
+        ownership,
+        runState: { checkpoints, definitionRevision: "1", interruptBeforeTool: true },
+    });
+    return createPrismAcpAgent({
+        name: "Prism ACP Agent",
+        authorize: () => ({ ownership }),
+        sessionFactory: async (input) => ({
+            session: prismAgent.createSession({ id: input.sessionId ?? randomUUID() }),
+            agentId: "prism-acp-agent",
+            tools,
+        }),
+        lifecycle: createAgentRunLifecycle({
+            checkpoints,
+            resolveAgent: () => ({ agent: prismAgent, definitionRevision: "1" }),
+        }),
+        mcp: config.mcp ? { transports: ["http", "sse"], select: ({ servers }) => selectMcpServers(config.mcp.allow, servers) } : undefined,
+        modes: config.modes
+            ? { modes: config.modes.modes, ...(config.modes.defaultModeId !== undefined ? { defaultModeId: config.modes.defaultModeId } : {}) }
+            : undefined,
+        configOptions: config.configOptions ? { options: config.configOptions.options } : undefined,
+        limits: config.limits,
+    });
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@arnilo/prism-acp-agent",
+  "version": "0.2.8",
+  "description": "Spawnable ACP agent: serves createPrismAcpAgent over stdio from a config file.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "prism-acp-agent": "dist/bin/prism-acp-agent.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/__tests__",
+    "!dist/**/*.map",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/with-build-lock.mjs tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/with-build-lock.mjs node --test dist/src/__tests__/*.test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.3.0",
+    "@arnilo/prism-coding-agent": "0.2.8",
+    "@arnilo/prism-session-store-sqlite": "0.2.8"
+  },
+  "peerDependencies": {
+    "@arnilo/prism": "0.2.8",
+    "@arnilo/prism-ag-ui": "0.2.8"
+  },
+  "devDependencies": {
+    "@arnilo/prism": "file:../..",
+    "@arnilo/prism-ag-ui": "file:../ag-ui"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashiqrniloy/prism.git",
+    "directory": "packages/acp-agent"
+  },
+  "bugs": {
+    "url": "https://github.com/ashiqrniloy/prism/issues"
+  },
+  "homepage": "https://github.com/ashiqrniloy/prism/tree/main/packages/acp-agent#readme",
+  "keywords": [
+    "prism",
+    "acp",
+    "agent",
+    "stdio",
+    "mcp"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}