@botconnector/bccli 0.5.0-rc.4 → 0.5.1

package/README.md

@@ -0,0 +1,250 @@
+# BCCLI
+
+**Bahasa Indonesia** · [English](README.en.md)
+
+[![npm](https://img.shields.io/npm/v/@botconnector/bccli?label=@botconnector/bccli)](https://www.npmjs.com/package/@botconnector/bccli?activeTab=versions)
+[![npm downloads](https://img.shields.io/npm/dm/@botconnector/bccli)](https://www.npmjs.com/package/@botconnector/bccli)
+[![Node.js](https://img.shields.io/node/v/@botconnector/bccli?label=Node.js)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Website](https://img.shields.io/badge/website-botconnector.id-06305A)](https://botconnector.id/id/download)
+
+Agent AI coding dari [BotConnector](https://botconnector.id/) yang bekerja di terminal: membaca kode, mengedit file,
+dan menjalankan perintah — dengan izin kamu.
+
+![BCCLI membuat hello.js dan menjalankannya dengan node](docs/demo.gif)
+
+*Rekaman sesi asli: BCCLI membuat file `hello.js` lalu menjalankannya dengan `node`.*
+
+```bash
+# install satu baris (macOS / Linux / WSL2) — pasang Node portable bila perlu, tanpa sudo
+curl -fsSL https://raw.githubusercontent.com/farijarifriyanto-debug/bccli/main/install.sh | bash
+
+# Windows (PowerShell 5.1+) — butuh Node.js 22+ terpasang lebih dulu
+irm https://raw.githubusercontent.com/farijarifriyanto-debug/bccli/main/install.ps1 | iex
+
+# atau manual, bila Node.js 22+ sudah terpasang
+npm i -g @botconnector/bccli        # rilis stabil terbaru, butuh Node.js 22+
+npm i -g @botconnector/bccli@next   # …atau pra-rilis berikutnya
+bccli login                         # simpan API key BotConnector Cloud
+cd project-kamu && bccli
+```
+
+## Pemakaian
+
+| Perintah | Fungsi |
+|---|---|
+| `bccli` | mode interaktif |
+| `bccli -p "tugas"` | satu tugas tanpa interaksi (skrip/CI) |
+| `bccli -p "tugas" --output-format json` | hasil akhir sebagai satu objek JSON; `stream-json` = event JSONL per tahap (tool_use/tool_result/message/result) untuk CI |
+| `bccli -c` / `bccli -r` | lanjutkan sesi terakhir / pilih sesi |
+| `bccli -m provider/model` | pilih model |
+| `bccli --reasoning <auto|off|low|medium|high|max>` | pilih level reasoning untuk invocation ini |
+| `bccli models` | daftar model |
+
+Perintah di dalam sesi (ketik `/` untuk saran, ↑↓ pilih, Enter jalankan):
+
+| Perintah | Fungsi |
+|---|---|
+| `/help` | daftar perintah dan pintasan |
+| `/model` | ganti model |
+| `/reasoning` | pilih Auto / Off / Low / Medium / High / Max |
+| `/provider` | tambah/pilih provider AI |
+| `/language` | ganti bahasa tampilan (`en` / `id`) |
+| `/mcp` | pasang/kelola server MCP |
+| `/new` | sesi baru (sesi lama tetap tersimpan) |
+| `/resume` | lanjutkan sesi lain di folder ini |
+| `/session` | info sesi ini |
+| `/status` | versi, model, mode izin, MCP, konteks |
+| `/permissions` | lihat/cabut izin |
+| `/pr` | review pull request (`/pr <n\|url\|branch>`) |
+| `/worktree` | daftar git worktree; buat dengan `bccli -w <nama>` |
+| `/undo` | batalkan edit file giliran terakhir |
+| `/redo` | terapkan ulang edit file yang baru dibatalkan `/undo` |
+| `/rewind` | mundur beberapa giliran: percakapan + edit file (`/rewind 2`) |
+| `/diff` | git diff project |
+| `/copy` | salin jawaban terakhir |
+| `/export` | simpan percakapan ke markdown |
+| `/memory` | instruksi project (/memory <teks>, /memory global <teks>) |
+| `/init` | buat/perbarui AGENTS.md untuk project ini |
+| `/agents` | daftar subagent |
+| `/tasks` | daftar tugas latar belakang |
+| `/skills` | daftar skill dan perintah custom |
+| `/doctor` | cek kesehatan instalasi |
+| `/login` | simpan API key provider aktif |
+| `/logout` | hapus API key provider aktif |
+| `/clear` | mulai percakapan baru |
+| `/compact` | ringkas percakapan |
+| `/cost` | pemakaian token sesi ini |
+| `/exit` | keluar |
+
+`/undo` hanya membatalkan perubahan lewat alat edit/tulis (bukan perintah bash), per giliran, sampai 20 giliran ke belakang.
+Shift+Tab ganti mode izin: `default` → `acceptEdits` → `plan` → `allowAll`.
+
+Membaca file rahasia (`.env`, `.ssh`, `.aws`, `id_rsa`, `*.pem`, `*.key`, `secret*`,
+`credential*`) selalu meminta izin; `allowAll` satu-satunya mode yang tidak bertanya, dan
+izin itu tidak bisa diberikan "untuk sesi ini".
+
+Mode `-p` tidak pernah bertanya: alat yang butuh izin ditolak, kecuali memakai
+`--allow-all` atau `--allowed-tools bash,edit,fetch`.
+
+## Bahasa
+
+Tampilan BCCLI (bantuan, pesan, prompt izin) memakai **bahasa Inggris secara default**. Bahasa Indonesia tetap tersedia:
+
+```bash
+bccli --lang id          # hanya untuk satu kali jalan
+BCCLI_LANG=id bccli      # lewat environment
+/language id             # di dalam sesi; disimpan di ~/.bccli/config.json ("language")
+```
+
+Urutan prioritas: `--lang`, lalu `BCCLI_LANG`, lalu `language` di config, lalu Inggris. Bahasa jawaban model mengikuti bahasa yang kamu tulis, dan
+pesan alat yang dibaca model (hasil tool, galat) selalu berbahasa Inggris supaya tidak mengganggu bahasa jawabannya.
+
+## Provider
+
+`/provider` di dalam sesi (atau `bccli provider add <id>`) memasang provider hanya dengan API key:
+
+| Id | Provider |
+|---|---|
+| `bc-cloud` | BotConnector Cloud (default) |
+| `openrouter` | OpenRouter |
+| `openai` | OpenAI |
+| `gemini` | Google Gemini |
+| `deepseek` | DeepSeek |
+| `groq` | Groq |
+| `ollama-cloud` | Ollama Cloud |
+| `ollama` | Ollama lokal (tanpa key) |
+| `lmstudio` | LM Studio lokal (tanpa key) |
+
+Provider lain yang OpenAI-compatible: pilih **Custom…** di `/provider`, atau
+`bccli provider add corp --url https://corp.example/v1 --name "Corp"`.
+
+`/model` menampilkan model dari **semua** provider yang sudah punya key, dikelompokkan
+per provider; ketik untuk menyaring. Pilihan tersimpan sebagai default.
+
+Reasoning dapat dipilih lewat `bccli --reasoning <auto|off|low|medium|high|max>` atau `/reasoning`.
+**Auto** memakai default model/provider dan BCCLI tidak mengirim override reasoning apa pun. BCCLI tidak
+otomatis menurunkan atau menaikkan reasoning effort. Level manual diteruskan bila kontrak provider/model
+mendukungnya; level yang tidak didukung menghasilkan error yang jelas dan tidak di-downgrade diam-diam.
+
+`.bccli/config.json` di dalam project hanya boleh memilih `model` dan menambah provider baru tanpa API key —
+preference `reasoning` hanya dibaca dari config user `~/.bccli/config.json`, bukan dari repo yang di-clone —
+izin (`permissionMode`, `allow`) dan provider yang sudah ada hanya diatur dari `~/.bccli/config.json`,
+supaya repo yang kamu clone tidak bisa memberi dirinya izin penuh atau mencuri API key.
+
+Daftar lengkap kunci `~/.bccli/config.json` beserta nilai dan cakupannya: [`docs/config.md`](docs/config.md).
+
+## Integrasi agent eksternal
+
+BCCLI dapat memasang BotConnector sebagai provider untuk agent lain:
+
+| Perintah | Fungsi |
+|---|---|
+| `bccli integrations` | lihat status integrasi |
+| `bccli connect opencode` | hubungkan OpenCode ke BotConnector |
+| `bccli connect aider` | hubungkan Aider ke BotConnector |
+| `bccli connect cline` | hubungkan Cline CLI ke BotConnector |
+| `bccli connect deepseek-harness` / `bccli connect dsh` | hubungkan DeepSeek Harness ke BotConnector |
+| `bccli connect codex` | buat profile Codex Responses API + launcher BotConnector |
+| `bccli connect claude-code` | buat launcher Claude Code via Anthropic Messages compatibility |
+| `bccli connect cursor` | buat guided setup Cursor + warning override Base URL |
+| `bccli connect openai-cli` | buat launcher OpenAI CLI khusus BotConnector |
+| `bccli connect openai-sdk` | buat env profile untuk OpenAI Python/Node SDK |
+| `bccli connect openai-compatible` | buat env profile universal OpenAI-compatible |
+| `bccli disconnect <agent>` | pulihkan config sebelum integrasi |
+
+OpenCode memakai config global `~/.config/opencode/opencode.json`. BCCLI mengambil katalog model BotConnector saat connect,
+menjaga config provider lain, dan menyimpan secret di file terpisah di `~/.bccli/integrations/`.
+Aider memakai `~/.aider.conf.yml` yang menunjuk ke env file BCCLI terpisah; BCCLI menolak menimpa setting
+OpenAI/env-file Aider yang sudah ada.
+
+Cline memakai provider `openai-compatible` di `~/.cline/data/settings/providers.json`. Jika slot itu sudah dipakai
+endpoint lain, BCCLI menolak menimpanya. Cline sendiri menyimpan API key provider di file tersebut.
+
+DeepSeek Harness memakai custom provider `botconnector` di `$DSH_HOME/settings.yaml` dengan
+`api: openai-completions` dan `apiKeyEnv: BOTCONNECTOR_API_KEY`; key diletakkan pada blok BCCLI di
+`$DSH_HOME/.env`. Provider DSH lain tetap dipertahankan. Setelah connect, jalankan profile web dengan
+`dsh web` (setara dengan `dsh --profile web`); `dsh` tanpa profile memang ditolak oleh DSH 0.1.x.
+
+Codex memakai profile `$CODEX_HOME/botconnector.config.toml` dengan `wire_api = "responses"` dan launcher
+BCCLI yang membaca key dari storage BCCLI saat dijalankan. Claude Code memakai launcher terisolasi dengan
+`ANTHROPIC_BASE_URL=https://api.botconnector.id` dan endpoint kompatibilitas `/v1/messages` + token counting.
+Login/config utama Codex dan Claude Code tidak ditimpa.
+
+External agent memanggil BotConnector langsung, jadi discovery model tidak memakai identitas khusus BCCLI.
+Akses yang memang dibatasi ke BCCLI/Web App (misalnya Luna launch access) tidak otomatis diwariskan.
+Sebelum mengubah config eksternal, BCCLI membuat backup agar disconnect dapat memulihkannya.
+
+## Internet
+
+- `web_search`: mencari di web tanpa perlu izin. Memakai akun BotConnector Cloud
+  bila ada key, kalau tidak langsung ke Keenable (gratis, tanpa key). Hasilnya
+  judul, URL, dan cuplikan singkat, jadi hemat token.
+- `fetch`: membuka satu URL dari komputer ini (butuh izin per host).
+
+## MCP
+
+`/mcp` (atau `bccli mcp add <nama>`) memasang server dari katalog:
+`playwright`, `context7`, `fetch`, `filesystem`, `git`, `github`. Server remote lain:
+`bccli mcp add nama --url https://…`. Tersimpan di `~/.bccli/mcp.json` (format `mcpServers`
+seperti Claude Code). Semua alat MCP selalu minta izin.
+
+`.bccli/mcp.json` di dalam repo tidak dijalankan sebelum kamu setujui (ditanya sekali per folder).
+
+`bccli mcp serve` menjalankan MCP server stdio dengan tools BotConnector milikmu
+(`bc_search`, `bc_fetch`, `bc_models`, `bc_chat`) untuk dipakai Claude Code, Cursor,
+opencode, dan host MCP lain. Butuh `bccli login` (atau `BOTCONNECTOR_API_KEY`):
+
+```bash
+claude mcp add botconnector -- npx -y @botconnector/bccli mcp serve
+```
+
+## Subagent
+
+Agent bisa mendelegasikan pekerjaan lewat alat `task`:
+- `explore` — hanya baca & cari, bisa jalan paralel;
+- `general` — semua alat (edit/perintah tetap minta izin);
+- custom — `.bccli/agents/nama.md` atau `.claude/agents/nama.md`:
+
+```markdown
+---
+name: reviewer
+description: review perubahan kode
+tools: [read, grep, glob]
+model: openrouter/qwen/qwen3-coder
+---
+Kamu reviewer kode. Laporkan bug nyata saja.
+```
+
+## Skill & perintah custom
+
+- Skill: folder berisi `SKILL.md` di `~/.bccli/skills/`, `.bccli/skills/`, `~/.claude/skills/`,
+  `.claude/skills/` — dipakai agent otomatis bila cocok, atau `/nama-skill`.
+- Perintah: `commands/nama.md` di folder yang sama → `/nama argumen` (`$ARGUMENTS` diganti argumen).
+
+## Todo & mode plan
+
+Tugas ≥ 3 langkah menampilkan checklist di atas kotak input. Di mode plan (Shift+Tab),
+agent hanya membaca lalu mengajukan rencana; `[a]` setujui dengan edit otomatis,
+`[y]` setujui dengan tanya tiap langkah, `[n]` minta perbaikan.
+
+Instruksi project dibaca dari `AGENTS.md`, `CLAUDE.md`, dan `BCCLI.md`.
+
+## Pengembangan
+
+```bash
+npm install
+npm test && npm run typecheck && npm run lint && npm run build
+npm run coverage   # gerbang coverage (juga dijalankan di CI Linux)
+```
+
+CI (`ci.yml`) menjalankan hal yang sama di Linux, macOS, dan Windows, plus gerbang coverage di Linux.
+Rilis: naikkan `version` di `package.json`, lalu push tag `v<version>` — `release.yml`
+menjalankan test, smoke test ke BotConnector Cloud, dan `npm publish --provenance`.
+
+## Pelajari lebih lanjut
+
+- [Unduh & panduan BCCLI](https://botconnector.id/id/download)
+- [Developer API BotConnector](https://botconnector.id/id/developers/api) — endpoint kompatibel OpenAI SDK
+- [Switchboard](https://github.com/farijarifriyanto-debug/switchboard) — harness agent open source dari BotConnector
+- [Berkontribusi](CONTRIBUTING.md)

package/dist/abort.d.ts

@@ -0,0 +1,5 @@
+export declare const ABORTED: unique symbol;
+/** Resolves with the promise's value, or with ABORTED as soon as the signal fires. */
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T | typeof ABORTED>;
+/** Collects an async iterable, giving up (and telling the iterator to stop) as soon as the signal fires. */
+export declare function collectUntilAbort<T>(iterable: AsyncIterable<T>, signal: AbortSignal | undefined, onItem: (item: T) => void): Promise<boolean>;

package/dist/acp-HWHF25KU.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import {
+  t
+} from "./chunk-IDZLHEVL.js";
+
+// src/acp.ts
+var ACP_PROTOCOL_VERSION = 1;
+var TOOL_KINDS = {
+  read: "read",
+  repo_map: "read",
+  edit: "edit",
+  write: "edit",
+  grep: "search",
+  glob: "search",
+  bash: "execute",
+  powershell: "execute",
+  fetch: "fetch",
+  web_search: "fetch"
+};
+var kindOf = (tool) => TOOL_KINDS[tool] ?? "other";
+var titleOf = (tool, target) => (target ? `${tool}: ${target}` : tool).slice(0, 200);
+var MAX_OUTPUT = 4e3;
+var PERMISSION_OPTIONS = [
+  { optionId: "allow", name: "Allow", kind: "allow_once" },
+  { optionId: "allow_session", name: "Allow for this session", kind: "allow_always" },
+  { optionId: "reject", name: "Reject", kind: "reject_once" }
+];
+var ANSWERS = { allow: "yes", allow_session: "session", reject: "no" };
+function runAcp(input, output, opts) {
+  const sessions = /* @__PURE__ */ new Map();
+  const awaiting = /* @__PURE__ */ new Map();
+  let nextSession = 1;
+  let nextRequest = 1;
+  const write = (msg) => {
+    output.write(`${JSON.stringify(msg)}
+`);
+  };
+  const reply = (id, result) => write({ jsonrpc: "2.0", id, result });
+  const replyError = (id, code, message) => write({ jsonrpc: "2.0", id, error: { code, message } });
+  const update = (sessionId, body) => write({ jsonrpc: "2.0", method: "session/update", params: { sessionId, update: body } });
+  const ioFor = (sid, session) => ({
+    onThinking(delta) {
+      update(sid, { sessionUpdate: "agent_thought_chunk", content: { type: "text", text: delta } });
+    },
+    toolStart(id, tool, target) {
+      session.open.push({ id, tool, target });
+      update(sid, { sessionUpdate: "tool_call", toolCallId: id, title: titleOf(tool, target), kind: kindOf(tool), status: "in_progress", rawInput: { target } });
+    },
+    toolEnd(id, output2, isError) {
+      session.open = session.open.filter((c) => c.id !== id);
+      const text = output2.length > MAX_OUTPUT ? `${output2.slice(0, MAX_OUTPUT)}
+[truncated]` : output2;
+      update(sid, {
+        sessionUpdate: "tool_call_update",
+        toolCallId: id,
+        status: isError ? "failed" : "completed",
+        ...text ? { content: [{ type: "content", content: { type: "text", text } }] } : {}
+      });
+    },
+    askPermission(req) {
+      return new Promise((resolve) => {
+        const requestId = nextRequest++;
+        const call = [...session.open].reverse().find((c) => c.tool === req.tool && c.target === req.target);
+        const settle = (answer) => {
+          session.pending.delete(settle);
+          awaiting.delete(requestId);
+          resolve(answer);
+        };
+        session.pending.add(settle);
+        awaiting.set(requestId, (message) => {
+          const outcome = message.result?.outcome;
+          settle(outcome?.outcome === "selected" ? ANSWERS[outcome.optionId ?? ""] ?? "no" : "no");
+        });
+        write({
+          jsonrpc: "2.0",
+          id: requestId,
+          method: "session/request_permission",
+          params: {
+            sessionId: sid,
+            toolCall: { toolCallId: call?.id ?? `permission-${requestId}`, title: titleOf(req.tool, req.target), kind: kindOf(req.tool), status: "pending" },
+            options: PERMISSION_OPTIONS
+          }
+        });
+      });
+    }
+  });
+  const handle = async (msg) => {
+    const { id, method, params } = msg ?? {};
+    if (method === void 0 && id !== void 0 && (msg.result !== void 0 || msg.error !== void 0)) {
+      awaiting.get(id)?.(msg);
+      return;
+    }
+    if (method === "initialize") {
+      return reply(id, {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        agentCapabilities: {
+          loadSession: false,
+          promptCapabilities: { image: false, audio: false, embeddedContext: true }
+        }
+      });
+    }
+    if (method === "session/new") {
+      const sessionId = `s${nextSession++}`;
+      sessions.set(sessionId, { controller: null, pending: /* @__PURE__ */ new Set(), open: [] });
+      return reply(id, { sessionId });
+    }
+    if (method === "session/cancel") {
+      const session = sessions.get(params?.sessionId ?? "");
+      session?.controller?.abort();
+      for (const settle of [...session?.pending ?? []]) settle("no");
+      return;
+    }
+    if (method === "session/prompt") {
+      const sid = params?.sessionId ?? "";
+      const session = sessions.get(sid);
+      if (!session) return replyError(id, -32602, "Unknown session");
+      if (session.controller) return replyError(id, -32e3, "Session is busy");
+      const text = (params?.prompt ?? []).map((p) => {
+        if (p?.type === "text") return String(p.text ?? "");
+        if ((p?.type === "resource" || p?.type === "embeddedContext") && p.resource?.text) {
+          const label = p.resource.uri ? `
+[${p.resource.uri}]
+` : "\n";
+          return `${label}${p.resource.text}`;
+        }
+        return "";
+      }).filter(Boolean).join("\n");
+      const controller = new AbortController();
+      session.controller = controller;
+      let cancelled = false;
+      controller.signal.addEventListener("abort", () => {
+        cancelled = true;
+      });
+      try {
+        session.agent ??= opts.newAgent(params?.cwd ?? opts.cwd);
+        await session.agent.run(text, (chunk) => update(sid, { sessionUpdate: "agent_message_chunk", content: { type: "text", text: chunk } }), controller.signal, ioFor(sid, session));
+      } catch (e) {
+        if (cancelled) return reply(id, { stopReason: "cancelled" });
+        return replyError(id, -32603, e.message);
+      } finally {
+        if (session.controller === controller) {
+          session.controller = null;
+          session.open = [];
+        }
+      }
+      return reply(id, { stopReason: cancelled ? "cancelled" : "end_turn" });
+    }
+    if (id !== void 0) return replyError(id, -32601, "Method not found");
+  };
+  return new Promise((resolve) => {
+    let buf = "";
+    const onData = (chunk) => {
+      buf += chunk.toString();
+      let idx = buf.indexOf("\n");
+      while (idx >= 0) {
+        const line = buf.slice(0, idx);
+        buf = buf.slice(idx + 1);
+        idx = buf.indexOf("\n");
+        if (!line.trim()) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        void handle(msg);
+      }
+    };
+    const onEnd = () => {
+      input.removeListener("data", onData);
+      for (const session of sessions.values()) {
+        session.controller?.abort();
+        for (const settle of [...session.pending]) settle("no");
+      }
+      resolve();
+    };
+    input.on("data", onData);
+    input.on("end", onEnd);
+  });
+}
+function planDecisionFrom(answer) {
+  if (answer === "no") return "no";
+  if (answer === "session") return "acceptEdits";
+  return "default";
+}
+function runtimeAgent(cwd, allowAll = false, deps = {}) {
+  let rt;
+  return {
+    async run(text, onChunk, signal, io) {
+      if (!rt) {
+        if (deps.createRuntime) rt = deps.createRuntime({ cwd, allowAll });
+        else {
+          const { parseCliArgs } = await import("./args-XA77XUMD.js");
+          const { createRuntime } = await import("./setup-3YB6EKYX.js");
+          rt = createRuntime({ cwd, args: { ...parseCliArgs([]), allowAll } });
+        }
+      }
+      if (io && !allowAll) {
+        rt.agent.askPermission = (req) => io.askPermission(req);
+        rt.interaction.approvePlan = async (plan) => planDecisionFrom(await io.askPermission({ tool: "exit_plan", kind: "edit", target: t("plan"), preview: plan }));
+      }
+      let turnError;
+      rt.agent.onEvent = (event) => {
+        if (event.type === "text") onChunk(event.delta);
+        else if (event.type === "thinking") io?.onThinking?.(event.delta);
+        else if (event.type === "toolStart") io?.toolStart(event.id, event.tool, event.target);
+        else if (event.type === "toolEnd") io?.toolEnd(event.id, event.output, event.isError);
+        else if (event.type === "error") turnError = event.message;
+        else if (event.type === "budgetExceeded") turnError = `Budget exceeded (${event.kind})`;
+      };
+      await rt.agent.run(text, signal);
+      if (turnError) throw new Error(turnError);
+    }
+  };
+}
+export {
+  ACP_PROTOCOL_VERSION,
+  planDecisionFrom,
+  runAcp,
+  runtimeAgent
+};

package/dist/acp.d.ts

@@ -0,0 +1,44 @@
+import type { PermissionAnswer, PermissionAsk } from './agent';
+import type { Runtime } from './setup';
+import type { PlanDecision } from './tools/plan';
+export declare const ACP_PROTOCOL_VERSION = 1;
+/** What the agent reports to the editor besides text: tool calls, and permission questions the editor answers. */
+export interface AcpIo {
+    toolStart(id: string, tool: string, target: string): void;
+    toolEnd(id: string, output: string, isError: boolean): void;
+    askPermission(req: PermissionAsk): Promise<PermissionAnswer>;
+    onThinking?(delta: string): void;
+}
+/** The minimum an ACP client needs: run one prompt, stream text chunks, allow cancellation. */
+export interface AcpAgent {
+    run(text: string, onChunk: (text: string) => void, signal: AbortSignal, io?: AcpIo): Promise<void>;
+}
+/**
+ * Agent Client Protocol over newline-delimited JSON-RPC (the transport editors like Zed use).
+ * Implements the subset: initialize, session/new, session/prompt (streaming session/update
+ * notifications: text chunks and tool calls), session/request_permission, session/cancel;
+ * anything else with an id gets -32601.
+ */
+export declare function runAcp(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, opts: {
+    cwd: string;
+    newAgent: (cwd: string) => AcpAgent;
+}): Promise<void>;
+/**
+ * A plan has no ACP primitive of its own, so it is asked through session/request_permission.
+ * 'yes' approves and keeps the normal per-tool prompts; 'session' also stops asking for edits
+ * for the rest of the session (acceptEdits). A plan answer never turns on allowAll, which stays
+ * an explicit user choice.
+ */
+export declare function planDecisionFrom(answer: PermissionAnswer): PlanDecision;
+export interface AcpRuntimeDeps {
+    /** Test seam: build the runtime without reading config/plugins. */
+    createRuntime?: (opts: {
+        cwd: string;
+        allowAll: boolean;
+    }) => Runtime;
+}
+/**
+ * Production agent: one bccli runtime per ACP session. Permission questions go to the editor
+ * (session/request_permission); `allowAll` skips them and runs everything unasked.
+ */
+export declare function runtimeAgent(cwd: string, allowAll?: boolean, deps?: AcpRuntimeDeps): AcpAgent;

package/dist/agent.d.ts

@@ -0,0 +1,158 @@
+import type { PermissionRequest, Permissions } from './permissions';
+import { type ChatMessage, type Provider, type Usage } from './provider';
+import type { ReasoningLevel } from './reasoning';
+import { type HookEvent, type HooksConfig } from './hooks';
+import type { Tool } from './tools/types';
+import { type UsageCap } from './budget';
+export type AgentEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'textReplace';
+    text: string;
+} | {
+    type: 'toolStart';
+    id: string;
+    tool: string;
+    target: string;
+} | {
+    type: 'toolEnd';
+    id: string;
+    tool: string;
+    output: string;
+    display?: string;
+    isError: boolean;
+} | {
+    type: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+    /** Prompt tokens of the most recent model call: the size of the context, not the session total. */
+    lastInputTokens?: number;
+    /** Cache reads for the most recent model call, rather than the session total. */
+    lastCachedInputTokens?: number;
+    /** True when the provider omitted usage and token counts use the local chars/4 estimate. */
+    estimated?: boolean;
+} | {
+    type: 'compacted';
+} | {
+    type: 'stepLimit';
+    maxSteps: number;
+} | {
+    type: 'budgetExceeded';
+    kind: 'tokens' | 'usd';
+    used: number;
+    limit: number;
+} | {
+    type: 'aborted';
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'done';
+} | {
+    type: 'subagent';
+    parentId: string;
+    agent: string;
+    event: AgentEvent;
+};
+export type PermissionAnswer = 'yes' | 'session' | 'all' | 'no';
+export type PermissionAsk = PermissionRequest & {
+    preview?: string;
+    sessionRules?: string[];
+    agent?: string;
+};
+export type AskPermission = (req: PermissionAsk) => Promise<PermissionAnswer>;
+export interface AgentOptions {
+    provider: Provider;
+    tools: Tool[];
+    permissions: Permissions;
+    systemPrompt: string;
+    cwd: string;
+    history?: ChatMessage[];
+    maxSteps?: number | null;
+    contextWindow?: number;
+    onMessage?: (message: ChatMessage) => void;
+    onReset?: () => void;
+    /** Per-turn token usage delta (provider-reported or estimated); the session persists it for stats. */
+    onUsage?: (usage: Usage) => void;
+    /** Marks the start of a user turn (undo boundary). */
+    onTurnStart?: () => void;
+    checkpoint?: (absPath: string) => Promise<void>;
+    /** Subagent name, shown on its permission prompts. */
+    label?: string;
+    reasoning?: ReasoningLevel;
+    /** Tool/session hooks (global config only). */
+    hooks?: HooksConfig;
+    /** In-process plugin observers fired alongside the shell hooks (global config plugins). */
+    pluginEmit?: (event: HookEvent, payload?: {
+        tool?: string;
+        input?: unknown;
+        output?: string;
+    }) => Promise<void>;
+    /** Base environment handed to hook processes (defaults to the process env at spawn). */
+    env?: NodeJS.ProcessEnv;
+    /** Per-session token/USD budget (global config usageCap); blocks model calls once exceeded. */
+    usageCap?: UsageCap;
+    /** Model ref used to match usageCap.prices keys. */
+    budgetModel?: string;
+}
+export declare class Agent {
+    private readonly opts;
+    provider: Provider;
+    permissions: Permissions;
+    messages: ChatMessage[];
+    totalUsage: Usage;
+    lastInputTokens: number;
+    lastInputEstimated: boolean;
+    onEvent: (event: AgentEvent) => void;
+    reasoning: ReasoningLevel;
+    askPermission: AskPermission;
+    tools: Tool[];
+    private definitions;
+    private turnTools;
+    private turnDefinitions;
+    readonly readFiles: Set<string>;
+    private readonly webBudget;
+    private readonly maxSteps?;
+    private contextWindow;
+    private budgetModel;
+    private systemPrompt;
+    constructor(opts: AgentOptions);
+    setSystemPrompt(text: string): void;
+    setContextWindow(window: number): void;
+    getContextWindow(): number;
+    setBudgetModel(model: string): void;
+    getBudgetModel(): string;
+    setTools(tools: Tool[]): void;
+    private isParallelSafe;
+    private push;
+    private estimateCurrentInputTokens;
+    private seedEstimatedContext;
+    /** Publish the latest context after prompt/history changes, without changing session usage totals. */
+    private publishContextMetadata;
+    /** Swaps in another conversation (resume, new session) without writing to the session log. */
+    load(messages: ChatMessage[]): void;
+    clear(): void;
+    compact(signal: AbortSignal): Promise<void>;
+    /**
+     * Events of one tool execution. A cancelled turn gives up on a tool that does not stop, and whatever that tool
+     * reports later must not reach the screen or a newer turn, so this is per execution and not per call id (ids repeat).
+     */
+    private report;
+    run(text: string, signal: AbortSignal): Promise<void>;
+    /** Current cap status; undefined means the budget is not exhausted. */
+    private overBudget;
+    /** Every tool call needs an answer in the history, or the next request to the model is rejected. */
+    private cancelCalls;
+    /**
+     * Every tool call must resolve with text: a rejected one would leave the assistant tool_calls
+     * without answers, and the next request to the model would be rejected until a restart.
+     */
+    private runTool;
+    private executeTool;
+}

package/dist/agents.d.ts

@@ -0,0 +1,4 @@
+import type { AgentDef } from './extensions';
+export declare const EXPLORE_PROMPT = "You are a read-only research agent working for another agent. Search and read the codebase to answer the request. You cannot edit files or run commands. Reply with a concise report: the answer, the relevant file paths with line numbers, and nothing else.";
+export declare const GENERAL_PROMPT = "You are an agent handling a delegated task for another agent. Complete the task end to end with the tools you have, verify the result, and reply with a short report of what you did and what you found.";
+export declare const BUILTIN_AGENTS: AgentDef[];