sakuracode 0.1.0 → 0.2.0

package/README.md

@@ -105,6 +105,7 @@ sakuracode exec --json "list the TODOs" | jq .   # events as JSON lines
 echo "explain this error" | sakuracode exec -    # prompt from stdin
 sakuracode sessions                 # list sessions
 sakuracode providers                # providers and whether their key is set (never the key)
+sakuracode acp                      # serve the Agent Client Protocol on stdin/stdout (see below)
 ```
 
 ### Options
@@ -135,6 +136,7 @@ sakuracode providers                # providers and whether their key is set (ne
 |---|---|---|
 | Enter | send | **steer**: delivered before the agent's next model request |
 | Tab | complete a slash command | **queue**: handled when the agent would stop |
+| Shift-Tab | switch the review mode: auto, strict, read-only (`full-access` only with `/permissions`) | applied when the run ends |
 | Esc | close the popup | **cancel** the run |
 | Ctrl-C | clear the prompt; twice on an empty prompt leaves | cancel the run |
 | Ctrl-D | leave (empty prompt) | |
@@ -179,6 +181,23 @@ Messages typed during a run show above the prompt as "steering" or "queued" unti
 
 None of them restricts the working directory: the review plugin runs with `directoryRules: false`, so a path outside the launch directory is not a reason to refuse. Writes, command expansions, credentials and catastrophic patterns are still checked by the hard rules and the reviewer model.
 
+## Use with T3 Code and other ACP clients
+
+`sakuracode acp` speaks the [Agent Client Protocol](https://agentclientprotocol.com) (ACP, version 1) on stdin and stdout, so an ACP client can run it as its coding agent. Stdout carries only protocol messages; logs go to stderr (`SAKURACODE_ACP_LOG=off|error|warn|info|debug`, default `warn`).
+
+**T3 Code:** Settings, Providers, Add provider, Show more, **Local ACP command**. Fill in:
+
+| Field | Value |
+|---|---|
+| Name | `Sakura Code` (any name) |
+| Executable | `sakuracode` (a full path works too) |
+| Arguments | one row, exactly `acp` |
+| Environment | your key, for example `DEEPSEEK_API_KEY` or `OPENCODE_API_KEY` (a GUI app often does not see the variables of your shell) |
+
+Then start a chat with that provider. To check it by hand, run `sakuracode acp` and paste `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}` followed by Enter: one JSON line comes back.
+
+What works now: chat with streamed replies and reasoning, cancelling a running turn, several chats at once (one prompt at a time in each). New chats use the review mode `auto` (every call is reviewed); `--permissions strict` or `read-only` after `acp` changes it, and `full-access` only runs when you ask for it on that command line. Not yet: tool call cards, images, attached files, model and mode pickers, resuming a chat, MCP servers from the client. See `docs/acp-design.md`.
+
 ## Config
 
 `~/.sakura/config.toml` (set `SAKURA_HOME` to use another directory; sessions are stored in `sessions/` beside it). Precedence: defaults < file < profile < environment (`SAKURA_PROVIDER`, `SAKURA_MODEL`) < flags.

package/README.zh-CN.md

@@ -105,6 +105,7 @@ sakuracode exec --json "列出 TODO" | jq .        # 事件以 JSON 行输出
 echo "解释这个报错" | sakuracode exec -          # 从 stdin 读取提示
 sakuracode sessions                 # 列出会话
 sakuracode providers                # 服务商以及它们的密钥是否已设置（不显示密钥）
+sakuracode acp                      # 在标准输入输出上提供 Agent Client Protocol（见下文）
 ```
 
 ### 选项
@@ -135,6 +136,7 @@ sakuracode providers                # 服务商以及它们的密钥是否已设
 |---|---|---|
 | Enter | 发送 | **引导**：在 Agent 的下一个模型请求之前送达 |
 | Tab | 补全斜杠命令 | **排队**：Agent 要停下时处理 |
+| Shift-Tab | 切换审查模式：auto、strict、read-only（`full-access` 只能用 `/permissions` 设置） | 运行结束后生效 |
 | Esc | 关闭弹出列表 | **取消**这次运行 |
 | Ctrl-C | 清空提示；在空提示上按两次退出 | 取消这次运行 |
 | Ctrl-D | 退出（提示为空时） | |
@@ -179,6 +181,23 @@ sakuracode providers                # 服务商以及它们的密钥是否已设
 
 它们都不限制工作目录：审核插件以 `directoryRules: false` 运行，所以启动目录之外的路径本身不是拒绝的理由。写入、命令展开、凭据和灾难性的模式仍然由硬规则和审核模型检查。
 
+## 在 T3 Code 和其他 ACP 客户端里使用
+
+`sakuracode acp` 在标准输入和标准输出上说 [Agent Client Protocol](https://agentclientprotocol.com)（ACP，版本 1），所以 ACP 客户端可以把它当作自己的编程 Agent 来运行。标准输出只有协议消息；日志写到标准错误（`SAKURACODE_ACP_LOG=off|error|warn|info|debug`，默认 `warn`）。
+
+**T3 Code：** Settings → Providers → Add provider → Show more → **Local ACP command**，填写：
+
+| 字段 | 内容 |
+|---|---|
+| Name | `Sakura Code`（随意） |
+| Executable | `sakuracode`（也可以写完整路径） |
+| Arguments | 一行，就是 `acp` |
+| Environment | 你的密钥，例如 `DEEPSEEK_API_KEY` 或 `OPENCODE_API_KEY`（图形界面应用通常看不到 shell 里的环境变量） |
+
+然后用这个 provider 开一个对话。想手动验证：运行 `sakuracode acp`，粘贴 `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}` 再按回车，会返回一行 JSON。
+
+现在可用：对话（回复和推理流式显示）、取消正在运行的一轮、同时开多个对话（每个对话一次只处理一条消息）。新对话使用审核模式 `auto`（每次调用都审核）；在 `acp` 后加 `--permissions strict` 或 `read-only` 可以更改，`full-access` 只有在这条命令行上明确要求时才会生效。暂时没有：工具调用卡片、图片、附件、模型和模式选择器、恢复对话、客户端传来的 MCP 服务器。详见 `docs/acp-design.md`。
+
 ## 配置
 
 `~/.sakura/config.toml`（设置 `SAKURA_HOME` 可以改用别的目录；会话保存在它旁边的 `sessions/` 里）。优先级：默认值 < 文件 < 方案 < 环境变量（`SAKURA_PROVIDER`、`SAKURA_MODEL`）< 命令行选项。

package/dist/THIRD_PARTY_NOTICES.md

@@ -10,4 +10,6 @@ Sakura borrows from a few other projects. Where code or text was copied or adapt
 
 Dependency: [`quickjs-emscripten`](https://github.com/justjake/quickjs-emscripten) (MIT) runs the code-mode scripts. It is installed from npm, not copied.
 
+Dependency: [`@agentclientprotocol/sdk`](https://github.com/agentclientprotocol/typescript-sdk) (Apache-2.0, Zed Industries) carries the Agent Client Protocol for `sakuracode acp`, and [`zod`](https://github.com/colinhacks/zod) (MIT) is its required peer dependency. Both are installed from npm, not copied.
+
 Licence texts: `licenses/pi-mono-MIT.txt`, `licenses/gitleaks-MIT.txt`, `licenses/codex-Apache-2.0.txt`.

package/dist/code/src/acp/agent.js

@@ -0,0 +1,70 @@
+// The ACP agent: routes the protocol methods to the session registry and the pure mappers. It knows nothing of JSON-RPC framing
+// (that is `connection.ts`) and nothing of the model.
+import { isAbsolute } from "node:path";
+import { initializeResult, readClientFeatures } from "./capabilities.js";
+import { promptText } from "./content.js";
+import { createUpdateMapper } from "./events-to-updates.js";
+import { outcomeOf } from "./stop-reasons.js";
+import { AcpError, ErrorCode } from "./types.js";
+import { randomUUID } from "node:crypto";
+export function createAcpAgent(deps) {
+    const { sessions, log } = deps;
+    let features = readClientFeatures(undefined);
+    // every handler is wrapped once: a failure becomes an error answer with a code, never a crash, and never reaches another session
+    const guard = (method, handler) => {
+        return async (...args) => {
+            try {
+                return await handler(...args);
+            }
+            catch (error) {
+                if (error instanceof AcpError)
+                    throw error;
+                log.error(`${method} failed: ${error instanceof Error ? error.message : String(error)}`);
+                throw new AcpError(ErrorCode.internalError, "The agent hit an internal error. See its log on stderr.");
+            }
+        };
+    };
+    return {
+        features: () => features,
+        initialize: guard("initialize", async (params) => {
+            features = readClientFeatures(params.clientCapabilities);
+            return initializeResult(params, deps.identity);
+        }),
+        // no authentication is needed yet (keys come from the environment), so there is nothing to do and nothing can fail
+        authenticate: guard("authenticate", async () => ({})),
+        newSession: guard("session/new", async (params) => {
+            if (typeof params.cwd !== "string" || !isAbsolute(params.cwd))
+                throw new AcpError(ErrorCode.invalidParams, "cwd must be an absolute path", { cwd: typeof params.cwd === "string" ? params.cwd : undefined });
+            if (Array.isArray(params.mcpServers) && params.mcpServers.length > 0)
+                log.debug("session/new: mcpServers are not used yet", { count: params.mcpServers.length });
+            return { sessionId: await sessions.create(params.cwd) };
+        }),
+        prompt: guard("session/prompt", async (params, channel, signal) => {
+            const text = promptText(params.prompt);
+            if (!sessions.has(params.sessionId))
+                throw new AcpError(ErrorCode.sessionNotFound, `Unknown session ${params.sessionId}`, { sessionId: params.sessionId });
+            if (text === "")
+                return { stopReason: "end_turn" };
+            const mapper = createUpdateMapper();
+            const cancel = () => sessions.cancel(params.sessionId);
+            signal?.addEventListener("abort", cancel, { once: true });
+            let turn;
+            try {
+                turn = await sessions.run(params.sessionId, text, async (event) => {
+                    for (const update of mapper.push(event))
+                        await channel.update(params.sessionId, update);
+                });
+            }
+            finally {
+                signal?.removeEventListener("abort", cancel);
+            }
+            const outcome = outcomeOf(turn.result, turn.cancelled);
+            if (outcome.notice)
+                await channel.update(params.sessionId, { sessionUpdate: "agent_message_chunk", content: { type: "text", text: outcome.notice }, messageId: randomUUID() });
+            return outcome.result;
+        }),
+        cancel: guard("session/cancel", async (params) => {
+            sessions.cancel(params.sessionId);
+        }),
+    };
+}

package/dist/code/src/acp/auth.js

@@ -0,0 +1,19 @@
+import { chooseProvider, listProviders, ProviderSetupError } from "../providers.js";
+import { AcpError, ErrorCode } from "./types.js";
+/** The provider to use, or the `auth_required` error with an instruction when there is none or its key is missing. */
+export function providerFor(settings, env) {
+    let name;
+    try {
+        name = chooseProvider(settings, env);
+    }
+    catch (error) {
+        if (!(error instanceof ProviderSetupError))
+            throw error;
+        throw new AcpError(ErrorCode.authRequired, `${error.message}. Set the key in the environment of this agent (in T3 Code: the environment overrides of the ACP command), then start a new chat.`);
+    }
+    const entry = listProviders(settings, env).find((item) => item.name === name);
+    if (entry && !entry.keyPresent) {
+        throw new AcpError(ErrorCode.authRequired, `No API key for provider "${name}". Set ${entry.definition.keyEnv} in the environment of this agent (in T3 Code: the environment overrides of the ACP command), then start a new chat.`, { provider: name, keyEnv: entry.definition.keyEnv });
+    }
+    return name;
+}

package/dist/code/src/acp/capabilities.js

@@ -0,0 +1,22 @@
+const flag = (value) => value === true;
+const record = (value) => (typeof value === "object" && value !== null && !Array.isArray(value) ? value : {});
+export function readClientFeatures(capabilities) {
+    const root = record(capabilities);
+    const fs = record(root.fs);
+    return Object.freeze({ readTextFile: flag(fs.readTextFile), writeTextFile: flag(fs.writeTextFile), terminal: flag(root.terminal) });
+}
+export const ACP_PROTOCOL_VERSION = 1;
+/** The `initialize` answer. The agent speaks ACP version 1 whatever the client asks for; the client then decides whether to continue. */
+export function initializeResult(_request, identity) {
+    return {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        agentCapabilities: {
+            loadSession: false,
+            promptCapabilities: { image: false, audio: false, embeddedContext: false },
+            mcpCapabilities: { http: false, sse: false },
+        },
+        // Keys come from the environment of the agent process; there is nothing to log in to yet.
+        authMethods: [],
+        agentInfo: identity,
+    };
+}

package/dist/code/src/acp/connection.js

@@ -0,0 +1,32 @@
+// The JSON-RPC link: the only file that imports the ACP SDK. It turns the SDK's handler calls into the plain calls of
+// `AgentHandlers`, turns `AcpError` into JSON-RPC errors, and gives the agent a `ClientChannel` to send updates through. The SDK
+// checks every message in both directions against the protocol schema.
+import { agent, methods, ndJsonStream, RequestError } from "@agentclientprotocol/sdk";
+import { AcpError } from "./types.js";
+/** A handler's `AcpError` must reach the client as the JSON-RPC error it describes. */
+async function answering(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof AcpError)
+            throw new RequestError(error.code, error.message, error.data);
+        throw error;
+    }
+}
+export function connect(handlers, streams, log) {
+    const app = agent({ name: "sakuracode" })
+        .onRequest(methods.agent.initialize, ({ params }) => answering(() => handlers.initialize(params)))
+        .onRequest(methods.agent.authenticate, ({ params }) => answering(() => handlers.authenticate(params)))
+        .onRequest(methods.agent.session.new, ({ params }) => answering(() => handlers.newSession(params)))
+        .onRequest(methods.agent.session.prompt, async ({ params, client, signal }) => {
+        const channel = {
+            update: (sessionId, update) => client.notify(methods.client.session.update, { sessionId, update }),
+        };
+        return answering(() => handlers.prompt(params, channel, signal));
+    })
+        .onNotification(methods.agent.session.cancel, ({ params }) => handlers.cancel(params));
+    const connection = app.connect(ndJsonStream(streams.output, streams.input));
+    void connection.closed.catch((error) => log.warn(`connection closed with an error: ${error instanceof Error ? error.message : String(error)}`));
+    return { closed: connection.closed.catch(() => undefined) };
+}

package/dist/code/src/acp/content.js

@@ -0,0 +1,29 @@
+function fileLinkPath(uri) {
+    if (!uri.startsWith("file://"))
+        return undefined;
+    try {
+        return decodeURIComponent(new URL(uri).pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Text blocks are joined with a blank line. A link to a file becomes an `@path` mention, which the agent reads like one typed
+ * in the terminal; any other link stays a Markdown link. Blocks the agent does not read yet (images, audio, embedded
+ * resources) leave a one-line note so the model knows something was there. An empty result means there is nothing to run.
+ */
+export function promptText(blocks) {
+    const parts = [];
+    for (const block of blocks) {
+        if (block.type === "text" && typeof block.text === "string")
+            parts.push(block.text);
+        else if (block.type === "resource_link" && typeof block.uri === "string") {
+            const path = fileLinkPath(block.uri);
+            parts.push(path ? `@${path}` : `[${typeof block.name === "string" ? block.name : block.uri}](${block.uri})`);
+        }
+        else
+            parts.push(`[a ${String(block.type)} attachment was sent but is not supported yet]`);
+    }
+    return parts.join("\n\n").trim();
+}

package/dist/code/src/acp/events-to-updates.js

@@ -0,0 +1,37 @@
+// Framework events to ACP updates, as a pure state machine. It decides message ids: ACP groups chunks by `messageId`, and cannot
+// take chunks back, so a reply that is sent again after a dropped connection gets a new id and the text already sent stays.
+import { randomUUID } from "node:crypto";
+export function createUpdateMapper(newId = randomUUID) {
+    // one id for the text and one for the reasoning of the current reply; both start again after the reply ends or is voided
+    let messageId;
+    let thoughtId;
+    const startAgain = () => {
+        messageId = undefined;
+        thoughtId = undefined;
+    };
+    return {
+        push(event) {
+            switch (event.type) {
+                case "message_update": {
+                    const delta = event.delta;
+                    if (delta.type !== "text" || delta.text === "")
+                        return [];
+                    messageId ??= newId();
+                    return [{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: delta.text }, messageId }];
+                }
+                case "reasoning_update": {
+                    if (typeof event.delta !== "string" || event.delta === "")
+                        return [];
+                    thoughtId ??= newId();
+                    return [{ sessionUpdate: "agent_thought_chunk", content: { type: "text", text: event.delta }, messageId: thoughtId }];
+                }
+                case "message_reset":
+                case "message_end":
+                    startAgain();
+                    return [];
+                default:
+                    return [];
+            }
+        },
+    };
+}

package/dist/code/src/acp/log.js

@@ -0,0 +1,22 @@
+const ORDER = { error: 0, warn: 1, info: 2, debug: 3 };
+/** `SAKURACODE_ACP_LOG` is off, error, warn (default), info or debug. */
+export function logLevelFromEnv(value) {
+    const level = value?.trim().toLowerCase();
+    if (level === "off" || level === "error" || level === "warn" || level === "info" || level === "debug")
+        return level;
+    return "warn";
+}
+export function createLogger(write, level, module = "acp") {
+    const emit = (at, message, fields) => {
+        if (level === "off" || ORDER[at] > ORDER[level])
+            return;
+        write(`${JSON.stringify({ ts: new Date().toISOString(), level: at, module, message, ...fields })}\n`);
+    };
+    return {
+        error: (message, fields) => emit("error", message, fields),
+        warn: (message, fields) => emit("warn", message, fields),
+        info: (message, fields) => emit("info", message, fields),
+        debug: (message, fields) => emit("debug", message, fields),
+        child: (name) => createLogger(write, level, name),
+    };
+}

package/dist/code/src/acp/serve.js

@@ -0,0 +1,59 @@
+// Starting the agent: wires the registry, the agent and the connection together and handles the process lifecycle.
+import { Readable, Writable } from "node:stream";
+import { openAgentSession } from "../agent-session.js";
+import { createAcpAgent } from "./agent.js";
+import { connect } from "./connection.js";
+import { createLogger, logLevelFromEnv } from "./log.js";
+import { createSessions } from "./sessions.js";
+/** Serves one client until it closes its end (or `stop` resolves), then cancels running turns and closes every session. Returns the exit code. */
+export async function runAcp(options) {
+    const sessions = createSessions({
+        settings: options.settings,
+        store: options.store,
+        env: options.env,
+        open: options.open ?? openAgentSession,
+        permissions: options.permissions,
+        clients: options.clients,
+        log: options.log.child("sessions"),
+    });
+    const agent = createAcpAgent({ sessions, identity: { name: "sakuracode", title: "Sakura Code", version: options.version }, log: options.log.child("agent") });
+    const connection = connect(agent, options.streams, options.log.child("connection"));
+    options.log.info("serving", { version: options.version, permissions: options.permissions });
+    await Promise.race([connection.closed, options.stop ?? new Promise(() => undefined)]);
+    await sessions.closeAll();
+    options.log.info("stopped");
+    return 0;
+}
+/**
+ * The real process: stdin and stdout carry the protocol and nothing else. Anything the program or a library prints with
+ * `console` goes to stderr instead, so a stray line can never corrupt the stream. The first SIGINT or SIGTERM ends the run
+ * cleanly; a second one exits at once.
+ */
+export async function serveProcess(io, options) {
+    const writeLog = (line) => void io.stderr.write(line);
+    for (const name of ["log", "info", "debug", "warn", "error"])
+        console[name] = (...args) => void io.stderr.write(`${args.map(String).join(" ")}\n`);
+    const log = createLogger(writeLog, logLevelFromEnv(io.env.SAKURACODE_ACP_LOG));
+    let stop;
+    const stopped = new Promise((resolve) => (stop = resolve));
+    let signals = 0;
+    const onSignal = () => {
+        signals += 1;
+        if (signals > 1)
+            process.exit(1);
+        stop();
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    try {
+        const streams = {
+            input: Readable.toWeb(io.stdin),
+            output: Writable.toWeb(io.stdout),
+        };
+        return await runAcp({ ...options, env: io.env, streams, log, stop: stopped });
+    }
+    finally {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+}

package/dist/code/src/acp/sessions.js

@@ -0,0 +1,81 @@
+import { providerFor } from "./auth.js";
+import { titleFromPrompt } from "../session-store.js";
+import { safeErrorText } from "./stop-reasons.js";
+import { AcpError, ErrorCode } from "./types.js";
+export function createSessions(deps) {
+    const entries = new Map();
+    const find = (sessionId) => {
+        const entry = entries.get(sessionId);
+        if (!entry)
+            throw new AcpError(ErrorCode.sessionNotFound, `Unknown session ${sessionId}`, { sessionId });
+        return entry;
+    };
+    return {
+        async create(cwd) {
+            const provider = deps.clients ? "scripted" : providerFor(deps.settings, deps.env);
+            const meta = await deps.store.create({ cwd, provider, model: deps.settings.model ?? "" });
+            const session = await deps.open({
+                settings: deps.settings,
+                provider,
+                model: deps.settings.model,
+                sessionId: meta.id,
+                sessionFile: deps.store.sessionFile(meta.id),
+                cwd,
+                permissions: deps.permissions,
+                redaction: deps.settings.redaction,
+                thinking: deps.settings.thinking,
+                maxTokens: deps.settings.maxTokens,
+                env: deps.env,
+                onRetry: (message) => deps.log.warn(`provider retry: ${safeErrorText(message)}`, { session: meta.id }),
+                ...(deps.clients ? { clients: deps.clients } : {}),
+            });
+            await deps.store.update(meta.id, { provider, model: session.model });
+            entries.set(meta.id, { session, titled: false, running: undefined });
+            deps.log.info("session created", { session: meta.id, provider, permissions: deps.permissions });
+            return meta.id;
+        },
+        has: (sessionId) => entries.has(sessionId),
+        async run(sessionId, input, onEvent) {
+            const entry = find(sessionId);
+            // checked and set before the first await: two prompts cannot both pass
+            if (entry.running)
+                throw new AcpError(ErrorCode.busy, "A prompt is already running in this session. Wait for it to end or cancel it.", { sessionId });
+            const handle = entry.session.agent.run(input);
+            const running = {
+                cancelled: false,
+                cancel() {
+                    running.cancelled = true;
+                    handle.cancel();
+                },
+            };
+            entry.running = running;
+            try {
+                if (!entry.titled) {
+                    entry.titled = true;
+                    await deps.store.update(sessionId, { title: titleFromPrompt(input) });
+                }
+                for await (const event of handle.events)
+                    await onEvent(event);
+                return { result: await handle.result, cancelled: running.cancelled };
+            }
+            catch (error) {
+                handle.cancel();
+                throw error;
+            }
+            finally {
+                entry.running = undefined;
+                await deps.store.update(sessionId, {}).catch(() => undefined);
+            }
+        },
+        cancel(sessionId) {
+            entries.get(sessionId)?.running?.cancel();
+        },
+        async closeAll() {
+            for (const entry of entries.values())
+                entry.running?.cancel();
+            const all = [...entries.values()];
+            entries.clear();
+            await Promise.allSettled(all.map((entry) => entry.session.close()));
+        },
+    };
+}

package/dist/code/src/acp/stop-reasons.js

@@ -0,0 +1,31 @@
+import { AcpError, ErrorCode } from "./types.js";
+const PAUSE_NOTICES = {
+    approval: "The run was paused because too many actions were refused by the review. Send a message to continue.",
+    quota: "The run was paused: the provider's quota is used up.",
+    budget: "The run was paused: its budget is used up.",
+    input: "The run was paused and waits for input.",
+    blocked: "The run was paused because the goal is blocked.",
+};
+/** Cuts a provider error to something a client may show: one short line, with anything that looks like a credential removed. */
+export function safeErrorText(text) {
+    const cleaned = text
+        .replace(/(authorization|x-api-key|api[-_]?key)\s*[:=]\s*(?:(?:bearer|basic)\s+)?\S+/gi, "$1: [removed]")
+        .replace(/\bBearer\s+[\w.~+/=-]+/gi, "Bearer [removed]")
+        .replace(/\bsk-[\w-]{8,}/g, "[removed]")
+        .replace(/\s+/g, " ")
+        .trim();
+    return cleaned.length > 500 ? `${cleaned.slice(0, 500)}…` : cleaned;
+}
+/**
+ * `done` ends the turn; a cancel the client asked for is always `cancelled` (an abort that surfaces as an error is still a cancel);
+ * a pause is a refusal with a note; a failed run is a JSON-RPC error.
+ */
+export function outcomeOf(result, cancelRequested) {
+    if (cancelRequested || result.reason === "cancelled")
+        return { result: { stopReason: "cancelled" } };
+    if (result.reason === "done")
+        return { result: { stopReason: "end_turn" } };
+    if (result.reason === "paused")
+        return { result: { stopReason: "refusal" }, notice: PAUSE_NOTICES[result.pause ?? ""] ?? "The run was paused." };
+    throw new AcpError(ErrorCode.internalError, `The run failed: ${safeErrorText(result.error ?? "unknown error")}`);
+}

package/dist/code/src/acp/types.js

@@ -0,0 +1,22 @@
+// The slice of the ACP wire format the agent uses, written as plain types. Nothing here imports the SDK: the pure mappers
+// depend on these types only, and `connection.ts` is the one place where they meet the SDK's own (the compiler checks that
+// they fit).
+/** The JSON-RPC error codes the agent uses (the standard ones, plus two in the server-defined range). */
+export const ErrorCode = {
+    invalidParams: -32602,
+    internalError: -32603,
+    authRequired: -32000,
+    busy: -32001,
+    sessionNotFound: -32002,
+};
+/** An error with a code the client can act on. The connection turns it into a JSON-RPC error; anything else becomes a plain internal error. */
+export class AcpError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "AcpError";
+        this.code = code;
+        this.data = data;
+    }
+}

package/dist/code/src/cli.js

@@ -6,6 +6,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { ConfigError, configDirectory, readConfigFile, resolveSettings } from "./config.js";
+import { serveProcess } from "./acp/serve.js";
 import { runExec } from "./exec-mode.js";
 import { createFauxClient } from "./framework-testing.js";
 import { parseInvocation } from "./invocation.js";
@@ -25,6 +26,7 @@ Usage:
   sakuracode fork <id|--last>            copy a session into a new one and continue there
   sakuracode review [--base BRANCH | --commit SHA] [focus]   review changes, then print the review
   sakuracode sessions                    list sessions
+  sakuracode acp                         serve the Agent Client Protocol on stdin/stdout (for T3 Code and other ACP clients)
   sakuracode providers                   list providers and whether their key is set
 
 Options:
@@ -168,6 +170,12 @@ async function run(argv, io) {
         return listProvidersCommand(settings, io);
     if (invocation.mode === "sessions")
         return listSessionsCommand(store, io);
+    if (invocation.mode === "acp") {
+        // stdout belongs to the protocol. Review mode: the command line, else the config, but never full-access unless it was asked for on the command line.
+        const asked = flagLayer(values).permissions;
+        const permissions = asked ?? (settings.permissions === "full-access" ? "auto" : settings.permissions);
+        return serveProcess({ stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, env: io.env }, { settings, store, version: VERSION, permissions, ...(clients ? { clients } : {}) });
+    }
     if (invocation.mode === "exec") {
         let prompt = invocation.prompt;
         if (prompt === "-" || (prompt === "" && !io.stdin.isTTY))

package/dist/code/src/context-estimate.js

@@ -0,0 +1,44 @@
+function messageCharacters(message) {
+    let characters = 0;
+    for (const part of message.content) {
+        if (part.type === "text")
+            characters += part.text.length;
+        else if (part.type === "tool_call")
+            characters += part.name.length + JSON.stringify(part.args ?? "").length;
+        else if (part.type === "image")
+            characters += 4000;
+        else
+            characters += JSON.stringify(part.data ?? "").length;
+    }
+    return characters;
+}
+/** Tokens of the log from the compaction on: the summary, the kept messages and everything after. */
+export function estimateAfterCompaction(branch) {
+    const compaction = branch.findLastIndex((entry) => entry.type === "compaction");
+    const entry = branch[compaction];
+    if (!entry || entry.type !== "compaction")
+        return undefined;
+    const kept = branch.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
+    const from = kept === -1 ? compaction + 1 : kept;
+    let characters = entry.summary.length;
+    for (let index = from; index < branch.length; index++) {
+        const candidate = branch[index];
+        if (candidate?.type === "message")
+            characters += messageCharacters(candidate.message);
+        else if (candidate?.type === "custom_message")
+            characters += candidate.content.reduce((sum, part) => sum + (part.type === "text" ? part.text.length : 0), 0);
+    }
+    return Math.ceil(characters / 4);
+}
+export async function measureContext(source) {
+    const status = await source.context();
+    const branch = await source.log.branch();
+    const compaction = branch.findLastIndex((entry) => entry.type === "compaction");
+    if (compaction === -1)
+        return { tokens: status.tokens, window: status.window, estimated: false };
+    const replied = branch.slice(compaction + 1).some((entry) => entry.type === "message" && entry.message.role === "assistant" && entry.message.usage !== undefined);
+    if (replied)
+        return { tokens: status.tokens, window: status.window, estimated: false };
+    const tokens = estimateAfterCompaction(branch) ?? status.tokens;
+    return { tokens, window: status.window, estimated: true };
+}

package/dist/code/src/invocation.js

@@ -8,6 +8,8 @@ export function parseInvocation(positionals, flags) {
         case "providers":
         case "sessions":
             return command === "providers" ? { mode: "providers" } : { mode: "sessions" };
+        case "acp":
+            return { mode: "acp" };
         case "exec": {
             if (rest[0] === "resume") {
                 const reference = last ?? rest[1];

package/dist/code/src/permissions.js

@@ -7,6 +7,15 @@ export const PERMISSION_PRESETS = {
     strict: { name: "strict", summary: "reviewed; three refusals in a row pause the run", review: true, tools: undefined, breakerConsecutive: 3 },
     "full-access": { name: "full-access", summary: "nothing is reviewed", review: false, tools: undefined, breakerConsecutive: undefined },
 };
+/**
+ * What Shift+Tab switches to: auto, then strict, then read-only, then auto again. `full-access` is never reached by the key
+ * (it needs the explicit `/permissions full-access`); from it the key goes back to auto.
+ */
+export function nextPermission(current) {
+    const cycle = ["auto", "strict", "read-only"];
+    const index = cycle.indexOf(current);
+    return index === -1 ? "auto" : cycle[(index + 1) % cycle.length];
+}
 export function isPermissionName(value) {
     return PERMISSION_NAMES.includes(value);
 }

package/dist/code/src/reports.js

@@ -39,7 +39,7 @@ export function statusReport(input) {
         ["Model", `${input.model} via ${input.provider}${input.thinking ? `, thinking ${input.thinking}` : ""}`],
         ["Permissions", `${input.permissions}: ${PERMISSION_PRESETS[input.permissions].summary}`],
         ["Redaction", input.redaction ? "on" : "off"],
-        ["Context", `${number(input.context.tokens)} of ${number(input.context.window)} tokens used, ${free}% left${input.context.compactAt ? `, compacts at ${number(input.context.compactAt)}` : ""}`],
+        ["Context", `${input.contextEstimated ? "about " : ""}${number(input.context.tokens)} of ${number(input.context.window)} tokens used${input.contextEstimated ? " (estimate until the next reply)" : ""}, ${input.contextEstimated ? "~" : ""}${free}% left${input.context.compactAt ? `, compacts at ${number(input.context.compactAt)}` : ""}`],
         ...usageRows(input),
         ["Goal", input.goal ? `${input.goal.status}: ${input.goal.objective}` : "none"],
         ["Idle compaction", input.idleCompaction],

package/dist/code/src/session-controller.js

@@ -3,13 +3,14 @@
 // through the Transcript (what to show) and the Surface (what only a screen can do).
 import { openAgentSession } from "./agent-session.js";
 import { expandMentions } from "./mentions.js";
-import { isPermissionName } from "./permissions.js";
+import { isPermissionName, nextPermission } from "./permissions.js";
 import { allProviders, chooseProvider, listProviders } from "./providers.js";
 import { mcpReport, medianReplyHitRate, modelsReport, permissionsReport, statusReport } from "./reports.js";
 import { createRunDriver } from "./run-driver.js";
 import { sessionLabel, titleFromPrompt } from "./session-store.js";
 import { runShell } from "./shell.js";
 import { findCommand, helpMarkdown, parseSlash } from "./slash-commands.js";
+import { measureContext } from "./context-estimate.js";
 import { contextLeftPercent } from "./status-line.js";
 import { excerpt, replayLog } from "./transcript.js";
 import { imageMediaType } from "./images.js";
@@ -26,6 +27,13 @@ export function createController(deps) {
     let session;
     let meta;
     let contextPercent;
+    // a mode asked for during a run; the agent is not reopened while it works
+    let pendingPermissions;
+    let contextEstimated = false;
+    let contextEstimatedShown = false;
+    let contextWindow = 0;
+    // a newer measurement wins over an older one that finishes later
+    let contextVersion = 0;
     const firstImages = [...(deps.images ?? [])];
     let choice = {
         provider: deps.clients ? "scripted" : chooseProvider(deps.settings, deps.env),
@@ -35,6 +43,18 @@ export function createController(deps) {
         thinking: deps.settings.thinking,
     };
     driver.onChange(() => surface.changed());
+    // The percentage follows the run: each finished reply carries the provider-reported usage, and a compaction changes the size at once.
+    driver.onEvent((event) => {
+        if (event.type === "message_end" && event.message.role === "assistant" && event.message.usage && contextWindow > 0) {
+            const { input, output, cacheRead, cacheWrite } = event.message.usage;
+            contextVersion++;
+            contextEstimated = false;
+            setContextPercent(contextLeftPercent(contextWindow - (input + output + cacheRead + cacheWrite), contextWindow));
+        }
+        else if (event.type === "compaction") {
+            void refreshContext().catch(() => undefined);
+        }
+    });
     const notice = (level, text) => transcript.add({ kind: "notice", level, text });
     const requireSession = () => {
         if (!session)
@@ -105,11 +125,29 @@ export function createController(deps) {
         replayLog(transcript, entries);
         notice("info", `Resumed ${sessionLabel(meta ?? target)} (${target.id.slice(0, 8)}).`);
     }
+    async function statusContext(active) {
+        const status = await active.agent.context();
+        const measured = await measureContext(active.agent);
+        return { context: { ...status, tokens: measured.tokens, free: Math.max(0, measured.window - measured.tokens) }, contextEstimated: measured.estimated };
+    }
+    function setContextPercent(next) {
+        const flagChanged = contextEstimatedShown !== contextEstimated;
+        contextEstimatedShown = contextEstimated;
+        if (next === contextPercent && !flagChanged)
+            return;
+        contextPercent = next;
+        surface.changed();
+    }
     async function refreshContext() {
         if (!session)
             return;
-        const status = await session.agent.context();
-        contextPercent = contextLeftPercent(status.free, status.window);
+        const version = ++contextVersion;
+        const measured = await measureContext(session.agent);
+        if (version !== contextVersion)
+            return;
+        contextWindow = measured.window;
+        contextEstimated = measured.estimated;
+        setContextPercent(contextLeftPercent(measured.window - measured.tokens, measured.window));
     }
     // ---------- running ----------
     async function runInput(input, options) {
@@ -127,8 +165,18 @@ export function createController(deps) {
         }
         if (meta)
             meta = await store.update(meta.id, {});
+        await applyPendingPermissions();
         return outcome.result;
     }
+    async function applyPendingPermissions() {
+        const wanted = pendingPermissions;
+        pendingPermissions = undefined;
+        if (wanted === undefined || wanted === choice.permissions)
+            return surface.changed();
+        if (await reopen({ permissions: wanted }))
+            notice("info", `Permissions: ${wanted} (Shift+Tab to change)`);
+        surface.changed();
+    }
     function reportEnd(result) {
         if (result.reason === "error")
             notice("error", `The run failed: ${result.error ?? "unknown error"}`);
@@ -179,7 +227,7 @@ export function createController(deps) {
                 thinking: active.thinking,
                 permissions: active.permissions,
                 redaction: active.redaction,
-                context: await active.agent.context(),
+                ...(await statusContext(active)),
                 usage: await active.agent.usage(),
                 medianHitRate: medianReplyHitRate(await active.agent.log.branch()),
                 goal: await active.agent.goal(),
@@ -201,6 +249,7 @@ export function createController(deps) {
                 return host.print(permissionsReport(choice.permissions, choice.redaction));
             if (!isPermissionName(name))
                 return notice("error", `Unknown preset "${name}". Use auto, read-only, strict or full-access.`);
+            pendingPermissions = undefined;
             if (await reopen({ permissions: name }))
                 notice("info", `Permissions: ${name}.`);
         },
@@ -379,10 +428,22 @@ export function createController(deps) {
                 transcript.muteCompaction(false);
                 stop();
             }
-            const after = (await requireSession().agent.context()).tokens;
+            const after = (await measureContext(requireSession().agent)).tokens;
             notice("info", `compacted after ${idleMinutes} min idle, ${thousands(before)} to ${thousands(after)} tokens`);
             return true;
         },
+        async cyclePermissions() {
+            const next = nextPermission(pendingPermissions ?? choice.permissions);
+            if (driver.working || launching) {
+                pendingPermissions = next === choice.permissions ? undefined : next;
+                return surface.changed();
+            }
+            if (!session)
+                return;
+            if (await reopen({ permissions: next }))
+                notice("info", `Permissions: ${next} (Shift+Tab to change)`);
+            surface.changed();
+        },
         statusInfo: () => ({
             provider: choice.provider,
             model: choice.model ?? "",
@@ -390,7 +451,9 @@ export function createController(deps) {
             cwd: deps.cwd,
             home: deps.home,
             contextLeftPercent: contextPercent,
+            contextEstimated: contextEstimatedShown,
             permissions: choice.permissions,
+            pendingPermissions,
             redaction: choice.redaction,
             working: driver.working,
             queued: driver.pending().length,

package/dist/code/src/slash-commands.js

@@ -79,5 +79,5 @@ export function complete(input) {
 }
 export function helpMarkdown() {
     const rows = COMMANDS.map((command) => `| \`${command.usage}\` | ${command.summary} |`);
-    return ["| Command | What it does |", "|---|---|", ...rows, "", "While the agent works: **Enter** steers it, **Tab** queues a message, **Esc** cancels. `!cmd` runs a shell command yourself."].join("\n");
+    return ["| Command | What it does |", "|---|---|", ...rows, "", "While the agent works: **Enter** steers it, **Tab** queues a message, **Esc** cancels. **Shift+Tab** cycles the review mode (auto, strict, read-only; `/permissions full-access` is explicit). `!cmd` runs a shell command yourself."].join("\n");
 }

package/dist/code/src/status-line.js

@@ -11,12 +11,21 @@ export function shortenPath(path, home, width) {
 export function contextLeftPercent(free, window) {
     return window <= 0 ? 0 : Math.max(0, Math.min(100, Math.round((free / window) * 100)));
 }
+function contextText(info, pal) {
+    const text = `${info.contextEstimated ? "~" : ""}${info.contextLeftPercent}%`;
+    return (info.contextLeftPercent ?? 100) < 15 ? pal.red(text) : text;
+}
+function permissionsPiece(info, pal) {
+    const mode = info.pendingPermissions ?? info.permissions;
+    const paint = mode === "auto" ? pal.dim : mode === "full-access" ? pal.red : pal.yellow;
+    return info.pendingPermissions === undefined ? paint(mode) : paint(mode) + pal.dim(" (next turn)");
+}
 export function formatStatusLine(info, width, color) {
     const pal = createPalette(color);
     const pieces = [
         pal.bold(info.model) + (info.thinking ? pal.dim(` ${info.thinking}`) : ""),
-        info.contextLeftPercent === undefined ? "" : `${info.contextLeftPercent < 15 ? pal.red(`${info.contextLeftPercent}%`) : `${info.contextLeftPercent}%`} context left`,
-        info.permissions === "auto" ? "" : pal.yellow(info.permissions),
+        info.contextLeftPercent === undefined ? "" : `${contextText(info, pal)} context left`,
+        permissionsPiece(info, pal),
         info.redaction ? pal.magenta("redaction") : "",
         info.queued > 0 ? pal.cyan(`${info.queued} queued`) : "",
         shortenPath(info.cwd, info.home, Math.max(12, Math.floor(width / 3))),

package/dist/code/src/tui/app.js

@@ -163,6 +163,12 @@ export async function runTui(options) {
         // a dropped or pasted image file becomes an @mention, which attaches it
         const dropped = key.name === "paste" ? pastedImagePath(key.text ?? "", options.controller.cwd) : undefined;
         const action = editor.handle(dropped ? { name: "paste", text: `@${dropped} ` } : key);
+        if (action === "shift-tab") {
+            // the command popup uses Tab; Shift+Tab never changes the mode while it is open
+            if (commands.length === 0)
+                void controller.cyclePermissions().catch((error) => showHint(error.message));
+            return;
+        }
         if (action !== "none")
             popupIndex = action === "tab" ? popupIndex : 0;
         if (action === "submit")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sakuracode",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "sakuracode: an open-source terminal coding agent (command-line AI coding assistant) with automatic review of every tool call. Works with DeepSeek, OpenCode Go and any OpenAI-compatible endpoint.",
@@ -29,7 +29,9 @@
     "node": ">=26"
   },
   "dependencies": {
-    "quickjs-emscripten": "^0.32.0"
+    "@agentclientprotocol/sdk": "2.4.0",
+    "quickjs-emscripten": "^0.32.0",
+    "zod": "4.6.7"
   },
   "publishConfig": {
     "access": "public",