From abecae116a4e66389597a27aa8f6f5737a2f45ee Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:16:58 +0000 Subject: [PATCH 1/9] TESTING.md and scripts/test-all.sh: every check, run locally One script runs what CI runs (fmt, clippy, the library, binary and sbx engine tests, the sandbox crate) plus the SDK and editor-extension suites when their toolchains are present, skipping and naming what it cannot run. TESTING.md lists each part, the Windows report script, the #[ignore]d live tests and the variables that enable them, and what to try by hand. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- README.md | 6 ++- TESTING.md | 84 +++++++++++++++++++++++++++++++++++++++++ scripts/test-all.sh | 91 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 180 insertions(+), 1 deletion(-) create mode 100644 TESTING.md create mode 100755 scripts/test-all.sh diff --git a/README.md b/README.md index f1ecbb9..93a83d0 100644 --- a/README.md +++ b/README.md @@ -1352,11 +1352,15 @@ The full list is in `docs/ROADMAP.md`. ## Development ```sh -cargo test # about 1,900 tests (1,878 library, 46 binary) +scripts/test-all.sh # everything CI runs, and the SDKs and editor extension +cargo test # about 2,100 tests (library and binary) cargo clippy --all-targets -- -D warnings cargo fmt ``` +[TESTING.md](TESTING.md) lists every suite, the Windows check, the live tests +that are off by default and what is worth trying by hand. + The documents under `docs/` are the input the loop reads, not decoration: `PRD.md` (what and why), `ARCHITECTURE.md` (the shape), `CONVENTIONS.md` (how the code should read), `ASSUMPTIONS.md` (what was decided without asking), diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 0000000..7397494 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,84 @@ +# Testing incode locally + +Everything CI runs, and the parts it cannot, from your own machine. + +## One command + +```sh +scripts/test-all.sh # every part this machine has the toolchain for +scripts/test-all.sh rust sbx # only some parts: rust sbx python ts vscode +QUICK=1 scripts/test-all.sh # the same without clippy (the slowest step) +``` + +A part whose toolchain (cargo, python3, npm) or folder is missing is skipped +and named in the summary; the exit code is non-zero when any part that ran +failed. + +On Linux, building incode needs the desktop backends' libraries: + +```sh +sudo apt-get install -y --no-install-recommends pkg-config clang libclang-dev \ + libwayland-dev libpipewire-0.3-dev libxcb1-dev libxcb-randr0-dev \ + libxcb-shm0-dev libdbus-1-dev libegl-dev libgbm-dev +``` + +The tests create git repositories and commit in them, so git needs a name and +an email (`git config --global user.name ...`, `user.email ...`). + +## The parts + +| Part | Commands | What it covers | +|---|---|---| +| rust | `cargo fmt --all -- --check` · `cargo clippy --all-targets -- -D warnings` · `cargo test --lib` · `cargo test --bins` | incode itself: about 2,100 library and 50 binary tests | +| rust | `cargo test --test sbx_engine` | Real shell commands run under `sandbox_engine = "sbx"`: a write outside the workspace refused (with an unconfined control), a planted git hook undone, `GIT_DIR` stripped. Linux; says it skipped elsewhere | +| sbx | `cargo clippy -p incord-sandbox --all-targets -- -D warnings` · `cargo test -p incord-sandbox` | The standalone sandbox: escape tests per OS, the MCP server, `.git` protection, WSL path translation | +| python | `python3 -m unittest discover -s sdk/python/tests -t sdk/python` | The Python SDK, against a fake incode | +| ts | `cd sdk/typescript && npm install && npm test` | The TypeScript SDK, against the same fake | +| vscode | `cd editors/vscode && npm install && npm run compile && npm test` | The VS Code extension's ACP client, against a fake agent | + +The SDK and extension suites also talk to the real binary when you point them +at one: `INCODE_BIN=$PWD/target/debug/incode` (build it first with +`cargo build`). + +## Windows + +From the incode folder, in PowerShell: + +```powershell +powershell -ExecutionPolicy Bypass -File scripts\test-windows.ps1 +``` + +It builds `sbx`, runs its Windows tests (writes outside the workspace, child +processes, the time, CPU and memory limits, killing `sbx`, the environment, +exit codes, the MCP server) and writes `sbx-windows-report.txt`. These need +real Windows: Wine cannot check Windows' own security. Nothing is installed +and nothing outside a temp folder is changed. + +The whole Rust suite runs on Windows too (`cargo test --lib`, `cargo test --bins`). + +## Live tests, off by default + +`#[ignore]`d because they touch the real machine or need a service. Run one +with `cargo test --lib -- --ignored --nocapture`. + +| Test | Needs | What it does | +|---|---|---| +| `sandbox::windows::acl` `live_*` | Windows; `INCODE_SANDBOX_LIVE_DIR` (a scratch folder) and `INCODE_SANDBOX_LIVE_BIN` (a built `incode.exe`) | Grants, confines and restores real ACLs; sweeps a crashed session's grant | +| `desktop::thread` (moves the cursor) | A desktop session you are not using | Moves the real mouse and puts it back | +| `desktop::capture::tests::live::report_real_capture` | A display | Captures the real screen and prints the coordinate mapping | +| `desktop::win32`, `desktop::uia` reports | Windows | Print the display table and the focused window's accessibility tree | +| `toolbox::code_edits_tests::live_an_unseen_change_is_refused_by_the_engine` | `INCODE_LIVE_MEMORY_URL` (a throwaway Incord Memory engine) and `INCODE_LIVE_REPO` | Checks the engine refuses an edit to code it has not seen | + +## By hand + +Things the suites cannot judge, worth a minute in a real terminal and editor: + +- `incode` in a terminal: the status line (`statusline_command`), `/vim`, + `/cost`, a notification after a long turn (`notify`), a custom command from + `.incode/commands/`, `/review`. +- `incode review` on a branch with a change; `incode mcp login ` against + a remote MCP server that needs a login; `incode plugin add` / `update`. +- `sandbox_engine = "sbx"` with `sandbox_allow_hosts`, then a command that + reaches an allowed host and one that does not. +- The VS Code extension (install the `.vsix` its README builds) and any ACP + editor (`incode --acp`). diff --git a/scripts/test-all.sh b/scripts/test-all.sh new file mode 100755 index 0000000..c0072ea --- /dev/null +++ b/scripts/test-all.sh @@ -0,0 +1,91 @@ +#!/bin/sh +# Run every check incode has, locally, the way CI does — and the parts CI +# cannot (the SDKs and the editor extension, when Node and Python are here). +# +# scripts/test-all.sh everything this machine can run +# scripts/test-all.sh rust only the named parts: rust sbx python ts vscode +# QUICK=1 scripts/test-all.sh skip clippy (the slowest step) +# +# A part whose toolchain is missing is skipped and said so; the exit code is +# non-zero when any part that ran failed. Run from anywhere inside the repo. +set -u + +root=$(cd "$(dirname "$0")/.." && pwd) +cd "$root" || exit 1 + +parts=${*:-"rust sbx python ts vscode"} +failed="" +skipped="" + +have() { command -v "$1" >/dev/null 2>&1; } + +step() { + name=$1 + shift + printf '\n== %s: %s\n' "$name" "$*" + if ! "$@"; then + failed="$failed\n $name: $*" + fi +} + +wants() { + case " $parts " in + *" $1 "*) return 0 ;; + *) return 1 ;; + esac +} + +if wants rust; then + if have cargo; then + step rust cargo fmt --all -- --check + [ -n "${QUICK:-}" ] || step rust cargo clippy --all-targets -- -D warnings + step rust cargo test --lib + step rust cargo test --bins + # Runs real commands under the sbx engine (Linux; it says it skipped + # elsewhere). + step rust cargo test --test sbx_engine + else + skipped="$skipped rust(cargo)" + fi +fi + +if wants sbx; then + if have cargo; then + [ -n "${QUICK:-}" ] || step sbx cargo clippy -p incord-sandbox --all-targets -- -D warnings + step sbx cargo test -p incord-sandbox + else + skipped="$skipped sbx(cargo)" + fi +fi + +if wants python; then + if have python3 && [ -d sdk/python ]; then + step python python3 -m unittest discover -s sdk/python/tests -t sdk/python + else + skipped="$skipped python" + fi +fi + +if wants ts; then + if have npm && [ -d sdk/typescript ]; then + step ts sh -c 'cd sdk/typescript && npm install --no-audit --no-fund && npm test' + else + skipped="$skipped ts" + fi +fi + +if wants vscode; then + if have npm && [ -d editors/vscode ]; then + step vscode sh -c 'cd editors/vscode && npm install --no-audit --no-fund && npm run compile && npm test' + else + skipped="$skipped vscode" + fi +fi + +printf '\n== summary\n' +[ -n "$skipped" ] && printf 'skipped (toolchain or folder missing):%s\n' "$skipped" +if [ -n "$failed" ]; then + printf 'FAILED:%b\n' "$failed" + exit 1 +fi +echo "all parts that ran passed" From e66c97a5b93d8d05ad787eb2c07694c6e922d749 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:32:28 +0000 Subject: [PATCH 2/9] editors/vscode: a VS Code extension that drives incode --acp A chat view (webview, strict CSP, model text rendered through text nodes only) with streamed text, tool calls, plan, permission buttons, mode and config pickers, slash-command completion, Stop and usage. fs/read_text_file returns open editor buffers; fs/write_text_file is an undoable WorkspaceEdit; both are limited to the workspace folders (symlinks resolved). The protocol client (src/acp.ts) has no vscode dependency and is tested with node:test against a fake agent, plus an optional test against the real binary (INCODE_BIN). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- editors/vscode/.gitignore | 3 + editors/vscode/.vscodeignore | 8 + editors/vscode/LICENSE | 176 +++++ editors/vscode/README.md | 127 ++++ editors/vscode/media/chat.css | 292 ++++++++ editors/vscode/media/chat.js | 412 +++++++++++ editors/vscode/media/icon.svg | 1 + editors/vscode/media/markdown.js | 252 +++++++ editors/vscode/package-lock.json | 59 ++ editors/vscode/package.json | 117 +++ editors/vscode/src/acp.ts | 786 +++++++++++++++++++++ editors/vscode/src/chatView.ts | 87 +++ editors/vscode/src/controller.ts | 428 +++++++++++ editors/vscode/src/extension.ts | 57 ++ editors/vscode/src/fsBridge.ts | 80 +++ editors/vscode/src/paths.ts | 111 +++ editors/vscode/src/selection.ts | 20 + editors/vscode/test/acp.test.ts | 416 +++++++++++ editors/vscode/test/controller.test.ts | 173 +++++ editors/vscode/test/fakeVscode.ts | 158 +++++ editors/vscode/test/fixtures/fake-agent.js | 214 ++++++ editors/vscode/test/markdown.test.ts | 103 +++ editors/vscode/test/paths.test.ts | 94 +++ editors/vscode/test/real-incode.test.ts | 47 ++ editors/vscode/tsconfig.json | 19 + 25 files changed, 4240 insertions(+) create mode 100644 editors/vscode/.gitignore create mode 100644 editors/vscode/.vscodeignore create mode 100644 editors/vscode/LICENSE create mode 100644 editors/vscode/README.md create mode 100644 editors/vscode/media/chat.css create mode 100644 editors/vscode/media/chat.js create mode 100644 editors/vscode/media/icon.svg create mode 100644 editors/vscode/media/markdown.js create mode 100644 editors/vscode/package-lock.json create mode 100644 editors/vscode/package.json create mode 100644 editors/vscode/src/acp.ts create mode 100644 editors/vscode/src/chatView.ts create mode 100644 editors/vscode/src/controller.ts create mode 100644 editors/vscode/src/extension.ts create mode 100644 editors/vscode/src/fsBridge.ts create mode 100644 editors/vscode/src/paths.ts create mode 100644 editors/vscode/src/selection.ts create mode 100644 editors/vscode/test/acp.test.ts create mode 100644 editors/vscode/test/controller.test.ts create mode 100644 editors/vscode/test/fakeVscode.ts create mode 100755 editors/vscode/test/fixtures/fake-agent.js create mode 100644 editors/vscode/test/markdown.test.ts create mode 100644 editors/vscode/test/paths.test.ts create mode 100644 editors/vscode/test/real-incode.test.ts create mode 100644 editors/vscode/tsconfig.json diff --git a/editors/vscode/.gitignore b/editors/vscode/.gitignore new file mode 100644 index 0000000..d3e15b1 --- /dev/null +++ b/editors/vscode/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +out/ +*.vsix diff --git a/editors/vscode/.vscodeignore b/editors/vscode/.vscodeignore new file mode 100644 index 0000000..f3e5c05 --- /dev/null +++ b/editors/vscode/.vscodeignore @@ -0,0 +1,8 @@ +src/** +test/** +out/test/** +**/*.map +**/*.ts +tsconfig.json +.gitignore +node_modules/** diff --git a/editors/vscode/LICENSE b/editors/vscode/LICENSE new file mode 100644 index 0000000..1b5ec8b --- /dev/null +++ b/editors/vscode/LICENSE @@ -0,0 +1,176 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS diff --git a/editors/vscode/README.md b/editors/vscode/README.md new file mode 100644 index 0000000..fe638d3 --- /dev/null +++ b/editors/vscode/README.md @@ -0,0 +1,127 @@ +# incode for VS Code + +A chat view for [incode](../../README.md) inside VS Code. The extension starts +`incode --acp` and talks to it over the Agent Client Protocol (ACP): +newline-delimited JSON-RPC 2.0 on the agent's stdin and stdout. incode does the +work; the extension is the client. + +## What it does + +- **Chat view** in its own activity-bar container (the `` icon). Streams the + agent's text (a small markdown subset, rendered as text nodes; model output + is never inserted as HTML, and the page runs under a strict + Content-Security-Policy), its thinking, each tool call with its status, + output and diffs, and the plan. +- **Slash commands**: type `/` for completion from the commands incode offers + (`available_commands_update`). Tab or Enter picks one. +- **Permission prompts** appear as buttons with the options the agent offers + (allow once / allow always / reject). +- **Pickers** for the session's mode (`read-only`, `workspace-write`, + `danger-full-access`) and its config options (incode offers the agent and + the role). +- **Stop** cancels the running turn (`session/cancel`); any open permission + question is answered `cancelled`. +- **Usage**: the context window's fill (`usage_update`), top right. +- **Files through the editor**: the extension advertises `fs.readTextFile` and + `fs.writeTextFile`. A read returns the open editor buffer, unsaved changes + included, when the file is open. A write is applied as a `WorkspaceEdit` + (visible, undoable with Ctrl+Z) and then saved. Both are refused for any + path outside the workspace folders, with symlinks resolved. (incode 0.1.0 + edits files with its own tools and does not send these requests yet; the + support is there for when it does.) +- The agent's stderr goes to the **incode** output channel. + +### Commands + +| Command | | +| --- | --- | +| `incode: Open Chat` (`incode.openChat`) | Show the chat view. The agent starts when the view first opens. | +| `incode: New Session` (`incode.newSession`) | Close the current session and start a fresh one on the same process. | +| `incode: Send Selection to Chat` (`incode.sendSelection`) | Put the selection (or the current line) into the chat input as `path:start-end` and a fenced block, so you can add your question. Also in the editor context menu. | +| `incode: Restart Agent` (`incode.restart`) | Stop the process and start it again. Use after changing settings or when it exits. | + +### Settings + +| Setting | Default | | +| --- | --- | --- | +| `incode.path` | `incode` | The binary. A bare name is looked up on `PATH`. | +| `incode.args` | `[]` | Extra arguments after `--acp`, e.g. `["-p", "read-only"]` or `["-m", ""]`. | + +The process runs with the first workspace folder as its working directory, and +the session is opened on that folder (`session/new` `cwd`). A window with no +folder open cannot start a session. + +## Build + +Requires Node.js 22 or newer (the test script uses `node --test` with a glob). + +```sh +cd editors/vscode +npm install # dev dependencies only: typescript, @types/node, @types/vscode +npm run compile # tsc, strict, into out/ +``` + +The extension has no runtime dependencies beyond the VS Code API. + +## Test + +```sh +npm test +``` + +compiles, then runs the unit tests with `node:test`, offline: + +- `test/acp.test.ts`: the ACP client (`src/acp.ts`) against a fake agent, + `test/fixtures/fake-agent.js`, a small Node script speaking the protocol on + stdio: initialize, session/new, a streamed prompt, set_mode and + set_config_option, the permission round trip, `fs/*` requests including + out-of-workspace refusal, cancel (also of an open permission question), + malformed lines, the agent exiting mid-turn, a missing binary. It also covers + the JSON-RPC layer over in-memory streams (framing, over-long lines, errors). +- `test/controller.test.ts`: the controller and the fs bridge with a minimal + fake `vscode` module (`test/fakeVscode.ts`) against the same fake agent: + what the chat view is sent for a turn, permission cards answered and + cancelled, reads returning unsaved buffers, writes going through a + `WorkspaceEdit`, refusals outside the workspace, link opening limited to + http(s), restart after the agent exits, and replay into a reopened view. + (Skipped on Windows, where the fixture cannot be run by its shebang.) +- `test/paths.test.ts`: the workspace path check as a pure function (POSIX + and Windows rules, `..`, prefix tricks, symlinks), line slicing for + `fs/read_text_file`, and the selection format. +- `test/markdown.test.ts`: the markdown-lite renderer never produces HTML from + model text and only links `http(s)` URLs. +- `test/real-incode.test.ts`: initialize and session/new against the real + binary. Skipped unless `INCODE_BIN` is set: + + ```sh + cargo build --release # at the repo root + INCODE_BIN="$PWD/../../target/release/incode" npm test + ``` + +To try the extension in a development host: open `editors/vscode` in VS Code, +run `npm run compile`, and press F5 ("Run Extension"), or run +`code --extensionDevelopmentPath="$PWD"`. + +## Package and install + +```sh +npm run package # runs `npx @vscode/vsce package`; needs network access the first time +code --install-extension incode-0.1.0.vsix +``` + +or in VS Code: Extensions view, `...` menu, **Install from VSIX...**. + +`vsce` is fetched by `npx` rather than listed as a dev dependency, to keep +`npm install` small; `npm test` does not need it. + +## Layout + +| Path | | +| --- | --- | +| `src/acp.ts` | The ACP client, independent of VS Code: framing, JSON-RPC correlation, notifications, agent→client requests (permission, fs) through callbacks, cancel, spawning. | +| `src/paths.ts` | The workspace path rule and line slicing. Pure. | +| `src/selection.ts` | The text `sendSelection` produces. Pure. | +| `src/fsBridge.ts` | `fs/read_text_file` and `fs/write_text_file` on top of the editor. | +| `src/controller.ts` | One agent process and session per window; between the agent and the view. | +| `src/chatView.ts` | The webview, its CSP and HTML shell. | +| `media/chat.js`, `media/markdown.js`, `media/chat.css` | The webview's script and styles. | diff --git a/editors/vscode/media/chat.css b/editors/vscode/media/chat.css new file mode 100644 index 0000000..fe6e911 --- /dev/null +++ b/editors/vscode/media/chat.css @@ -0,0 +1,292 @@ +html, +body { + height: 100%; + margin: 0; + padding: 0; +} +body { + display: flex; + flex-direction: column; + font-family: var(--vscode-font-family); + font-size: var(--vscode-font-size); + color: var(--vscode-foreground); + background: var(--vscode-sideBar-background, var(--vscode-editor-background)); +} +#bar { + display: flex; + flex-wrap: wrap; + gap: 6px 10px; + align-items: center; + padding: 6px 8px; + border-bottom: 1px solid var(--vscode-panel-border, transparent); +} +#config { + display: contents; +} +.picker { + display: inline-flex; + gap: 4px; + align-items: center; + color: var(--vscode-descriptionForeground); +} +select { + background: var(--vscode-dropdown-background); + color: var(--vscode-dropdown-foreground); + border: 1px solid var(--vscode-dropdown-border, transparent); + padding: 1px 4px; + max-width: 12em; +} +#usage { + margin-left: auto; + color: var(--vscode-descriptionForeground); + font-variant-numeric: tabular-nums; +} +#usage.mid { + color: var(--vscode-editorWarning-foreground); +} +#usage.high { + color: var(--vscode-editorError-foreground); +} +#status { + padding: 0 8px; + color: var(--vscode-descriptionForeground); +} +#status:empty { + display: none; +} +#status.error, +#status.stopped { + color: var(--vscode-errorForeground); + padding: 4px 8px; +} +#log { + flex: 1; + overflow-y: auto; + padding: 8px; +} +.msg { + margin: 0 0 10px; + line-height: 1.45; + overflow-wrap: anywhere; +} +.msg.user { + white-space: pre-wrap; + padding: 6px 8px; + border-radius: 4px; + background: var(--vscode-input-background); + border: 1px solid var(--vscode-input-border, transparent); +} +.msg.thought { + color: var(--vscode-descriptionForeground); + font-style: italic; + white-space: pre-wrap; +} +.label { + font-size: 0.85em; + text-transform: uppercase; + letter-spacing: 0.04em; + color: var(--vscode-descriptionForeground); + font-style: normal; +} +.msg p { + margin: 0 0 6px; +} +pre { + background: var(--vscode-textCodeBlock-background); + padding: 6px 8px; + border-radius: 3px; + overflow-x: auto; + font-family: var(--vscode-editor-font-family); + font-size: var(--vscode-editor-font-size); + margin: 4px 0; + white-space: pre; +} +code { + font-family: var(--vscode-editor-font-family); +} +p code, +li code { + background: var(--vscode-textCodeBlock-background); + padding: 0 3px; + border-radius: 3px; +} +a { + color: var(--vscode-textLink-foreground); +} +blockquote { + margin: 4px 0; + padding-left: 8px; + border-left: 3px solid var(--vscode-textBlockQuote-border); +} +.tool { + margin: 0 0 8px; + padding: 4px 6px; + border-left: 3px solid var(--vscode-panel-border, #8884); +} +.tool summary { + cursor: pointer; + display: flex; + gap: 6px; + align-items: baseline; +} +.tool-title { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + flex: 1; +} +.tool-kind, +.tool-loc { + color: var(--vscode-descriptionForeground); + font-size: 0.9em; +} +.tool-status { + font-size: 0.8em; + padding: 0 4px; + border-radius: 3px; + border: 1px solid currentColor; +} +.tool-status.completed { + color: var(--vscode-testing-iconPassed, green); +} +.tool-status.failed { + color: var(--vscode-errorForeground); +} +.tool-status.in_progress { + color: var(--vscode-progressBar-background); +} +.tool-output { + max-height: 16em; + overflow: auto; +} +.diff-path { + font-family: var(--vscode-editor-font-family); + margin-top: 4px; +} +.diff-old { + background: var(--vscode-diffEditor-removedTextBackground); +} +.diff-new { + background: var(--vscode-diffEditor-insertedTextBackground); +} +.permission { + margin: 0 0 10px; + padding: 8px; + border: 1px solid var(--vscode-focusBorder); + border-radius: 4px; +} +.permission.done { + border-color: var(--vscode-panel-border, #8884); + opacity: 0.8; +} +.permission-actions { + display: flex; + flex-wrap: wrap; + gap: 6px; + margin-top: 6px; +} +.permission-result { + margin-top: 4px; + color: var(--vscode-descriptionForeground); +} +.notice { + margin: 0 0 8px; + color: var(--vscode-descriptionForeground); +} +.notice.error { + color: var(--vscode-errorForeground); +} +#plan { + padding: 6px 8px; + border-top: 1px solid var(--vscode-panel-border, transparent); + max-height: 30%; + overflow-y: auto; +} +#plan ol { + margin: 4px 0 0; + padding-left: 20px; +} +.plan-completed { + text-decoration: line-through; + color: var(--vscode-descriptionForeground); +} +.plan-in_progress { + font-weight: bold; +} +footer { + position: relative; + padding: 6px 8px 8px; + border-top: 1px solid var(--vscode-panel-border, transparent); +} +textarea { + width: 100%; + box-sizing: border-box; + resize: vertical; + font-family: var(--vscode-font-family); + font-size: var(--vscode-font-size); + color: var(--vscode-input-foreground); + background: var(--vscode-input-background); + border: 1px solid var(--vscode-input-border, transparent); + padding: 4px 6px; +} +textarea:focus { + outline: 1px solid var(--vscode-focusBorder); +} +.actions { + display: flex; + justify-content: flex-end; + gap: 6px; + margin-top: 4px; +} +button { + background: var(--vscode-button-background); + color: var(--vscode-button-foreground); + border: none; + padding: 4px 12px; + border-radius: 2px; + cursor: pointer; +} +button:hover { + background: var(--vscode-button-hoverBackground); +} +button:disabled { + opacity: 0.5; + cursor: default; +} +button.secondary { + background: var(--vscode-button-secondaryBackground); + color: var(--vscode-button-secondaryForeground); +} +#completions { + position: absolute; + bottom: 100%; + left: 8px; + right: 8px; + margin: 0; + padding: 2px 0; + list-style: none; + max-height: 14em; + overflow-y: auto; + background: var(--vscode-editorSuggestWidget-background, var(--vscode-input-background)); + border: 1px solid var(--vscode-editorSuggestWidget-border, var(--vscode-focusBorder)); +} +#completions li { + display: flex; + gap: 6px; + padding: 2px 6px; + cursor: pointer; +} +#completions li.active { + background: var(--vscode-editorSuggestWidget-selectedBackground, var(--vscode-list-activeSelectionBackground)); + color: var(--vscode-editorSuggestWidget-selectedForeground, inherit); +} +#completions .cmd { + font-family: var(--vscode-editor-font-family); +} +#completions .hint, +#completions .desc { + color: var(--vscode-descriptionForeground); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} diff --git a/editors/vscode/media/chat.js b/editors/vscode/media/chat.js new file mode 100644 index 0000000..29099c3 --- /dev/null +++ b/editors/vscode/media/chat.js @@ -0,0 +1,412 @@ +// The chat view. Talks to the extension with postMessage only; every piece of +// text from the agent goes into the DOM through textContent (directly or via +// IncodeMarkdown.render), never innerHTML. +(function () { + "use strict"; + // eslint-disable-next-line no-undef + var vscode = acquireVsCodeApi(); + var md = self.IncodeMarkdown; + + var $ = function (id) { + return document.getElementById(id); + }; + var log = $("log"); + var input = $("input"); + var sendBtn = $("send"); + var stopBtn = $("stop"); + var statusEl = $("status"); + var planEl = $("plan"); + var usageEl = $("usage"); + var modeWrap = $("mode-wrap"); + var modeSel = $("mode"); + var configEl = $("config"); + var completions = $("completions"); + + var commands = []; + var running = false; + var current = null; // { kind: "agentText"|"thought", el, text } + var tools = {}; // toolCallId -> element + var permissions = {}; // key -> element + var renderPending = null; + + function el(tag, cls, text) { + var e = document.createElement(tag); + if (cls) e.className = cls; + if (text !== undefined && text !== null) e.textContent = String(text); + return e; + } + + function atBottom() { + return log.scrollHeight - log.scrollTop - log.clientHeight < 40; + } + function append(node) { + var stick = atBottom(); + log.appendChild(node); + if (stick) log.scrollTop = log.scrollHeight; + } + function openLink(url) { + vscode.postMessage({ type: "openLink", url: url }); + } + + function endStream() { + if (current && renderPending) flushRender(); + current = null; + } + + function flushRender() { + renderPending = null; + if (!current) return; + var stick = atBottom(); + if (current.kind === "thought") current.body.textContent = current.text; + else md.render(document, current.body, current.text, openLink); + if (stick) log.scrollTop = log.scrollHeight; + } + + function streamText(kind, text) { + if (!current || current.kind !== kind) { + endStream(); + var box = el("div", kind === "thought" ? "msg thought" : "msg agent"); + if (kind === "thought") box.appendChild(el("div", "label", "Thinking")); + var body = el("div", "body"); + box.appendChild(body); + append(box); + current = { kind: kind, el: box, body: body, text: "" }; + } + current.text += text; + if (!renderPending) renderPending = requestAnimationFrame(flushRender); + } + + var STATUS_TEXT = { pending: "pending", in_progress: "running", completed: "done", failed: "failed" }; + + function renderTool(call) { + var box = tools[call.toolCallId]; + if (!box) { + endStream(); + box = el("details", "tool"); + tools[call.toolCallId] = box; + append(box); + } + while (box.firstChild) box.removeChild(box.firstChild); + var status = call.status || "pending"; + box.setAttribute("data-status", status); + var summary = el("summary"); + summary.appendChild(el("span", "tool-status " + status, STATUS_TEXT[status] || status)); + summary.appendChild(el("span", "tool-title", call.title || "tool call")); + if (call.kind) summary.appendChild(el("span", "tool-kind", call.kind)); + box.appendChild(summary); + (call.locations || []).forEach(function (loc) { + box.appendChild(el("div", "tool-loc", loc.path + (loc.line ? ":" + loc.line : ""))); + }); + (call.content || []).forEach(function (c) { + if (c.type === "diff") { + var d = el("div", "diff"); + d.appendChild(el("div", "diff-path", c.path || "")); + if (c.oldText) d.appendChild(el("pre", "diff-old", c.oldText)); + d.appendChild(el("pre", "diff-new", c.newText || "")); + box.appendChild(d); + } else if (c.type === "content" && c.content) { + var text = c.content.type === "text" ? c.content.text : "[" + c.content.type + "]"; + box.appendChild(el("pre", "tool-output", text)); + } else if (c.type === "terminal") { + box.appendChild(el("div", "tool-loc", "terminal " + (c.terminalId || ""))); + } + }); + } + + function renderPlan(entries) { + while (planEl.firstChild) planEl.removeChild(planEl.firstChild); + if (!entries || entries.length === 0) { + planEl.hidden = true; + return; + } + planEl.hidden = false; + planEl.appendChild(el("div", "label", "Plan")); + var ol = el("ol"); + entries.forEach(function (e) { + var li = el("li", "plan-" + (e.status || "pending"), e.content); + li.title = (e.status || "pending") + (e.priority ? " · " + e.priority + " priority" : ""); + ol.appendChild(li); + }); + planEl.appendChild(ol); + } + + function renderPermission(m) { + endStream(); + var box = el("div", "permission"); + box.appendChild(el("div", "permission-title", m.title)); + var row = el("div", "permission-actions"); + m.options.forEach(function (o) { + var kind = String(o.kind || ""); + var b = el("button", /^reject/.test(kind) ? "secondary" : "", o.name); + b.type = "button"; + b.title = kind.replace(/_/g, " "); + b.addEventListener("click", function () { + vscode.postMessage({ type: "permission", key: m.key, optionId: o.optionId }); + }); + row.appendChild(b); + }); + box.appendChild(row); + box._options = m.options; + permissions[m.key] = box; + append(box); + } + + function permissionDone(m) { + var box = permissions[m.key]; + if (!box) return; + delete permissions[m.key]; + var row = box.querySelector(".permission-actions"); + if (row) box.removeChild(row); + var name = null; + (box._options || []).forEach(function (o) { + if (o.optionId === m.chosen) name = o.name; + }); + box.appendChild(el("div", "permission-result", m.chosen ? "Answered: " + (name || m.chosen) : "Cancelled")); + box.classList.add("done"); + } + + function flatOptions(options) { + var out = []; + (options || []).forEach(function (o) { + if (o && Array.isArray(o.options)) { + o.options.forEach(function (x) { + out.push(x); + }); + } else if (o) out.push(o); + }); + return out; + } + + function renderModes(modes) { + while (modeSel.firstChild) modeSel.removeChild(modeSel.firstChild); + if (!modes || !modes.availableModes || modes.availableModes.length === 0) { + modeWrap.hidden = true; + return; + } + modes.availableModes.forEach(function (m) { + var o = el("option", "", m.name); + o.value = m.id; + if (m.description) o.title = m.description; + modeSel.appendChild(o); + }); + modeSel.value = modes.currentModeId; + modeWrap.hidden = false; + } + + function renderConfig(options) { + while (configEl.firstChild) configEl.removeChild(configEl.firstChild); + (options || []).forEach(function (opt) { + if (opt.type !== "select") return; + var label = el("label", "picker"); + label.appendChild(document.createTextNode(opt.name + " ")); + if (opt.description) label.title = opt.description; + var sel = el("select"); + flatOptions(opt.options).forEach(function (o) { + var op = el("option", "", o.name); + op.value = o.value; + if (o.description) op.title = o.description; + sel.appendChild(op); + }); + sel.value = opt.currentValue; + sel.addEventListener("change", function () { + vscode.postMessage({ type: "setConfig", configId: opt.id, value: sel.value }); + }); + label.appendChild(sel); + configEl.appendChild(label); + }); + } + + function formatTokens(n) { + if (n >= 1000000) return (n / 1000000).toFixed(1) + "M"; + if (n >= 1000) return Math.round(n / 1000) + "k"; + return String(n); + } + + function renderUsage(m) { + var pct = m.size > 0 ? Math.round((m.used / m.size) * 100) : 0; + var text = formatTokens(m.used) + " / " + formatTokens(m.size) + " (" + pct + "%)"; + if (m.cost && typeof m.cost.amount === "number") text += " · " + m.cost.amount.toFixed(2) + " " + m.cost.currency; + usageEl.textContent = text; + usageEl.className = pct >= 90 ? "high" : pct >= 70 ? "mid" : ""; + } + + function setRunning(r) { + running = r; + stopBtn.hidden = !r; + sendBtn.disabled = r; + document.body.classList.toggle("running", r); + } + + function reset() { + while (log.firstChild) log.removeChild(log.firstChild); + current = null; + tools = {}; + permissions = {}; + renderPlan([]); + usageEl.textContent = ""; + } + + // ----- slash-command completion ----------------------------------------- + + var selected = 0; + var shown = []; + + function matches() { + var v = input.value; + var m = /^\/(\S*)$/.exec(v); + if (!m) return []; + var q = m[1].toLowerCase(); + return commands.filter(function (c) { + return c.name.toLowerCase().indexOf(q) === 0; + }); + } + + function updateCompletions() { + shown = matches(); + while (completions.firstChild) completions.removeChild(completions.firstChild); + if (shown.length === 0) { + completions.hidden = true; + return; + } + if (selected >= shown.length) selected = 0; + shown.forEach(function (c, i) { + var li = el("li", i === selected ? "active" : ""); + li.setAttribute("role", "option"); + li.appendChild(el("span", "cmd", "/" + c.name)); + if (c.input && c.input.hint) li.appendChild(el("span", "hint", c.input.hint)); + li.appendChild(el("span", "desc", c.description)); + li.addEventListener("mousedown", function (e) { + e.preventDefault(); + choose(i); + }); + completions.appendChild(li); + }); + completions.hidden = false; + } + + function choose(i) { + var c = shown[i]; + if (!c) return; + input.value = "/" + c.name + " "; + selected = 0; + updateCompletions(); + input.focus(); + } + + input.addEventListener("input", function () { + selected = 0; + updateCompletions(); + }); + input.addEventListener("keydown", function (e) { + if (!completions.hidden && shown.length > 0) { + if (e.key === "ArrowDown" || e.key === "ArrowUp") { + e.preventDefault(); + selected = (selected + (e.key === "ArrowDown" ? 1 : shown.length - 1)) % shown.length; + updateCompletions(); + return; + } + if (e.key === "Tab" || (e.key === "Enter" && !e.shiftKey)) { + e.preventDefault(); + choose(selected); + return; + } + if (e.key === "Escape") { + completions.hidden = true; + return; + } + } + if (e.key === "Enter" && !e.shiftKey && !e.isComposing) { + e.preventDefault(); + send(); + } + }); + + function send() { + var text = input.value; + if (!text.trim() || running) return; + vscode.postMessage({ type: "send", text: text }); + input.value = ""; + updateCompletions(); + } + + sendBtn.addEventListener("click", send); + stopBtn.addEventListener("click", function () { + vscode.postMessage({ type: "stop" }); + }); + modeSel.addEventListener("change", function () { + vscode.postMessage({ type: "setMode", modeId: modeSel.value }); + }); + + // ----- from the extension ----------------------------------------------- + + window.addEventListener("message", function (event) { + var m = event.data; + if (!m || typeof m.type !== "string") return; + switch (m.type) { + case "reset": + reset(); + break; + case "status": + statusEl.textContent = m.text || ""; + statusEl.className = m.state; + break; + case "user": + endStream(); + append(el("div", "msg user", m.text)); + break; + case "agentText": + streamText("agentText", m.text); + break; + case "thought": + streamText("thought", m.text); + break; + case "tool": + renderTool(m.call); + break; + case "plan": + renderPlan(m.entries); + break; + case "commands": + commands = Array.isArray(m.commands) ? m.commands : []; + updateCompletions(); + break; + case "modes": + renderModes(m.modes); + break; + case "mode": + modeSel.value = m.currentModeId; + break; + case "config": + renderConfig(m.configOptions); + break; + case "usage": + renderUsage(m); + break; + case "permission": + renderPermission(m); + break; + case "permissionDone": + permissionDone(m); + break; + case "turn": + if (!m.running) endStream(); + setRunning(!!m.running); + if (!m.running && m.stopReason && m.stopReason !== "end_turn") { + append(el("div", "notice", "Turn ended: " + m.stopReason.replace(/_/g, " "))); + } + break; + case "notice": + endStream(); + append(el("div", "notice " + (m.level || "info"), m.text)); + break; + case "prefill": + input.value = (input.value ? input.value.replace(/\s*$/, "\n") : "") + m.text; + input.focus(); + input.setSelectionRange(input.value.length, input.value.length); + break; + } + }); + + setRunning(false); + vscode.postMessage({ type: "ready" }); +})(); diff --git a/editors/vscode/media/icon.svg b/editors/vscode/media/icon.svg new file mode 100644 index 0000000..211330b --- /dev/null +++ b/editors/vscode/media/icon.svg @@ -0,0 +1 @@ + diff --git a/editors/vscode/media/markdown.js b/editors/vscode/media/markdown.js new file mode 100644 index 0000000..7fff1c9 --- /dev/null +++ b/editors/vscode/media/markdown.js @@ -0,0 +1,252 @@ +// Markdown-lite for the chat view. +// +// The model's text is NEVER turned into HTML. `parse` produces a small tree of +// plain objects; `render` builds DOM nodes from it with createElement and +// textContent only. A ` + + +`; + } +} diff --git a/editors/vscode/src/controller.ts b/editors/vscode/src/controller.ts new file mode 100644 index 0000000..c41f1e1 --- /dev/null +++ b/editors/vscode/src/controller.ts @@ -0,0 +1,428 @@ +/** + * One incode agent process and its current session, for this window, and the + * bridge between it and the chat view. + */ + +import * as vscode from "vscode"; +import { + AcpError, + AgentProcess, + AvailableCommand, + ConnectionClosedError, + PermissionOutcome, + RequestPermissionParams, + SessionConfigOption, + SessionModeState, + SessionNotification, + ToolCall, + mergeToolCall, + spawnAgent, + textOf, +} from "./acp"; +import { readTextFile, writeTextFile, workspaceRoots } from "./fsBridge"; + +/** A message to the webview. See media/chat.js for the receiving side. */ +export type ToView = + | { type: "reset" } + | { type: "status"; state: "stopped" | "starting" | "ready" | "error"; text: string } + | { type: "user"; text: string } + | { type: "agentText"; text: string } + | { type: "thought"; text: string } + | { type: "tool"; call: ToolCall } + | { type: "plan"; entries: unknown[] } + | { type: "commands"; commands: AvailableCommand[] } + | { type: "modes"; modes: SessionModeState | null } + | { type: "mode"; currentModeId: string } + | { type: "config"; configOptions: SessionConfigOption[] } + | { type: "usage"; used: number; size: number; cost?: { amount: number; currency: string } | null } + | { type: "permission"; key: number; title: string; options: { optionId: string; name: string; kind: string }[] } + | { type: "permissionDone"; key: number; chosen?: string } + | { type: "turn"; running: boolean; stopReason?: string } + | { type: "notice"; level: "info" | "error"; text: string } + | { type: "prefill"; text: string }; + +/** A message from the webview. */ +export type FromView = + | { type: "ready" } + | { type: "send"; text: string } + | { type: "stop" } + | { type: "permission"; key: number; optionId: string } + | { type: "setMode"; modeId: string } + | { type: "setConfig"; configId: string; value: string } + | { type: "openLink"; url: string } + | { type: "newSession" } + | { type: "restart" }; + +export interface View { + post(message: ToView): void; + reveal(): Promise; +} + +/** How many messages are kept to replay into a view that is opened again. */ +const REPLAY_LIMIT = 4000; + +export class Controller implements vscode.Disposable { + private agent?: AgentProcess; + private starting?: Promise; + private sessionId?: string; + private cwd?: string; + private running = false; + private tools = new Map(); + private permissionKey = 0; + private readonly permissions = new Map void>(); + private replay: ToView[] = []; + private view?: View; + + constructor( + private readonly output: vscode.OutputChannel, + private readonly version: string, + ) {} + + attach(view: View | undefined): void { + this.view = view; + } + + // ----- to the view ------------------------------------------------------- + + private post(message: ToView): void { + if (message.type === "reset") this.replay = []; + const last = this.replay[this.replay.length - 1]; + // Streamed text is kept as one entry per run, not one per chunk. + if (last && (message.type === "agentText" || message.type === "thought") && last.type === message.type) { + this.replay[this.replay.length - 1] = { type: message.type, text: last.text + message.text }; + } else { + this.replay.push(message); + if (this.replay.length > REPLAY_LIMIT) this.replay.splice(0, this.replay.length - REPLAY_LIMIT); + } + this.view?.post(message); + } + + /** The view (re)loaded: give it everything since the last reset. */ + private replayToView(): void { + if (!this.view) return; + this.view.post({ type: "reset" }); + for (const m of this.replay) if (m.type !== "reset") this.view.post(m); + this.view.post({ type: "turn", running: this.running }); + } + + private notice(level: "info" | "error", text: string): void { + this.post({ type: "notice", level, text }); + if (level === "error") this.output.appendLine(`[error] ${text}`); + } + + // ----- from the view ----------------------------------------------------- + + async onMessage(m: FromView): Promise { + switch (m.type) { + case "ready": + this.replayToView(); + if (!this.agent && !this.starting) void this.ensureSession().catch(() => undefined); + return; + case "send": + return this.send(m.text); + case "stop": + return this.stop(); + case "permission": { + const resolve = this.permissions.get(m.key); + if (resolve) resolve({ outcome: "selected", optionId: m.optionId }); + return; + } + case "setMode": + return this.setMode(m.modeId); + case "setConfig": + return this.setConfig(m.configId, m.value); + case "openLink": { + let uri: vscode.Uri; + try { + uri = vscode.Uri.parse(m.url, true); + } catch { + return; + } + if (uri.scheme === "http" || uri.scheme === "https") await vscode.env.openExternal(uri); + return; + } + case "newSession": + return this.newSession(); + case "restart": + return this.restart(); + } + } + + // ----- the agent --------------------------------------------------------- + + private settings(): { command: string; args: string[] } { + const cfg = vscode.workspace.getConfiguration("incode"); + const command = (cfg.get("path") ?? "incode").trim() || "incode"; + const args = (cfg.get("args") ?? []).filter((a): a is string => typeof a === "string"); + return { command, args }; + } + + private async ensureAgent(): Promise { + if (this.agent) return this.agent; + if (this.starting) return this.starting; + this.starting = this.startAgent().finally(() => (this.starting = undefined)); + return this.starting; + } + + private async startAgent(): Promise { + const roots = workspaceRoots(); + if (roots.length === 0) { + const text = "Open a folder first: incode works in a workspace folder."; + this.post({ type: "status", state: "error", text }); + throw new Error(text); + } + const cwd = roots[0]; + const { command, args } = this.settings(); + this.post({ type: "status", state: "starting", text: `Starting ${command} --acp…` }); + this.output.appendLine(`[start] ${command} --acp ${args.join(" ")} (cwd ${cwd})`); + const agent = spawnAgent({ + command, + args, + cwd, + handlers: { + requestPermission: (p, signal) => this.askPermission(p, signal), + readTextFile, + writeTextFile, + }, + onStderr: (text) => this.output.append(text), + }); + agent.client.on("update", (n: SessionNotification) => this.onUpdate(n)); + agent.client.on("protocolError", (d: string) => this.output.appendLine(`[protocol] ${d}`)); + agent.client.on("close", (reason: string) => { + if (this.agent !== agent) return; + this.agent = undefined; + this.sessionId = undefined; + this.running = false; + this.output.appendLine(`[stopped] ${reason}`); + this.post({ type: "turn", running: false }); + this.post({ type: "status", state: "stopped", text: `incode stopped: ${reason}` }); + }); + this.agent = agent; + this.cwd = cwd; + try { + const init = await agent.client.initialize({ name: "incode-vscode", title: "incode for VS Code", version: this.version }); + this.output.appendLine(`[ready] ${init.agentInfo?.title ?? init.agentInfo?.name ?? "agent"} ${init.agentInfo?.version ?? ""}`); + } catch (e) { + const text = describe(e); + this.post({ type: "status", state: "error", text: `Could not start incode: ${text}. Check the \`incode.path\` setting and the incode output.` }); + this.output.show(true); + await agent.stop(500); + if (this.agent === agent) this.agent = undefined; + throw e; + } + return agent; + } + + private async ensureSession(): Promise { + const agent = await this.ensureAgent(); + if (this.sessionId) return this.sessionId; + return this.openSession(agent); + } + + private opening?: Promise; + private early: SessionNotification[] = []; + + private openSession(agent: AgentProcess): Promise { + if (this.opening) return this.opening; + this.opening = (async () => { + this.post({ type: "status", state: "starting", text: "Opening a session…" }); + try { + const opened = await agent.client.newSession(this.cwd!); + this.sessionId = opened.sessionId; + this.tools.clear(); + this.post({ type: "reset" }); + this.post({ type: "modes", modes: opened.modes ?? null }); + this.post({ type: "config", configOptions: opened.configOptions ?? [] }); + this.post({ type: "status", state: "ready", text: "" }); + // Updates that arrived in the same read as the answer, before + // `sessionId` was known (the slash commands follow the answer). + const early = this.early.filter((n) => n.sessionId === opened.sessionId); + this.early = []; + for (const n of early) this.onUpdate(n); + return opened.sessionId; + } catch (e) { + this.post({ type: "status", state: "error", text: `Could not open a session: ${describe(e)}` }); + throw e; + } finally { + this.opening = undefined; + this.early = []; + } + })(); + return this.opening; + } + + async send(text: string): Promise { + const trimmed = text.trim(); + if (!trimmed) return; + if (this.running) { + this.notice("info", "A turn is still running. Stop it first, or wait for it to finish."); + return; + } + let sessionId: string; + try { + sessionId = await this.ensureSession(); + } catch { + return; + } + const agent = this.agent!; + this.running = true; + this.post({ type: "user", text: trimmed }); + this.post({ type: "turn", running: true }); + try { + const stopReason = await agent.client.prompt(sessionId, [{ type: "text", text: trimmed }]); + this.post({ type: "turn", running: false, stopReason }); + } catch (e) { + if (!(e instanceof ConnectionClosedError)) this.notice("error", describe(e)); + this.post({ type: "turn", running: false }); + } finally { + this.running = false; + } + } + + stop(): void { + if (this.agent && this.sessionId) this.agent.client.cancel(this.sessionId); + } + + private async setMode(modeId: string): Promise { + if (!this.agent || !this.sessionId) return; + try { + await this.agent.client.setMode(this.sessionId, modeId); + this.post({ type: "mode", currentModeId: modeId }); + } catch (e) { + this.notice("error", `Could not change mode: ${describe(e)}`); + } + } + + private async setConfig(configId: string, value: string): Promise { + if (!this.agent || !this.sessionId) return; + try { + const options = await this.agent.client.setConfigOption(this.sessionId, configId, value); + if (options) this.post({ type: "config", configOptions: options }); + } catch (e) { + this.notice("error", `Could not change ${configId}: ${describe(e)}`); + } + } + + async newSession(): Promise { + const agent = this.agent; + const old = this.sessionId; + if (agent && old) { + if (this.running) agent.client.cancel(old); + this.sessionId = undefined; + if (agent.client.supportsClose) { + agent.client.closeSession(old).catch((e) => this.output.appendLine(`[close] ${describe(e)}`)); + } + } + this.post({ type: "reset" }); + try { + await this.ensureSession(); + } catch { + /* shown in the view */ + } + } + + async restart(): Promise { + const agent = this.agent; + this.agent = undefined; + this.sessionId = undefined; + this.running = false; + if (agent) { + this.post({ type: "status", state: "starting", text: "Restarting…" }); + await agent.stop(); + } + this.post({ type: "reset" }); + try { + await this.ensureSession(); + } catch { + /* shown in the view */ + } + } + + prefill(text: string): void { + this.post({ type: "prefill", text }); + } + + // ----- agent → client ---------------------------------------------------- + + private onUpdate(n: SessionNotification): void { + if (this.sessionId === undefined && this.opening) { + if (this.early.length < 1000) this.early.push(n); + return; + } + if (n.sessionId !== this.sessionId) return; + const u = n.update as { sessionUpdate: string; [k: string]: unknown }; + switch (u.sessionUpdate) { + case "agent_message_chunk": + this.post({ type: "agentText", text: textOf(u.content as never) }); + return; + case "agent_thought_chunk": + this.post({ type: "thought", text: textOf(u.content as never) }); + return; + case "user_message_chunk": + this.post({ type: "user", text: textOf(u.content as never) }); + return; + case "tool_call": + case "tool_call_update": { + const id = String(u.toolCallId ?? ""); + if (!id) return; + const merged = mergeToolCall(this.tools.get(id), u as never); + this.tools.set(id, merged); + this.post({ type: "tool", call: merged }); + return; + } + case "plan": + this.post({ type: "plan", entries: Array.isArray(u.entries) ? u.entries : [] }); + return; + case "available_commands_update": + this.post({ type: "commands", commands: Array.isArray(u.availableCommands) ? (u.availableCommands as AvailableCommand[]) : [] }); + return; + case "current_mode_update": + if (typeof u.currentModeId === "string") this.post({ type: "mode", currentModeId: u.currentModeId }); + return; + case "config_option_update": + if (Array.isArray(u.configOptions)) this.post({ type: "config", configOptions: u.configOptions as SessionConfigOption[] }); + return; + case "usage_update": + if (typeof u.used === "number" && typeof u.size === "number") { + this.post({ type: "usage", used: u.used, size: u.size, cost: (u.cost as never) ?? null }); + } + return; + default: + // Updates this client does not show (session_info_update, …). + return; + } + } + + private askPermission(p: RequestPermissionParams, signal: AbortSignal): Promise { + const key = ++this.permissionKey; + const title = p.toolCall.title ?? this.tools.get(p.toolCall.toolCallId)?.title ?? "The agent asks for permission"; + return new Promise((resolve) => { + const finish = (outcome: PermissionOutcome): void => { + if (!this.permissions.delete(key)) return; + this.post({ type: "permissionDone", key, chosen: outcome.outcome === "selected" ? outcome.optionId : undefined }); + resolve(outcome); + }; + this.permissions.set(key, finish); + signal.addEventListener("abort", () => finish({ outcome: "cancelled" }), { once: true }); + this.post({ + type: "permission", + key, + title, + options: p.options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })), + }); + void this.view?.reveal(); + }); + } + + dispose(): void { + const agent = this.agent; + this.agent = undefined; + void agent?.stop(1000); + } +} + +function describe(e: unknown): string { + if (e instanceof AcpError) return e.describe(); + if (e instanceof Error) return e.message; + return String(e); +} diff --git a/editors/vscode/src/extension.ts b/editors/vscode/src/extension.ts new file mode 100644 index 0000000..27b83b6 --- /dev/null +++ b/editors/vscode/src/extension.ts @@ -0,0 +1,57 @@ +import * as vscode from "vscode"; +import { ChatViewProvider, VIEW_ID } from "./chatView"; +import { Controller } from "./controller"; +import { formatSelection } from "./selection"; + +export function activate(context: vscode.ExtensionContext): void { + const output = vscode.window.createOutputChannel("incode"); + const version = String((context.extension.packageJSON as { version?: string }).version ?? "0.0.0"); + const controller = new Controller(output, version); + const provider = new ChatViewProvider(context.extensionUri, controller); + controller.attach(provider); + + context.subscriptions.push( + output, + controller, + vscode.window.registerWebviewViewProvider(VIEW_ID, provider, { webviewOptions: { retainContextWhenHidden: true } }), + vscode.commands.registerCommand("incode.openChat", () => provider.reveal()), + vscode.commands.registerCommand("incode.newSession", async () => { + await provider.reveal(); + await controller.newSession(); + }), + vscode.commands.registerCommand("incode.restart", async () => { + await provider.reveal(); + await controller.restart(); + }), + vscode.commands.registerCommand("incode.sendSelection", async () => { + const editor = vscode.window.activeTextEditor; + if (!editor) { + void vscode.window.showInformationMessage("incode: no active editor."); + return; + } + const doc = editor.document; + const sel = editor.selection; + const range = sel.isEmpty ? doc.lineAt(sel.active.line).range : sel; + const text = formatSelection({ + path: vscode.workspace.asRelativePath(doc.uri, false), + languageId: doc.languageId, + startLine: range.start.line + 1, + endLine: range.end.character === 0 && range.end.line > range.start.line ? range.end.line : range.end.line + 1, + text: doc.getText(range), + }); + await provider.reveal(); + controller.prefill(text); + }), + vscode.workspace.onDidChangeConfiguration((e) => { + if (e.affectsConfiguration("incode.path") || e.affectsConfiguration("incode.args")) { + void vscode.window + .showInformationMessage("incode: restart the agent to use the new settings.", "Restart") + .then((choice) => (choice === "Restart" ? controller.restart() : undefined)); + } + }), + ); +} + +export function deactivate(): void { + // The controller is disposed with the subscriptions, which stops the agent. +} diff --git a/editors/vscode/src/fsBridge.ts b/editors/vscode/src/fsBridge.ts new file mode 100644 index 0000000..737be30 --- /dev/null +++ b/editors/vscode/src/fsBridge.ts @@ -0,0 +1,80 @@ +/** + * `fs/read_text_file` and `fs/write_text_file`, answered through the editor. + * + * - A read returns the open editor buffer when the file is open (unsaved + * changes included), and the file on disk otherwise. + * - A write is a WorkspaceEdit: it shows in the editor and can be undone. The + * document is then saved so the agent, which reads the disk too, sees it. + * - Both are refused for any path outside the workspace folders, symlinks + * resolved ({@link checkWorkspacePathReal}). + */ + +import * as vscode from "vscode"; +import { AcpError, ErrorCodes, ReadTextFileParams, WriteTextFileParams } from "./acp"; +import { checkWorkspacePathReal, currentPlatform, sliceLines } from "./paths"; + +export function workspaceRoots(): string[] { + return (vscode.workspace.workspaceFolders ?? []).filter((f) => f.uri.scheme === "file").map((f) => f.uri.fsPath); +} + +async function allowed(requested: string): Promise { + const check = await checkWorkspacePathReal(requested, workspaceRoots()); + if (!check.ok) throw new AcpError(ErrorCodes.InvalidParams, "Invalid params", `refused: ${check.reason}`); + return check.path; +} + +function samePath(a: string, b: string): boolean { + return currentPlatform() === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b; +} + +function openDocument(fsPath: string): vscode.TextDocument | undefined { + return vscode.workspace.textDocuments.find((d) => d.uri.scheme === "file" && samePath(d.uri.fsPath, fsPath)); +} + +async function exists(uri: vscode.Uri): Promise { + try { + await vscode.workspace.fs.stat(uri); + return true; + } catch { + return false; + } +} + +export async function readTextFile(params: ReadTextFileParams): Promise<{ content: string }> { + const fsPath = await allowed(params.path); + const open = openDocument(fsPath); + let text: string; + if (open) { + text = open.getText(); + } else { + try { + const bytes = await vscode.workspace.fs.readFile(vscode.Uri.file(fsPath)); + text = new TextDecoder("utf-8").decode(bytes); + } catch (e) { + throw new AcpError(ErrorCodes.ResourceNotFound, "Resource not found", `${params.path}: ${(e as Error).message}`); + } + } + return { content: sliceLines(text, params.line, params.limit) }; +} + +export async function writeTextFile(params: WriteTextFileParams): Promise { + const fsPath = await allowed(params.path); + const uri = vscode.Uri.file(fsPath); + const edit = new vscode.WorkspaceEdit(); + const metadata = { needsConfirmation: false, label: "incode: write file" }; + if (await exists(uri)) { + const doc = await vscode.workspace.openTextDocument(uri); + const all = new vscode.Range(doc.positionAt(0), doc.positionAt(doc.getText().length)); + edit.replace(uri, all, params.content, metadata); + } else { + edit.createFile(uri, { ignoreIfExists: true }, metadata); + edit.insert(uri, new vscode.Position(0, 0), params.content, metadata); + } + if (!(await vscode.workspace.applyEdit(edit))) { + throw new AcpError(ErrorCodes.InternalError, "Internal error", `the editor did not apply the write to ${params.path}`); + } + const doc = await vscode.workspace.openTextDocument(uri); + if (doc.isDirty && !(await doc.save())) { + throw new AcpError(ErrorCodes.InternalError, "Internal error", `the edit to ${params.path} was applied but could not be saved`); + } +} diff --git a/editors/vscode/src/paths.ts b/editors/vscode/src/paths.ts new file mode 100644 index 0000000..26c9dba --- /dev/null +++ b/editors/vscode/src/paths.ts @@ -0,0 +1,111 @@ +/** + * Which files the agent may read and write through the editor: only those + * inside one of the workspace folders. Pure functions, no `vscode`, so the + * rule is tested on its own. + */ + +import { promises as fs } from "node:fs"; +import * as nodePath from "node:path"; + +export type Platform = "posix" | "win32"; + +function api(platform: Platform): nodePath.PlatformPath { + return platform === "win32" ? nodePath.win32 : nodePath.posix; +} + +export function currentPlatform(): Platform { + return process.platform === "win32" ? "win32" : "posix"; +} + +/** + * Whether `candidate` lies inside `root` (or is `root` itself). Both must be + * absolute; they are normalised lexically (`..` and `.` resolved) first. + * Windows compares case-insensitively. + */ +export function isInside(root: string, candidate: string, platform: Platform = currentPlatform()): boolean { + const p = api(platform); + if (!p.isAbsolute(root) || !p.isAbsolute(candidate)) return false; + let r = p.resolve(root); + let c = p.resolve(candidate); + if (platform === "win32") { + r = r.toLowerCase(); + c = c.toLowerCase(); + } + const rel = p.relative(r, c); + if (rel === "") return true; + // `..foo` is a name inside root; `..` and `../x` (or `..\x`) are not. + const escapes = rel === ".." || rel.startsWith(`..${p.sep}`); + return !escapes && !p.isAbsolute(rel); +} + +export type PathCheck = { ok: true; path: string; root: string } | { ok: false; reason: string }; + +/** + * Decide whether the agent may touch `requested`. It must be an absolute path + * (ACP requires absolute paths) inside one of `roots`. Returns the normalised + * path, or why it was refused. + */ +export function checkWorkspacePath(requested: string, roots: readonly string[], platform: Platform = currentPlatform()): PathCheck { + const p = api(platform); + if (typeof requested !== "string" || requested.length === 0) return { ok: false, reason: "no path given" }; + if (requested.includes("\0")) return { ok: false, reason: "the path contains a NUL byte" }; + if (!p.isAbsolute(requested)) return { ok: false, reason: `\`${requested}\` is not an absolute path` }; + if (roots.length === 0) return { ok: false, reason: "no workspace folder is open" }; + const normalised = p.resolve(requested); + for (const root of roots) { + if (isInside(root, normalised, platform)) return { ok: true, path: normalised, root }; + } + return { ok: false, reason: `\`${requested}\` is outside the workspace folders` }; +} + +/** + * {@link checkWorkspacePath}, then the same check on the path with symlinks + * resolved: a link inside the workspace that points outside it is refused. + * For a path that does not exist yet, its nearest existing ancestor is + * resolved and the rest appended. + */ +export async function checkWorkspacePathReal( + requested: string, + roots: readonly string[], + realpath: (p: string) => Promise = (p) => fs.realpath(p), + platform: Platform = currentPlatform(), +): Promise { + const lexical = checkWorkspacePath(requested, roots, platform); + if (!lexical.ok) return lexical; + const p = api(platform); + const realRoots: string[] = []; + for (const root of roots) { + try { + realRoots.push(await realpath(root)); + } catch { + realRoots.push(root); + } + } + let existing = lexical.path; + const rest: string[] = []; + for (;;) { + try { + const real = await realpath(existing); + const full = rest.length ? p.join(real, ...rest.reverse()) : real; + const again = checkWorkspacePath(full, realRoots, platform); + return again.ok ? lexical : { ok: false, reason: `\`${requested}\` resolves outside the workspace folders` }; + } catch { + const parent = p.dirname(existing); + if (parent === existing) return lexical; + rest.push(p.basename(existing)); + existing = parent; + } + } +} + +/** + * The part of `text` that `fs/read_text_file` asked for: from 1-based `line`, + * at most `limit` lines. Line endings are kept as they are. + */ +export function sliceLines(text: string, line?: number | null, limit?: number | null): string { + if ((line === undefined || line === null) && (limit === undefined || limit === null)) return text; + const start = Math.max(1, Math.floor(line ?? 1)) - 1; + const lines = text.split(/(?<=\n)/); + const end = limit === undefined || limit === null ? lines.length : start + Math.max(0, Math.floor(limit)); + return lines.slice(start, end).join(""); +} diff --git a/editors/vscode/src/selection.ts b/editors/vscode/src/selection.ts new file mode 100644 index 0000000..4d6423b --- /dev/null +++ b/editors/vscode/src/selection.ts @@ -0,0 +1,20 @@ +/** The text `incode.sendSelection` puts in the chat input. Pure. */ + +export interface SelectionInfo { + /** Workspace-relative path, as shown to the person and the model. */ + path: string; + languageId: string; + /** 1-based, inclusive. */ + startLine: number; + endLine: number; + text: string; +} + +export function formatSelection(s: SelectionInfo): string { + const where = s.startLine === s.endLine ? `${s.path}:${s.startLine}` : `${s.path}:${s.startLine}-${s.endLine}`; + // A fence longer than any backtick run inside the text, so it cannot be closed early. + const longest = Math.max(0, ...(s.text.match(/`+/g) ?? []).map((r) => r.length)); + const fence = "`".repeat(Math.max(3, longest + 1)); + const body = s.text.endsWith("\n") ? s.text : `${s.text}\n`; + return `${where}\n${fence}${s.languageId}\n${body}${fence}\n`; +} diff --git a/editors/vscode/test/acp.test.ts b/editors/vscode/test/acp.test.ts new file mode 100644 index 0000000..dde56f4 --- /dev/null +++ b/editors/vscode/test/acp.test.ts @@ -0,0 +1,416 @@ +import { strict as assert } from "node:assert"; +import * as path from "node:path"; +import { PassThrough } from "node:stream"; +import { after, describe, it } from "node:test"; +import { + AcpClient, + AcpError, + AgentProcess, + ClientHandlers, + ConnectionClosedError, + JsonRpcConnection, + LineFramer, + PermissionOutcome, + RequestPermissionParams, + SessionNotification, + classifyLine, + flattenSelectOptions, + mergeToolCall, + spawnAgent, +} from "../src/acp"; +import { checkWorkspacePath, sliceLines } from "../src/paths"; + +const FAKE = path.resolve(__dirname, "..", "..", "test", "fixtures", "fake-agent.js"); +const WORKSPACE = path.resolve(__dirname, "..", "..", "test", "fixtures"); + +interface Harness { + agent: AgentProcess; + updates: SessionNotification[]; + stderr: string[]; + protocolErrors: string[]; + permissions: RequestPermissionParams[]; + /** The text of every agent_message_chunk so far. */ + said(): string; +} + +const started: AgentProcess[] = []; +after(async () => { + await Promise.all(started.map((a) => a.stop(200))); +}); + +function start(overrides: Partial = {}): Harness { + const updates: SessionNotification[] = []; + const stderr: string[] = []; + const protocolErrors: string[] = []; + const permissions: RequestPermissionParams[] = []; + const roots = [WORKSPACE]; + const handlers: ClientHandlers = { + async requestPermission(p) { + permissions.push(p); + return { outcome: "selected", optionId: "always" }; + }, + async readTextFile(p) { + const check = checkWorkspacePath(p.path, roots); + if (!check.ok) throw new AcpError(-32602, "Invalid params", `refused: ${check.reason}`); + return { content: sliceLines("one\ntwo\nthree\n", p.line, p.limit) }; + }, + async writeTextFile(p) { + const check = checkWorkspacePath(p.path, roots); + if (!check.ok) throw new AcpError(-32602, "Invalid params", `refused: ${check.reason}`); + }, + ...overrides, + }; + const agent = spawnAgent({ + command: process.execPath, + prefixArgs: [FAKE], + cwd: WORKSPACE, + handlers, + onStderr: (t) => stderr.push(t), + }); + started.push(agent); + agent.client.on("update", (n: SessionNotification) => updates.push(n)); + agent.client.on("protocolError", (d: string) => protocolErrors.push(d)); + return { + agent, + updates, + stderr, + protocolErrors, + permissions, + said: () => + updates + .filter((u) => u.update.sessionUpdate === "agent_message_chunk") + .map((u) => (u.update as { content: { text: string } }).content.text) + .join(""), + }; +} + +async function ready(h: Harness): Promise { + await h.agent.client.initialize({ name: "test", version: "0" }); + const s = await h.agent.client.newSession(WORKSPACE); + return s.sessionId; +} + +describe("AcpClient against the fake agent", () => { + it("initialize → session/new → a streamed prompt", async () => { + const h = start(); + const init = await h.agent.client.initialize({ name: "test", version: "0" }); + assert.equal(init.protocolVersion, 1); + assert.deepEqual( + (init.agentInfo as unknown as { clientCapabilitiesSeen: unknown }).clientCapabilitiesSeen, + { fs: { readTextFile: true, writeTextFile: true }, terminal: false }, + "the client advertises fs read/write", + ); + assert.equal(h.agent.client.supportsClose, true); + const session = await h.agent.client.newSession(WORKSPACE); + assert.equal(session.sessionId, "sess-1"); + assert.equal(session.modes?.currentModeId, "workspace-write"); + assert.equal(session.configOptions?.[0].id, "agent"); + + const stop = await h.agent.client.prompt(session.sessionId, [{ type: "text", text: "stream" }]); + assert.equal(stop, "end_turn"); + assert.equal(h.said(), "Hello, world"); + const kinds = h.updates.map((u) => u.update.sessionUpdate); + assert.deepEqual(kinds, [ + "available_commands_update", + "agent_message_chunk", + "agent_message_chunk", + "agent_message_chunk", + "tool_call", + "tool_call_update", + "plan", + "usage_update", + ]); + // Updates arrive before the prompt's answer, in order; the tool call folds. + let call = undefined; + for (const u of h.updates) { + if (u.update.sessionUpdate === "tool_call" || u.update.sessionUpdate === "tool_call_update") { + call = mergeToolCall(call, u.update as never); + } + } + assert.equal(call?.title, "Read file"); + assert.equal(call?.status, "completed"); + assert.equal(call?.content?.length, 1); + assert.match(h.stderr.join(""), /fake agent ready/); + }); + + it("set_mode and set_config_option", async () => { + const h = start(); + const id = await ready(h); + await h.agent.client.setMode(id, "read-only"); + const options = await h.agent.client.setConfigOption(id, "agent", "codex"); + assert.equal(options?.[0].currentValue, "codex"); + }); + + it("a permission round trip", async () => { + const h = start(); + const id = await ready(h); + await h.agent.client.prompt(id, [{ type: "text", text: "permission" }]); + assert.equal(h.permissions.length, 1); + assert.equal(h.permissions[0].toolCall.toolCallId, "t2"); + assert.deepEqual( + h.permissions[0].options.map((o) => o.kind), + ["allow_once", "allow_always", "reject_once"], + ); + assert.equal(h.said(), "chose always"); + }); + + it("an option the agent did not offer is answered as cancelled", async () => { + const h = start({ requestPermission: async () => ({ outcome: "selected", optionId: "made-up" }) }); + const id = await ready(h); + await h.agent.client.prompt(id, [{ type: "text", text: "permission" }]); + assert.equal(h.said(), "chose nothing"); + }); + + it("fs/read_text_file inside the workspace, with line and limit", async () => { + const h = start(); + const id = await ready(h); + await h.agent.client.prompt(id, [{ type: "text", text: `read ${path.join(WORKSPACE, "a.txt")} 2 1` }]); + assert.equal(h.said(), "content: two\n"); + }); + + it("fs requests outside the workspace are refused", async () => { + const h = start(); + const id = await ready(h); + const outside = path.resolve(WORKSPACE, "..", "..", "package.json"); + await h.agent.client.prompt(id, [{ type: "text", text: `read ${outside}` }]); + assert.match(h.said(), /^error -32602: refused: .* is outside the workspace folders$/); + const before = h.said().length; + await h.agent.client.prompt(id, [{ type: "text", text: `write ${path.join(WORKSPACE, "..", "escape.txt")} hi` }]); + assert.match(h.said().slice(before), /^error -32602: refused/); + const before2 = h.said().length; + await h.agent.client.prompt(id, [{ type: "text", text: `write relative/path.txt hi` }]); + assert.match(h.said().slice(before2), /^error -32602: refused: .*not an absolute path/); + }); + + it("fs/write_text_file inside the workspace answers {}", async () => { + const h = start(); + const id = await ready(h); + await h.agent.client.prompt(id, [{ type: "text", text: `write ${path.join(WORKSPACE, "new.txt")} some words` }]); + assert.equal(h.said(), "wrote {}"); + }); + + it("fs requests without handlers are 'method not found'", async () => { + const h = start({ readTextFile: undefined }); + const id = await ready(h); + await h.agent.client.prompt(id, [{ type: "text", text: `read ${path.join(WORKSPACE, "a.txt")}` }]); + assert.match(h.said(), /^error -32601/); + }); + + it("an unknown agent→client request is answered 'method not found'", async () => { + const h = start(); + const id = await ready(h); + await h.agent.client.prompt(id, [{ type: "text", text: "unknown" }]); + assert.equal(h.said(), "code -32601"); + }); + + it("cancel ends a running prompt with `cancelled`", async () => { + const h = start(); + const id = await ready(h); + const running = h.agent.client.prompt(id, [{ type: "text", text: "hang" }]); + while (!h.said().includes("working")) await new Promise((r) => setTimeout(r, 5)); + h.agent.client.cancel(id); + assert.equal(await running, "cancelled"); + }); + + it("cancel answers an open permission question `cancelled`", async () => { + let aborted = false; + let asked = false; + const h = start({ + requestPermission: (_p, signal) => + new Promise(() => { + // Never answered by the person; the cancel must answer it. + asked = true; + signal.addEventListener("abort", () => (aborted = true)); + }), + }); + const id = await ready(h); + const running = h.agent.client.prompt(id, [{ type: "text", text: "permission-hang" }]); + while (!asked) await new Promise((r) => setTimeout(r, 5)); + h.agent.client.cancel(id); + assert.equal(await running, "cancelled"); + assert.equal(h.said(), 'after cancel: {"outcome":{"outcome":"cancelled"}}'); + assert.equal(aborted, true, "the handler is told to take its prompt down"); + }); + + it("malformed lines are reported and skipped; the session carries on", async () => { + const h = start(); + const id = await ready(h); + const stop = await h.agent.client.prompt(id, [{ type: "text", text: "garbage" }]); + assert.equal(stop, "end_turn"); + assert.equal(h.said(), "still here"); + assert.equal(h.protocolErrors.length, 3, h.protocolErrors.join("\n")); + assert.match(h.protocolErrors[0], /Parse error/); + assert.match(h.protocolErrors[1], /one JSON-RPC object per line/); + assert.match(h.protocolErrors[2], /unknown request id "nobody"/); + // The update without `update` was dropped, not delivered half-formed. + assert.ok(h.updates.every((u) => u.update && typeof u.update.sessionUpdate === "string")); + }); + + it("the agent exiting mid-turn rejects the pending prompt and emits close", async () => { + const h = start(); + const id = await ready(h); + const closed = new Promise((r) => h.agent.client.once("close", r)); + await assert.rejects(h.agent.client.prompt(id, [{ type: "text", text: "exit" }]), (e: unknown) => { + assert.ok(e instanceof ConnectionClosedError); + return true; + }); + assert.match(await closed, /agent (exited|closed)/); + const how = await h.agent.exited; + assert.equal(how.code, 3); + await assert.rejects(h.agent.client.newSession(WORKSPACE), ConnectionClosedError, "later requests fail at once"); + }); + + it("a binary that does not exist fails cleanly", async () => { + const agent = spawnAgent({ + command: path.join(WORKSPACE, "no-such-incode"), + cwd: WORKSPACE, + handlers: { requestPermission: async () => ({ outcome: "cancelled" }) }, + }); + await assert.rejects(agent.client.initialize({ name: "t", version: "0" }), ConnectionClosedError); + const how = await agent.exited; + assert.ok(how.error, "the spawn error is reported"); + }); + + it("stop() closes stdin and the agent exits", async () => { + const h = start(); + await ready(h); + await h.agent.stop(2000); + const how = await h.agent.exited; + assert.equal(how.code, 0); + }); +}); + +describe("JsonRpcConnection over in-memory streams", () => { + function pair(): { conn: JsonRpcConnection; toClient: PassThrough; fromClient: string[] } { + const toClient = new PassThrough(); + const out = new PassThrough(); + const fromClient: string[] = []; + out.on("data", (d: Buffer) => fromClient.push(...d.toString("utf8").split("\n").filter(Boolean))); + return { conn: new JsonRpcConnection(toClient, out, 256), toClient, fromClient }; + } + + it("correlates responses by id, in any order, and maps errors", async () => { + const { conn, toClient, fromClient } = pair(); + const a = conn.request("a"); + const b = conn.request("b"); + await new Promise((r) => setImmediate(r)); + const [ra, rb] = fromClient.map((l) => JSON.parse(l)); + toClient.write(JSON.stringify({ jsonrpc: "2.0", id: rb.id, error: { code: -32602, message: "bad", data: "why" } }) + "\n"); + toClient.write(JSON.stringify({ jsonrpc: "2.0", id: ra.id, result: { ok: 1 } }) + "\n"); + assert.deepEqual(await a, { ok: 1 }); + await assert.rejects(b, (e: unknown) => e instanceof AcpError && e.code === -32602 && e.describe() === "bad: why"); + }); + + it("a request split across chunks with CRLF still arrives", async () => { + const { conn, toClient, fromClient } = pair(); + conn.onRequest("ping", (p) => ({ pong: p })); + const line = JSON.stringify({ jsonrpc: "2.0", id: 9, method: "ping", params: 1 }); + toClient.write(line.slice(0, 10)); + toClient.write(line.slice(10) + "\r\n"); + await new Promise((r) => setTimeout(r, 10)); + assert.deepEqual(JSON.parse(fromClient[0]), { jsonrpc: "2.0", id: 9, result: { pong: 1 } }); + }); + + it("an over-long line is dropped and the next one still arrives", async () => { + const { conn, toClient } = pair(); + const errors: string[] = []; + const seen: string[] = []; + conn.on("protocolError", (d: string) => errors.push(d)); + conn.onNotification((m) => seen.push(m)); + toClient.write("x".repeat(1000) + "\n"); + toClient.write(JSON.stringify({ jsonrpc: "2.0", method: "n" }) + "\n"); + await new Promise((r) => setTimeout(r, 10)); + assert.equal(errors.length, 1); + assert.match(errors[0], /longer than 256 bytes/); + assert.deepEqual(seen, ["n"]); + }); + + it("a request it cannot read is answered with its own id", async () => { + const { toClient, fromClient } = pair(); + toClient.write(JSON.stringify({ id: 4, method: "x" }) + "\n"); + await new Promise((r) => setTimeout(r, 10)); + const reply = JSON.parse(fromClient[0]); + assert.equal(reply.id, 4); + assert.equal(reply.error.code, -32600); + }); + + it("a handler that throws answers an internal error", async () => { + const { conn, toClient, fromClient } = pair(); + conn.onRequest("boom", () => { + throw new Error("kaput"); + }); + toClient.write(JSON.stringify({ jsonrpc: "2.0", id: "q", method: "boom" }) + "\n"); + await new Promise((r) => setTimeout(r, 10)); + const reply = JSON.parse(fromClient[0]); + assert.equal(reply.id, "q"); + assert.equal(reply.error.code, -32603); + assert.equal(reply.error.data, "kaput"); + }); + + it("end of input rejects everything pending", async () => { + const { conn, toClient } = pair(); + const p = conn.request("never"); + toClient.end(); + await assert.rejects(p, ConnectionClosedError); + assert.equal(conn.isClosed, true); + }); + + it("the AcpClient drops session/update without a valid shape", async () => { + const { conn, toClient } = pair(); + const client = new AcpClient(conn, { requestPermission: async () => ({ outcome: "cancelled" }) }); + const got: unknown[] = []; + client.on("update", (u) => got.push(u)); + toClient.write(JSON.stringify({ jsonrpc: "2.0", method: "session/update", params: { sessionId: 1 } }) + "\n"); + toClient.write( + JSON.stringify({ + jsonrpc: "2.0", + method: "session/update", + params: { sessionId: "s", update: { sessionUpdate: "plan", entries: [] } }, + }) + "\n", + ); + await new Promise((r) => setTimeout(r, 10)); + assert.equal(got.length, 1); + }); +}); + +describe("pure helpers", () => { + it("classifyLine", () => { + assert.equal(classifyLine("nope").kind, "invalid"); + assert.equal(classifyLine("[]").kind, "invalid"); + assert.deepEqual(classifyLine('{"jsonrpc":"2.0","method":"m"}'), { kind: "notification", method: "m", params: undefined }); + assert.equal(classifyLine('{"jsonrpc":"2.0","id":1,"method":"m"}').kind, "request"); + assert.equal(classifyLine('{"jsonrpc":"2.0","id":1,"result":null}').kind, "response"); + const bad = classifyLine('{"jsonrpc":"1.0","id":"z","method":"m"}'); + assert.equal(bad.kind, "invalid"); + assert.equal(bad.kind === "invalid" && bad.id, "z"); + }); + + it("LineFramer keeps the last unterminated line and handles UTF-8 split across chunks", () => { + const lines: string[] = []; + const f = new LineFramer((l) => lines.push(l), () => lines.push(""), 100); + const bytes = Buffer.from("héllo\nwörld", "utf8"); + f.push(bytes.subarray(0, 2)); + f.push(bytes.subarray(2, 9)); + f.push(bytes.subarray(9)); + f.end(); + assert.deepEqual(lines, ["héllo", "wörld"]); + }); + + it("mergeToolCall keeps fields an update leaves out", () => { + const a = mergeToolCall(undefined, { toolCallId: "1", title: "Edit x", kind: "edit", status: "pending" }); + const b = mergeToolCall(a, { toolCallId: "1", status: "in_progress" }); + const c = mergeToolCall(b, { toolCallId: "1", status: "failed", title: undefined }); + assert.deepEqual(c, { toolCallId: "1", title: "Edit x", kind: "edit", status: "failed" }); + assert.equal(mergeToolCall(undefined, { toolCallId: "z" }).title, "tool call"); + }); + + it("flattenSelectOptions flattens groups", () => { + assert.deepEqual( + flattenSelectOptions([ + { group: "g", name: "G", options: [{ value: "a", name: "A" }] }, + { value: "b", name: "B" }, + ] as never).map((o) => o.value), + ["a", "b"], + ); + }); +}); diff --git a/editors/vscode/test/controller.test.ts b/editors/vscode/test/controller.test.ts new file mode 100644 index 0000000..b6bef55 --- /dev/null +++ b/editors/vscode/test/controller.test.ts @@ -0,0 +1,173 @@ +// The controller and the fs bridge, end to end against the fake agent, with +// a fake `vscode` module. Checks what the chat view is sent. +import { strict as assert } from "node:assert"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { after, before, describe, it } from "node:test"; +import type * as ControllerModule from "../src/controller"; +import { FakeDocument, FakeState, installFakeVscode, makeFakeVscode } from "./fakeVscode"; + +const FAKE = path.resolve(__dirname, "..", "..", "test", "fixtures", "fake-agent.js"); + +const state: FakeState = { roots: [], config: { path: FAKE, args: [] }, documents: [], applied: [], opened: [] }; +installFakeVscode(makeFakeVscode(state)); +// eslint-disable-next-line @typescript-eslint/no-require-imports +const { Controller } = require("../src/controller") as typeof ControllerModule; + +type ToView = ControllerModule.ToView; + +describe("Controller with the fake agent", { skip: process.platform === "win32" ? "runs the fixture by its shebang" : false }, () => { + let ws: string; + let controller: InstanceType; + const posted: ToView[] = []; + const logged: string[] = []; + + async function until(pred: () => boolean, what: string): Promise { + const deadline = Date.now() + 5000; + while (!pred()) { + if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}; got ${JSON.stringify(posted.map((m) => m.type))}`); + await new Promise((r) => setTimeout(r, 5)); + } + } + const said = () => + posted + .filter((m): m is Extract => m.type === "agentText") + .map((m) => m.text) + .join(""); + + before(async () => { + ws = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "incode-vscode-ctl-"))); + state.roots = [ws]; + const output = { append: (s: string) => logged.push(s), appendLine: (s: string) => logged.push(s + "\n"), show: () => undefined }; + controller = new Controller(output as never, "0.0.0-test"); + controller.attach({ post: (m) => posted.push(m), reveal: async () => undefined }); + }); + after(async () => { + controller.dispose(); + await new Promise((r) => setTimeout(r, 100)); + await fs.rm(ws, { recursive: true, force: true }); + }); + + it("opens a session when the view is ready, with modes, config and slash commands", async () => { + await controller.onMessage({ type: "ready" }); + await until(() => posted.some((m) => m.type === "commands"), "the slash commands"); + const modes = posted.find((m) => m.type === "modes") as Extract; + assert.equal(modes.modes?.currentModeId, "workspace-write"); + const config = posted.find((m) => m.type === "config") as Extract; + assert.equal(config.configOptions[0].id, "agent"); + const commands = posted.find((m) => m.type === "commands") as Extract; + assert.deepEqual(commands.commands.map((c) => c.name), ["undo"]); + assert.match(logged.join(""), /fake agent ready/, "stderr goes to the output channel"); + }); + + it("streams a turn: text, the merged tool call, plan, usage, turn end", async () => { + posted.length = 0; + await controller.onMessage({ type: "send", text: "stream" }); + assert.equal(said(), "Hello, world"); + const tools = posted.filter((m) => m.type === "tool") as Extract[]; + assert.equal(tools.length, 2); + assert.equal(tools[1].call.title, "Read file", "the update keeps the title"); + assert.equal(tools[1].call.status, "completed"); + assert.ok(posted.some((m) => m.type === "plan")); + assert.ok(posted.some((m) => m.type === "usage" && m.used === 1000 && m.size === 200000)); + assert.deepEqual(posted.at(-1), { type: "turn", running: false, stopReason: "end_turn" }); + }); + + it("a permission question is answered from the view", async () => { + posted.length = 0; + const turn = controller.onMessage({ type: "send", text: "permission" }); + await until(() => posted.some((m) => m.type === "permission"), "the permission card"); + const card = posted.find((m) => m.type === "permission") as Extract; + assert.equal(card.title, "Run `rm -rf build`"); + assert.deepEqual(card.options.map((o) => o.optionId), ["allow", "always", "reject"]); + await controller.onMessage({ type: "permission", key: card.key, optionId: "reject" }); + await turn; + assert.equal(said(), "chose reject"); + assert.ok(posted.some((m) => m.type === "permissionDone" && m.key === card.key && m.chosen === "reject")); + }); + + it("Stop cancels the turn and takes down an open permission card", async () => { + posted.length = 0; + const turn = controller.onMessage({ type: "send", text: "permission-hang" }); + await until(() => posted.some((m) => m.type === "permission"), "the permission card"); + await controller.onMessage({ type: "stop" }); + await turn; + assert.ok(posted.some((m) => m.type === "permissionDone" && m.chosen === undefined)); + assert.deepEqual(posted.at(-1), { type: "turn", running: false, stopReason: "cancelled" }); + }); + + it("fs/read_text_file returns the unsaved buffer of an open file", async () => { + const file = path.join(ws, "open.txt"); + await fs.writeFile(file, "on disk\n"); + state.documents.push(new FakeDocument(file, "in the editor\n")); + posted.length = 0; + await controller.onMessage({ type: "send", text: `read ${file}` }); + assert.equal(said(), "content: in the editor\n"); + const other = path.join(ws, "closed.txt"); + await fs.writeFile(other, "from disk\n"); + posted.length = 0; + await controller.onMessage({ type: "send", text: `read ${other}` }); + assert.equal(said(), "content: from disk\n"); + posted.length = 0; + await controller.onMessage({ type: "send", text: `read ${path.join(ws, "missing.txt")}` }); + assert.match(said(), /^error -32002/); + }); + + it("fs/write_text_file goes through a WorkspaceEdit and is saved", async () => { + const file = path.join(ws, "sub", "new.txt"); + posted.length = 0; + state.applied.length = 0; + await controller.onMessage({ type: "send", text: `write ${file} hello there` }); + assert.equal(said(), "wrote {}"); + assert.equal(state.applied.length, 1); + assert.deepEqual(state.applied[0].ops.map((o) => o.kind), ["create", "insert"]); + assert.equal(await fs.readFile(file, "utf8"), "hello there"); + + posted.length = 0; + await controller.onMessage({ type: "send", text: `write ${file} replaced` }); + assert.deepEqual(state.applied[1].ops.map((o) => o.kind), ["replace"]); + assert.equal(await fs.readFile(file, "utf8"), "replaced"); + }); + + it("fs requests outside the workspace are refused, and nothing is written", async () => { + const outside = path.join(path.dirname(ws), `outside-${path.basename(ws)}.txt`); + posted.length = 0; + state.applied.length = 0; + await controller.onMessage({ type: "send", text: `write ${outside} nope` }); + assert.match(said(), /^error -32602: refused: .*outside the workspace folders/); + assert.equal(state.applied.length, 0); + await assert.rejects(fs.stat(outside)); + }); + + it("set_config_option sends the agent's new options to the view; links open only for http(s)", async () => { + posted.length = 0; + await controller.onMessage({ type: "setConfig", configId: "agent", value: "codex" }); + const config = posted.find((m) => m.type === "config") as Extract; + assert.equal(config.configOptions[0].currentValue, "codex"); + await controller.onMessage({ type: "openLink", url: "https://example.com/x" }); + await controller.onMessage({ type: "openLink", url: "command:workbench.action.quit" }); + await controller.onMessage({ type: "openLink", url: "file:///etc/passwd" }); + assert.deepEqual(state.opened, ["https://example.com/x"]); + }); + + it("the agent exiting is shown, and restart brings a new session", async () => { + posted.length = 0; + await controller.onMessage({ type: "send", text: "exit" }); + await until(() => posted.some((m) => m.type === "status" && m.state === "stopped"), "the stopped status"); + posted.length = 0; + await controller.restart(); + await until(() => posted.some((m) => m.type === "commands"), "the new session's commands"); + posted.length = 0; + await controller.onMessage({ type: "send", text: "hi" }); + assert.equal(said(), "echo: hi"); + }); + + it("a view opened again is replayed what it missed", async () => { + posted.length = 0; + await controller.onMessage({ type: "ready" }); + assert.equal(posted[0].type, "reset"); + assert.ok(posted.some((m) => m.type === "user" && m.text === "hi")); + assert.ok(posted.some((m) => m.type === "agentText" && m.text === "echo: hi")); + }); +}); diff --git a/editors/vscode/test/fakeVscode.ts b/editors/vscode/test/fakeVscode.ts new file mode 100644 index 0000000..df6b58a --- /dev/null +++ b/editors/vscode/test/fakeVscode.ts @@ -0,0 +1,158 @@ +/** + * Just enough of the `vscode` module to run the controller and the fs bridge + * in plain Node. Installed with {@link installFakeVscode} before they are + * required. + */ +import { promises as fs } from "node:fs"; +import Module = require("node:module"); +import * as path from "node:path"; + +export class Position { + constructor( + readonly line: number, + readonly character: number, + ) {} +} +export class Range { + constructor( + readonly start: Position, + readonly end: Position, + ) {} +} +export class Uri { + private constructor( + readonly scheme: string, + readonly fsPath: string, + private readonly raw: string, + ) {} + static file(p: string): Uri { + return new Uri("file", path.resolve(p), `file://${p}`); + } + static parse(s: string): Uri { + const m = /^([a-z][a-z0-9+.-]*):/i.exec(s); + if (!m) throw new Error("no scheme"); + return new Uri(m[1].toLowerCase(), "", s); + } + toString(): string { + return this.raw; + } +} + +/** An open document: text in memory, saved to disk on save(). */ +export class FakeDocument { + readonly uri: Uri; + isDirty = false; + constructor( + fsPath: string, + public text: string, + ) { + this.uri = Uri.file(fsPath); + } + getText(): string { + return this.text; + } + positionAt(offset: number): Position { + const before = this.text.slice(0, offset).split("\n"); + return new Position(before.length - 1, before[before.length - 1].length); + } + offsetAt(p: Position): number { + const lines = this.text.split("\n"); + let o = 0; + for (let i = 0; i < p.line; i++) o += lines[i].length + 1; + return o + p.character; + } + async save(): Promise { + await fs.mkdir(path.dirname(this.uri.fsPath), { recursive: true }); + await fs.writeFile(this.uri.fsPath, this.text); + this.isDirty = false; + return true; + } +} + +type Op = { kind: "create"; uri: Uri } | { kind: "replace"; uri: Uri; range: Range; text: string } | { kind: "insert"; uri: Uri; at: Position; text: string }; + +export class WorkspaceEdit { + readonly ops: Op[] = []; + createFile(uri: Uri): void { + this.ops.push({ kind: "create", uri }); + } + replace(uri: Uri, range: Range, text: string): void { + this.ops.push({ kind: "replace", uri, range, text }); + } + insert(uri: Uri, at: Position, text: string): void { + this.ops.push({ kind: "insert", uri, at, text }); + } +} + +export interface FakeState { + roots: string[]; + config: Record; + documents: FakeDocument[]; + applied: WorkspaceEdit[]; + opened: string[]; +} + +export function makeFakeVscode(state: FakeState): Record { + const findDoc = (p: string) => state.documents.find((d) => d.uri.fsPath === p); + const workspace = { + get workspaceFolders() { + return state.roots.map((r, index) => ({ uri: Uri.file(r), name: path.basename(r), index })); + }, + get textDocuments() { + return state.documents; + }, + getConfiguration: () => ({ get: (k: string) => state.config[k] }), + fs: { + stat: async (uri: Uri) => fs.stat(uri.fsPath), + readFile: async (uri: Uri) => new Uint8Array(await fs.readFile(uri.fsPath)), + }, + openTextDocument: async (uri: Uri) => { + let doc = findDoc(uri.fsPath); + if (!doc) { + doc = new FakeDocument(uri.fsPath, await fs.readFile(uri.fsPath, "utf8").catch(() => "")); + state.documents.push(doc); + } + return doc; + }, + applyEdit: async (edit: WorkspaceEdit) => { + state.applied.push(edit); + for (const op of edit.ops) { + let doc = findDoc(op.uri.fsPath); + if (op.kind === "create") { + if (!doc) state.documents.push(new FakeDocument(op.uri.fsPath, "")); + continue; + } + if (!doc) doc = await workspace.openTextDocument(op.uri); + if (op.kind === "replace") { + doc.text = doc.text.slice(0, doc.offsetAt(op.range.start)) + op.text + doc.text.slice(doc.offsetAt(op.range.end)); + } else { + const at = doc.offsetAt(op.at); + doc.text = doc.text.slice(0, at) + op.text + doc.text.slice(at); + } + doc.isDirty = true; + } + return true; + }, + }; + return { + Position, + Range, + Uri, + WorkspaceEdit, + workspace, + env: { openExternal: async (u: Uri) => (state.opened.push(u.toString()), true) }, + commands: { executeCommand: async () => undefined }, + window: {}, + }; +} + +/** Make `require("vscode")` return `fake` from now on. */ +export function installFakeVscode(fake: Record): void { + const M = Module as unknown as { _resolveFilename: (req: string, ...rest: unknown[]) => string }; + const original = M._resolveFilename; + const id = "fake-vscode-module"; + require.cache[id] = { id, filename: id, loaded: true, exports: fake } as unknown as NodeJS.Module; + M._resolveFilename = function (req: string, ...rest: unknown[]) { + return req === "vscode" ? id : original.call(this, req, ...rest); + }; +} diff --git a/editors/vscode/test/fixtures/fake-agent.js b/editors/vscode/test/fixtures/fake-agent.js new file mode 100755 index 0000000..8eb4fce --- /dev/null +++ b/editors/vscode/test/fixtures/fake-agent.js @@ -0,0 +1,214 @@ +#!/usr/bin/env node +// A fake ACP agent for the unit tests: newline-delimited JSON-RPC on stdio, +// shaped like `incode --acp`. What a prompt does is chosen by its first word: +// +// stream three text chunks, a tool call and its update, a plan, usage +// permission asks session/request_permission, then says what it got +// read [line limit] asks fs/read_text_file, says the content or the error +// write asks fs/write_text_file, says ok or the error +// hang waits for session/cancel, then answers `cancelled` +// permission-hang asks for permission, and on session/cancel answers `cancelled` +// garbage writes malformed lines, then a valid chunk +// unknown sends the client a request for a method it does not have +// exit exits with code 3 in the middle of the turn +// +// `--acp` is accepted and ignored, so the tests spawn it the way the +// extension spawns incode. +"use strict"; + +const SESSION = "sess-1"; +let buffer = ""; +let nextId = 1; +const waiting = new Map(); // our request id -> resolve +let running = null; // { id, onCancel } + +function send(message) { + process.stdout.write(JSON.stringify(message) + "\n"); +} +function respond(id, result) { + send({ jsonrpc: "2.0", id, result }); +} +function fail(id, code, message, data) { + send({ jsonrpc: "2.0", id, error: { code, message, data } }); +} +function update(u) { + send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: SESSION, update: u } }); +} +function say(text) { + update({ sessionUpdate: "agent_message_chunk", content: { type: "text", text } }); +} +function ask(method, params) { + const id = `agent-${nextId++}`; + return new Promise((resolve) => { + waiting.set(id, resolve); + send({ jsonrpc: "2.0", id, method, params }); + }); +} + +const configOptions = (agent) => [ + { + id: "agent", + name: "Agent", + type: "select", + currentValue: agent, + options: [ + { value: "claude-code", name: "Claude Code" }, + { value: "codex", name: "Codex" }, + ], + }, +]; + +async function prompt(id, params) { + const text = (params.prompt || []).map((b) => (b.type === "text" ? b.text : "")).join(""); + const [word, ...rest] = text.trim().split(/\s+/); + const cancelled = new Promise((resolve) => (running = { id, onCancel: resolve })); + const done = (stopReason) => { + running = null; + respond(id, { stopReason }); + }; + switch (word) { + case "stream": + say("Hello"); + say(", "); + say("world"); + update({ sessionUpdate: "tool_call", toolCallId: "t1", title: "Read file", kind: "read", status: "pending" }); + update({ + sessionUpdate: "tool_call_update", + toolCallId: "t1", + status: "completed", + content: [{ type: "content", content: { type: "text", text: "contents" } }], + }); + update({ sessionUpdate: "plan", entries: [{ content: "step one", priority: "high", status: "in_progress" }] }); + update({ sessionUpdate: "usage_update", used: 1000, size: 200000 }); + return done("end_turn"); + case "permission": + case "permission-hang": { + const asked = ask("session/request_permission", { + sessionId: SESSION, + toolCall: { toolCallId: "t2", title: "Run `rm -rf build`", kind: "execute", status: "pending" }, + options: [ + { optionId: "allow", name: "Allow", kind: "allow_once" }, + { optionId: "always", name: "Always allow", kind: "allow_always" }, + { optionId: "reject", name: "Reject", kind: "reject_once" }, + ], + }); + if (word === "permission-hang") { + await cancelled; + const reply = await asked; + say(`after cancel: ${JSON.stringify(reply.result)}`); + return done("cancelled"); + } + const reply = await asked; + const outcome = reply.result && reply.result.outcome; + say(outcome && outcome.outcome === "selected" ? `chose ${outcome.optionId}` : "chose nothing"); + return done("end_turn"); + } + case "read": { + const [path, line, limit] = rest; + const p = { sessionId: SESSION, path }; + if (line) p.line = Number(line); + if (limit) p.limit = Number(limit); + const reply = await ask("fs/read_text_file", p); + say(reply.error ? `error ${reply.error.code}: ${reply.error.data}` : `content: ${reply.result.content}`); + return done("end_turn"); + } + case "write": { + const [path, ...words] = rest; + const reply = await ask("fs/write_text_file", { sessionId: SESSION, path, content: words.join(" ") }); + say(reply.error ? `error ${reply.error.code}: ${reply.error.data}` : `wrote ${JSON.stringify(reply.result)}`); + return done("end_turn"); + } + case "hang": + say("working"); + await cancelled; + return done("cancelled"); + case "garbage": + process.stdout.write("this is not json\n"); + process.stdout.write("[1,2,3]\n"); + process.stdout.write('{"jsonrpc":"2.0","id":"nobody","result":{}}\n'); + process.stdout.write("\n"); + process.stdout.write('{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"sess-1"}}\n'); + say("still here"); + return done("end_turn"); + case "unknown": { + const reply = await ask("x/does_not_exist", {}); + say(`code ${reply.error && reply.error.code}`); + return done("end_turn"); + } + case "exit": + say("bye"); + setTimeout(() => process.exit(3), 20); + return undefined; + default: + say(`echo: ${text}`); + return done("end_turn"); + } +} + +function handle(line) { + let msg; + try { + msg = JSON.parse(line); + } catch { + return fail(null, -32700, "Parse error"); + } + if (msg.method === undefined) { + const resolve = waiting.get(msg.id); + if (resolve) { + waiting.delete(msg.id); + resolve(msg); + } + return undefined; + } + const { id, method, params } = msg; + switch (method) { + case "initialize": + return respond(id, { + protocolVersion: 1, + agentCapabilities: { loadSession: false, sessionCapabilities: { close: {} } }, + authMethods: [], + agentInfo: { name: "fake", version: "0.0.1", clientCapabilitiesSeen: params.clientCapabilities }, + }); + case "session/new": + respond(id, { + sessionId: SESSION, + modes: { + currentModeId: "workspace-write", + availableModes: [ + { id: "read-only", name: "Read only" }, + { id: "workspace-write", name: "Workspace write" }, + ], + }, + configOptions: configOptions("claude-code"), + }); + return update({ sessionUpdate: "available_commands_update", availableCommands: [{ name: "undo", description: "Undo" }] }); + case "session/prompt": + if (running) return fail(id, -32600, "Invalid request", "a prompt is already running"); + return void prompt(id, params); + case "session/cancel": + if (running) running.onCancel(); + return undefined; + case "session/set_mode": + return respond(id, {}); + case "session/set_config_option": + return respond(id, { configOptions: configOptions(params.value) }); + case "session/close": + return respond(id, {}); + default: + if (id !== undefined) return fail(id, -32601, "Method not found"); + return undefined; + } +} + +process.stdin.setEncoding("utf8"); +process.stdin.on("data", (chunk) => { + buffer += chunk; + let nl; + while ((nl = buffer.indexOf("\n")) >= 0) { + const line = buffer.slice(0, nl); + buffer = buffer.slice(nl + 1); + if (line.trim()) handle(line); + } +}); +process.stdin.on("end", () => process.exit(0)); +process.stderr.write("fake agent ready\n"); diff --git a/editors/vscode/test/markdown.test.ts b/editors/vscode/test/markdown.test.ts new file mode 100644 index 0000000..d09cfff --- /dev/null +++ b/editors/vscode/test/markdown.test.ts @@ -0,0 +1,103 @@ +import { strict as assert } from "node:assert"; +import { describe, it } from "node:test"; + +// media/markdown.js is a plain script shared with the webview. +// eslint-disable-next-line @typescript-eslint/no-require-imports +const md = require("../../media/markdown.js") as { + parse(text: string): Block[]; + parseInline(text: string): Inline[]; + render(doc: FakeDocument, container: FakeElement, text: string, onLink?: (url: string) => void): void; +}; + +type Inline = { t: string; v?: string; href?: string; c?: Inline[] }; +type Block = { t: string; inl?: Inline[]; text?: string; lang?: string; items?: Inline[][]; level?: number }; + +/** Just enough DOM to run render() and see what it builds. */ +class FakeElement { + children: FakeElement[] = []; + attrs: Record = {}; + textContent = ""; + constructor(readonly tag: string) {} + get firstChild(): FakeElement | undefined { + return this.children[0]; + } + appendChild(c: FakeElement): FakeElement { + this.children.push(c); + return c; + } + removeChild(c: FakeElement): void { + this.children = this.children.filter((x) => x !== c); + } + setAttribute(k: string, v: string): void { + this.attrs[k] = v; + } + addEventListener(): void {} + set innerHTML(_v: string) { + throw new Error("innerHTML must never be used"); + } + /** Tags and text, flattened, for assertions. */ + dump(): string { + if (this.tag === "#text") return this.textContent; + const inner = this.children.length ? this.children.map((c) => c.dump()).join("") : this.textContent; + return `<${this.tag}>${inner}`; + } +} +class FakeDocument { + createElement(tag: string): FakeElement { + return new FakeElement(tag); + } + createTextNode(text: string): FakeElement { + const e = new FakeElement("#text"); + e.textContent = text; + return e; + } +} + +function rendered(text: string): string { + const root = new FakeElement("div"); + md.render(new FakeDocument(), root, text); + return root.children.map((c) => c.dump()).join(""); +} + +describe("markdown-lite", () => { + it("HTML in model output stays text", () => { + const blocks = md.parse(' '); + assert.deepEqual(blocks, [ + { t: "p", inl: [{ t: "text", v: ' ' }] }, + ]); + // And render() puts it in a text node, not markup. + const root = new FakeElement("div"); + md.render(new FakeDocument(), root, "hi"); + assert.equal(root.children[0].children[0].tag, "#text"); + assert.equal(root.children[0].children[0].textContent, "hi"); + }); + + it("only http(s) links become links", () => { + assert.deepEqual(md.parseInline("[a](https://x.dev)"), [{ t: "a", href: "https://x.dev", c: [{ t: "text", v: "a" }] }]); + assert.deepEqual(md.parseInline("[a](javascript:alert(1))"), [ + { t: "text", v: "a" }, + { t: "text", v: ")" }, + ]); + assert.deepEqual(md.parseInline("[a](command:workbench.action.quit)"), [{ t: "text", v: "a" }]); + }); + + it("inline code, bold, italic", () => { + assert.equal(rendered("use `x` and **bold** and *it*"), "

use x and bold and it

"); + }); + + it("fenced code keeps its text verbatim, even unterminated while streaming", () => { + assert.deepEqual(md.parse("```rust\nfn main() {}\n```\nafter"), [ + { t: "code", lang: "rust", text: "fn main() {}" }, + { t: "p", inl: [{ t: "text", v: "after" }] }, + ]); + assert.deepEqual(md.parse("```\npartial"), [{ t: "code", lang: "", text: "partial" }]); + }); + + it("headings, lists, quotes, rules", () => { + assert.equal(rendered("# Title\n- a\n- b\n\n1. one\n> q\n---"), "

Title

  • a
  • b
  1. one
q

"); + }); + + it("snake_case words are not italic", () => { + assert.equal(rendered("call my_func_name now"), "

call my_func_name now

"); + }); +}); diff --git a/editors/vscode/test/paths.test.ts b/editors/vscode/test/paths.test.ts new file mode 100644 index 0000000..be430a7 --- /dev/null +++ b/editors/vscode/test/paths.test.ts @@ -0,0 +1,94 @@ +import { strict as assert } from "node:assert"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { describe, it } from "node:test"; +import { checkWorkspacePath, checkWorkspacePathReal, isInside, sliceLines } from "../src/paths"; +import { formatSelection } from "../src/selection"; + +describe("checkWorkspacePath (posix)", () => { + const roots = ["/home/me/proj", "/srv/other"]; + const ok = (p: string) => checkWorkspacePath(p, roots, "posix").ok; + + it("allows files in any workspace folder, and the folder itself", () => { + assert.equal(ok("/home/me/proj/src/main.rs"), true); + assert.equal(ok("/home/me/proj"), true); + assert.equal(ok("/srv/other/a"), true); + assert.equal(ok("/home/me/proj/..foo/x"), true, "`..foo` is a name, not a parent"); + }); + + it("refuses paths outside, including by `..` and prefix tricks", () => { + assert.equal(ok("/etc/passwd"), false); + assert.equal(ok("/home/me/proj/../secret"), false); + assert.equal(ok("/home/me/proj-evil/x"), false, "a sibling sharing the prefix is outside"); + assert.equal(ok("/home/me"), false); + assert.equal(ok("/home/me/proj/a/../../proj2/x"), false); + }); + + it("refuses relative paths, empty paths, NUL bytes, and everything when no folder is open", () => { + assert.equal(ok("src/main.rs"), false); + assert.equal(ok(""), false); + assert.equal(ok("/home/me/proj/a\0b"), false); + assert.equal(checkWorkspacePath("/home/me/proj/x", [], "posix").ok, false); + }); + + it("normalises the path it allows", () => { + const r = checkWorkspacePath("/home/me/proj/./a/../b.txt", roots, "posix"); + assert.deepEqual(r, { ok: true, path: "/home/me/proj/b.txt", root: "/home/me/proj" }); + }); +}); + +describe("checkWorkspacePath (win32)", () => { + it("compares case-insensitively and across drives", () => { + const roots = ["C:\\Users\\me\\proj"]; + assert.equal(checkWorkspacePath("c:\\users\\ME\\proj\\src\\a.ts", roots, "win32").ok, true); + assert.equal(checkWorkspacePath("D:\\Users\\me\\proj\\a.ts", roots, "win32").ok, false); + assert.equal(checkWorkspacePath("C:\\Users\\me\\proj\\..\\x", roots, "win32").ok, false); + assert.equal(isInside("C:\\a", "C:\\ab", "win32"), false); + }); +}); + +describe("checkWorkspacePathReal", () => { + it("refuses a symlink inside the workspace that points outside", async (t) => { + const base = await fs.mkdtemp(path.join(os.tmpdir(), "incode-vscode-")); + t.after(() => fs.rm(base, { recursive: true, force: true })); + const ws = path.join(base, "ws"); + const outside = path.join(base, "outside"); + await fs.mkdir(ws); + await fs.mkdir(outside); + await fs.writeFile(path.join(ws, "in.txt"), "x"); + try { + await fs.symlink(outside, path.join(ws, "link"), "dir"); + } catch { + t.skip("symlinks are not available here"); + return; + } + assert.equal((await checkWorkspacePathReal(path.join(ws, "in.txt"), [ws])).ok, true); + assert.equal((await checkWorkspacePathReal(path.join(ws, "new", "deep.txt"), [ws])).ok, true, "a new file"); + const viaLink = await checkWorkspacePathReal(path.join(ws, "link", "secret.txt"), [ws]); + assert.equal(viaLink.ok, false); + assert.match(!viaLink.ok ? viaLink.reason : "", /resolves outside/); + }); +}); + +describe("sliceLines", () => { + const text = "a\nb\nc\nd"; + it("returns everything without line/limit", () => assert.equal(sliceLines(text), text)); + it("is 1-based", () => assert.equal(sliceLines(text, 2), "b\nc\nd")); + it("honours limit", () => assert.equal(sliceLines(text, 2, 2), "b\nc\n")); + it("limit alone starts at the top", () => assert.equal(sliceLines(text, null, 1), "a\n")); + it("past the end is empty", () => assert.equal(sliceLines(text, 10), "")); +}); + +describe("formatSelection", () => { + it("names the file and lines and fences the code", () => { + assert.equal( + formatSelection({ path: "src/a.ts", languageId: "typescript", startLine: 3, endLine: 4, text: "x\ny" }), + "src/a.ts:3-4\n```typescript\nx\ny\n```\n", + ); + assert.equal( + formatSelection({ path: "a.md", languageId: "markdown", startLine: 1, endLine: 1, text: "```js\n```\n" }), + "a.md:1\n````markdown\n```js\n```\n````\n", + ); + }); +}); diff --git a/editors/vscode/test/real-incode.test.ts b/editors/vscode/test/real-incode.test.ts new file mode 100644 index 0000000..788d68e --- /dev/null +++ b/editors/vscode/test/real-incode.test.ts @@ -0,0 +1,47 @@ +// Against the real binary: `INCODE_BIN=/path/to/incode npm test`. +// Skipped when INCODE_BIN is not set. Only initialize and session/new: a +// prompt would need an agent CLI and its login. +import { strict as assert } from "node:assert"; +import { promises as fs } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { describe, it } from "node:test"; +import { SessionNotification, spawnAgent } from "../src/acp"; + +const BIN = process.env.INCODE_BIN; + +describe("the real incode --acp", { skip: BIN ? false : "set INCODE_BIN to run" }, () => { + it("initialize and session/new", { timeout: 120_000 }, async (t) => { + const ws = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "incode-vscode-real-"))); + t.after(() => fs.rm(ws, { recursive: true, force: true })); + const stderr: string[] = []; + const updates: SessionNotification[] = []; + const agent = spawnAgent({ + command: BIN!, + cwd: ws, + handlers: { requestPermission: async () => ({ outcome: "cancelled" }) }, + onStderr: (s) => stderr.push(s), + }); + agent.client.on("update", (n: SessionNotification) => updates.push(n)); + try { + const init = await agent.client.initialize({ name: "incode-vscode-test", version: "0" }); + assert.equal(init.protocolVersion, 1); + assert.equal(init.agentInfo?.name, "incode"); + const session = await agent.client.newSession(ws); + assert.match(session.sessionId, /\S/); + assert.ok(session.modes?.availableModes.some((m) => m.id === "read-only"), JSON.stringify(session.modes)); + assert.ok(Array.isArray(session.configOptions)); + // The slash commands follow the answer. + const deadline = Date.now() + 10_000; + while (!updates.some((u) => u.update.sessionUpdate === "available_commands_update") && Date.now() < deadline) { + await new Promise((r) => setTimeout(r, 20)); + } + assert.ok( + updates.some((u) => u.update.sessionUpdate === "available_commands_update"), + `no available_commands_update; stderr:\n${stderr.join("")}`, + ); + } finally { + await agent.stop(5000); + } + }); +}); diff --git a/editors/vscode/tsconfig.json b/editors/vscode/tsconfig.json new file mode 100644 index 0000000..0de4653 --- /dev/null +++ b/editors/vscode/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "commonjs", + "lib": ["ES2022"], + "outDir": "out", + "rootDir": ".", + "strict": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "forceConsistentCasingInFileNames": true, + "sourceMap": true, + "skipLibCheck": true, + "types": ["node", "vscode"] + }, + "include": ["src/**/*.ts", "test/**/*.ts"] +} From ee574b3c3e557cf6e938c04a532d21adb8496390 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:33:18 +0000 Subject: [PATCH 3/9] sdk: Python and TypeScript SDKs for driving incode Two ways to drive incode from a program, in both languages: - one-shot: run_task()/runTask() wrap `incode -t ... --output-format json` and parse the result object (result, error, usage, cost_usd, exit code, stderr); TaskFailed carries the parsed result. - interactive: Session speaks ACP to `incode --acp` (initialize, session/new|load, prompt streaming typed events, cancel, set_mode, set_config_option), answers session/request_permission (default: reject) and fs/read_text_file / fs/write_text_file (default: workspace only, after resolving symlinks and ..), skips malformed lines, and reports a crashed agent with its exit code and stderr. Python (sdk/python, incode_sdk): stdlib only, 3.9+, threads, with a thin asyncio wrapper. TypeScript (sdk/typescript, @incord/incode-sdk): Node 18+, no runtime deps, strict, ESM + d.ts. Both test suites run against sdk/testing/fake_incode.py, a scripted fake of both modes; a live test runs initialize + session/new against INCODE_BIN. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- sdk/.gitignore | 8 + sdk/README.md | 70 +++ sdk/examples/python_example.py | 51 +++ sdk/examples/typescript_example.mjs | 45 ++ sdk/python/README.md | 123 +++++ sdk/python/incode_sdk/__init__.py | 71 +++ sdk/python/incode_sdk/aio.py | 77 ++++ sdk/python/incode_sdk/errors.py | 69 +++ sdk/python/incode_sdk/events.py | 322 +++++++++++++ sdk/python/incode_sdk/fs.py | 93 ++++ sdk/python/incode_sdk/py.typed | 0 sdk/python/incode_sdk/session.py | 681 ++++++++++++++++++++++++++++ sdk/python/incode_sdk/task.py | 206 +++++++++ sdk/python/pyproject.toml | 23 + sdk/python/tests/_support.py | 14 + sdk/python/tests/test_live.py | 32 ++ sdk/python/tests/test_session.py | 355 +++++++++++++++ sdk/python/tests/test_task.py | 118 +++++ sdk/testing/fake_incode.py | 497 ++++++++++++++++++++ sdk/typescript/README.md | 113 +++++ sdk/typescript/package-lock.json | 51 +++ sdk/typescript/package.json | 31 ++ sdk/typescript/src/errors.ts | 59 +++ sdk/typescript/src/events.ts | 271 +++++++++++ sdk/typescript/src/fs.ts | 112 +++++ sdk/typescript/src/index.ts | 36 ++ sdk/typescript/src/session.ts | 674 +++++++++++++++++++++++++++ sdk/typescript/src/task.ts | 199 ++++++++ sdk/typescript/test/live.test.ts | 26 ++ sdk/typescript/test/session.test.ts | 361 +++++++++++++++ sdk/typescript/test/support.ts | 31 ++ sdk/typescript/test/task.test.ts | 117 +++++ sdk/typescript/tsconfig.json | 19 + sdk/typescript/tsconfig.test.json | 9 + 34 files changed, 4964 insertions(+) create mode 100644 sdk/.gitignore create mode 100644 sdk/README.md create mode 100644 sdk/examples/python_example.py create mode 100644 sdk/examples/typescript_example.mjs create mode 100644 sdk/python/README.md create mode 100644 sdk/python/incode_sdk/__init__.py create mode 100644 sdk/python/incode_sdk/aio.py create mode 100644 sdk/python/incode_sdk/errors.py create mode 100644 sdk/python/incode_sdk/events.py create mode 100644 sdk/python/incode_sdk/fs.py create mode 100644 sdk/python/incode_sdk/py.typed create mode 100644 sdk/python/incode_sdk/session.py create mode 100644 sdk/python/incode_sdk/task.py create mode 100644 sdk/python/pyproject.toml create mode 100644 sdk/python/tests/_support.py create mode 100644 sdk/python/tests/test_live.py create mode 100644 sdk/python/tests/test_session.py create mode 100644 sdk/python/tests/test_task.py create mode 100755 sdk/testing/fake_incode.py create mode 100644 sdk/typescript/README.md create mode 100644 sdk/typescript/package-lock.json create mode 100644 sdk/typescript/package.json create mode 100644 sdk/typescript/src/errors.ts create mode 100644 sdk/typescript/src/events.ts create mode 100644 sdk/typescript/src/fs.ts create mode 100644 sdk/typescript/src/index.ts create mode 100644 sdk/typescript/src/session.ts create mode 100644 sdk/typescript/src/task.ts create mode 100644 sdk/typescript/test/live.test.ts create mode 100644 sdk/typescript/test/session.test.ts create mode 100644 sdk/typescript/test/support.ts create mode 100644 sdk/typescript/test/task.test.ts create mode 100644 sdk/typescript/tsconfig.json create mode 100644 sdk/typescript/tsconfig.test.json diff --git a/sdk/.gitignore b/sdk/.gitignore new file mode 100644 index 0000000..0672afa --- /dev/null +++ b/sdk/.gitignore @@ -0,0 +1,8 @@ +node_modules/ +dist/ +dist-test/ +__pycache__/ +*.pyc +*.egg-info/ +build/ +*.tsbuildinfo diff --git a/sdk/README.md b/sdk/README.md new file mode 100644 index 0000000..adf72ef --- /dev/null +++ b/sdk/README.md @@ -0,0 +1,70 @@ +# incode SDKs + +Libraries for programs that drive `incode`, in two ways: + +| | One-shot | Interactive | +|---|---|---| +| incode side | `incode -t "" --output-format json` | `incode --acp` (Agent Client Protocol over stdio) | +| Python (`sdk/python`, `incode_sdk`) | `run_task()` | `Session` (threads; `incode_sdk.aio.AsyncSession` for asyncio) | +| TypeScript (`sdk/typescript`, `@incord/incode-sdk`) | `runTask()` | `Session` (async iterator of events) | + +Both SDKs have no runtime dependencies and the same shape: a prompt streams typed +events (message and thought chunks, tool calls and their updates, the plan, the +context window's usage, mode and option changes) and ends with a `PromptResult` +carrying the stop reason. incode's requests to the client are answered by +callbacks: `session/request_permission` (default: reject) and +`fs/read_text_file` / `fs/write_text_file` (default: inside the workspace only, +after resolving symlinks and `..`). + +``` +sdk/ + python/ incode_sdk package, unittest suite + typescript/ @incord/incode-sdk package, node:test suite + testing/ + fake_incode.py a scripted fake incode (both -t and --acp) used by both suites + examples/ python_example.py, typescript_example.mjs +``` + +## Running the tests + +From the repository root: + +```sh +# Python (3.9+, stdlib only) +python3 -m unittest discover sdk/python/tests + +# TypeScript (Node 18+; needs network once for `npm install`, offline after) +cd sdk/typescript && npm install && npm test +``` + +Both suites run against `sdk/testing/fake_incode.py`, so they need `python3` but +no incode build and no agent CLI. Each has one live test, skipped unless +`INCODE_BIN` names a real binary; it runs `initialize` and `session/new` only: + +```sh +cargo build --release +INCODE_BIN=$PWD/target/release/incode python3 -m unittest discover sdk/python/tests +(cd sdk/typescript && INCODE_BIN=$PWD/../../target/release/incode npm test) +``` + +## The fake + +`sdk/testing/fake_incode.py` picks a scenario from the task or prompt text — see +its docstring. `hello` streams one of everything, `permission` asks permission, +`fs R W` reads R and writes W through the client, `wait` waits for a cancel, +`crash` exits mid-prompt, `malformed` writes lines that are not JSON-RPC. Point +an SDK at it with `incode_path=[sys.executable, ".../fake_incode.py"]` / +`incodePath: ["python3", ".../fake_incode.py"]`. + +## Things to know about incode itself + +- `-p` is accepted with `-t` but not applied (the one-shot run ignores it). +- An error found before the run starts (bad `-w`, bad `-p`) prints nothing on + stdout even with `--output-format json`: only stderr and exit code 1. The SDKs + raise `IncodeError` with that stderr. +- `session/update` notifications are per session, not per prompt. incode sends + `available_commands_update` just *after* answering `session/new`, so a prompt + sent at once can see it in its stream. +- incode does not currently send `fs/read_text_file` or `fs/write_text_file` + (its agent CLIs use their own file tools); the SDKs answer them anyway, as ACP + clients, so they work if and when it does. diff --git a/sdk/examples/python_example.py b/sdk/examples/python_example.py new file mode 100644 index 0000000..3c93203 --- /dev/null +++ b/sdk/examples/python_example.py @@ -0,0 +1,51 @@ +#!/usr/bin/env python3 +"""Drive incode from Python: one ACP session that streams a prompt. + + python3 sdk/examples/python_example.py /path/to/repo "Summarise this project" + +INCODE_PATH picks the binary (default: `incode` on PATH). To try it without a +real agent: INCODE_PATH=sdk/testing/fake_incode.py python3 sdk/examples/python_example.py . hello +""" + +import os +import sys + +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "python")) + +from incode_sdk import IncodeError, MessageChunk, Plan, PromptResult, Session, ToolCall, ToolCallUpdate # noqa: E402 + + +def ask(request): + print("\n[permission] %s" % request.title) + answer = input("allow? [y/N] ").strip().lower() + return request.allow() if answer == "y" else request.reject() + + +def main(): + workspace = sys.argv[1] if len(sys.argv) > 1 else "." + text = sys.argv[2] if len(sys.argv) > 2 else "Summarise this project in three sentences." + incode = os.environ.get("INCODE_PATH", "incode") + try: + with Session(workspace, incode_path=incode, permission_mode="read-only", on_permission=ask) as session: + print("session %s (mode %s)" % (session.session_id, session.current_mode)) + for event in session.prompt(text): + if isinstance(event, MessageChunk): + print(event.text, end="", flush=True) + elif isinstance(event, ToolCall): + print("\n[tool] %s" % event.title) + elif isinstance(event, ToolCallUpdate) and event.status in ("completed", "failed"): + print("[tool %s] %s" % (event.tool_call_id, event.status)) + elif isinstance(event, Plan): + print("\n[plan] " + "; ".join("%s (%s)" % (e.content, e.status) for e in event.entries)) + elif isinstance(event, PromptResult): + print("\n-- stop reason: %s" % event.stop_reason) + except KeyboardInterrupt: + pass + except IncodeError as e: + print("incode failed: %s" % e, file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/sdk/examples/typescript_example.mjs b/sdk/examples/typescript_example.mjs new file mode 100644 index 0000000..bbf339d --- /dev/null +++ b/sdk/examples/typescript_example.mjs @@ -0,0 +1,45 @@ +#!/usr/bin/env node +// Drive incode from Node: a one-shot task, then an ACP session that streams a prompt. +// +// (cd sdk/typescript && npm install && npm run build) +// node sdk/examples/typescript_example.mjs /path/to/repo "Summarise this project" +// +// INCODE_PATH picks the binary (default: `incode` on PATH). To try it without a +// real agent: INCODE_PATH=sdk/testing/fake_incode.py node sdk/examples/typescript_example.mjs . hello +import { IncodeError, runTask, Session } from "../typescript/dist/index.js"; + +const [workspace = ".", text = "Summarise this project in three sentences."] = process.argv.slice(2); +const incodePath = process.env.INCODE_PATH ?? "incode"; + +try { + const task = await runTask(text, { workspace, incodePath, timeoutMs: 10 * 60_000 }); + console.log(`one-shot: ${task.result}\n tokens in/out ${task.usage.inputTokens}/${task.usage.outputTokens}, cost ${task.costUsd ?? "unknown"}`); + + const session = await Session.start({ + workspace, + incodePath, + permissionMode: "read-only", + onPermission: (request) => { + console.log(`\n[permission] ${request.title} -> rejected`); + return request.reject(); + }, + }); + try { + process.once("SIGINT", () => session.cancel()); + for await (const event of session.prompt(text)) { + if (event.type === "message_chunk") process.stdout.write(event.text); + else if (event.type === "tool_call") console.log(`\n[tool] ${event.title}`); + else if (event.type === "plan") console.log(`\n[plan] ${event.entries.map((e) => `${e.content} (${e.status})`).join("; ")}`); + else if (event.type === "prompt_result") console.log(`\n-- stop reason: ${event.stopReason}`); + } + } finally { + await session.close(); + } +} catch (e) { + if (e instanceof IncodeError) { + console.error(`incode failed: ${e.message}`); + process.exitCode = 1; + } else { + throw e; + } +} diff --git a/sdk/python/README.md b/sdk/python/README.md new file mode 100644 index 0000000..73f2b0a --- /dev/null +++ b/sdk/python/README.md @@ -0,0 +1,123 @@ +# incode_sdk (Python) + +Drive [incode](../../README.md) from Python 3.9+. Standard library only. + +```sh +pip install ./sdk/python # or put sdk/python on PYTHONPATH +``` + +## One-shot: `run_task` + +Runs `incode -t "" --output-format json` and parses the result object. + +```python +from incode_sdk import run_task, TaskFailed, IncodeError + +try: + r = run_task("Add a unit test for parse_args", workspace="/path/to/repo", + model="sonnet", timeout=600) + print(r.result) # the agent's final answer + print(r.usage.input_tokens, r.usage.output_tokens, r.cost_usd) # cost_usd may be None + print(r.stop_reason, r.agent, r.duration_ms, r.agent_session_id) +except TaskFailed as e: # incode ran and said is_error: true + print("failed:", e.result.error, e.exit_code) +except IncodeError as e: # could not start, timeout, no result object + print(e, e.stderr) +``` + +`TaskResult` fields: `is_error, result, error, session_id, agent, model, +agent_session_id, stop_reason, served_by, usage (TaskUsage), cost_usd, +duration_ms, spec_gate, exit_code, stderr, raw`. Options: `workspace`, `model`, +`permission_mode` (note: incode does not currently apply `-p` to `-t` runs), +`timeout` (seconds; the process is killed), `incode_path` (a path, or a command +prefix list), `env` (added to the environment), `extra_args` (for example +`["--spec-gate=off"]`). + +## Interactive: `Session` + +`incode --acp`, spoken over stdin/stdout as ACP (JSON-RPC 2.0, one message per +line). One `Session` is one process holding one ACP session. + +```python +from incode_sdk import Session, MessageChunk, ToolCall, ToolCallUpdate, Plan, Usage, PromptResult + +def on_permission(request): # session/request_permission + print("asked:", request.title) + return request.allow() # or request.reject(), True/False, None (= cancelled) + +with Session("/path/to/repo", model="sonnet", permission_mode="workspace-write", + on_permission=on_permission) as s: + print(s.session_id, s.current_mode, [o["id"] for o in s.config_options]) + for event in s.prompt("Explain what src/main.rs does"): + if isinstance(event, MessageChunk): + print(event.text, end="") + elif isinstance(event, ToolCall): + print("\n[tool]", event.title, event.kind) + elif isinstance(event, PromptResult): + print("\nstop:", event.stop_reason) # end_turn, cancelled, ... + + s.set_mode("read-only") # session/set_mode + s.set_config_option("agent", "codex") # session/set_config_option + stream = s.prompt("And now?") + result = stream.wait() # consume; stream.text holds the reply +``` + +- `prompt(text_or_blocks, timeout=None)` returns a `PromptStream`: iterate it for + events; the last item is `PromptResult`. It also keeps `.text`, `.events` and + `.result`. One prompt at a time per session. +- `cancel()` sends `session/cancel` (the prompt ends `cancelled`) and answers any + open permission question `cancelled`. Safe to call from another thread. +- Events: `MessageChunk`, `ThoughtChunk`, `UserMessageChunk`, `ToolCall`, + `ToolCallUpdate`, `Plan`, `Usage` (context window `used`/`size`), + `ModeChanged`, `ConfigOptionsChanged`, `AvailableCommands`, `UnknownUpdate`. + Each has `session_id` and `raw` (the update as sent). +- Updates that arrive while no prompt is running go to `on_update(event)` and + `idle_events` (for example the slash commands sent after `session/new`, or a + loaded session's replayed history). Updates are per session, not per prompt: + one sent just as a prompt starts lands in that prompt's stream. +- `on_read_file(ReadFileRequest) -> str` / `on_write_file(WriteFileRequest)` + answer `fs/read_text_file` / `fs/write_text_file`. The defaults + (`WorkspaceFS`) refuse any path whose real path — symlinks followed, `..` + resolved — is outside the workspace, with JSON-RPC error -32602. Pass + `False` to not offer the capability. Raise `FsError(message, code)` from a + custom handler to choose the error. +- Lines on incode's stdout that are not JSON-RPC are skipped and reported to + `on_protocol_error(line, error)` and `protocol_errors`. +- If incode exits, every waiting call and the running prompt raise + `AgentCrashed` with `exit_code` and the stderr tail (`session.stderr`). +- Other options: `load_session_id` (`session/load`), `mcp_servers`, `env`, + `extra_args`, `request_timeout` (seconds, default 120). Raw access: + `request(method, params)` and `notify(method, params)`. + +Callbacks run on worker threads, never on the reader, so a slow permission +prompt does not hold up streaming or a cancel. + +### asyncio + +```python +from incode_sdk.aio import AsyncSession, run_task_async + +async with AsyncSession("/path/to/repo") as s: + async for event in s.prompt("hello"): + ... +``` + +A thin wrapper: the work still runs on threads. + +## Errors + +`IncodeError` (base; `.stderr`, `.exit_code`) → `TaskFailed` (`.result`), +`IncodeTimeout`, `ProtocolError`, `AcpError` (`.method`, `.code`, `.data`), +`AgentCrashed`. + +## Tests + +From the repository root: + +```sh +python3 -m unittest discover sdk/python/tests +# plus the live test against a real binary (initialize + session/new only): +INCODE_BIN=/path/to/incode python3 -m unittest discover sdk/python/tests +``` + +The suite runs against `sdk/testing/fake_incode.py`. diff --git a/sdk/python/incode_sdk/__init__.py b/sdk/python/incode_sdk/__init__.py new file mode 100644 index 0000000..ab91b26 --- /dev/null +++ b/sdk/python/incode_sdk/__init__.py @@ -0,0 +1,71 @@ +"""Drive the incode coding agent from Python. + +* :func:`run_task` — one instruction, ``incode -t ... --output-format json``. +* :class:`Session` — an interactive session over ACP, ``incode --acp``. +* :mod:`incode_sdk.aio` — awaitable wrappers of both. +""" + +__version__ = "0.1.0" + +from .errors import AcpError, AgentCrashed, IncodeError, IncodeTimeout, ProtocolError, TaskFailed # noqa: E402 +from .events import ( # noqa: E402 + AvailableCommands, + ConfigOptionsChanged, + Event, + MessageChunk, + ModeChanged, + PermissionOption, + PermissionRequest, + Plan, + PlanEntry, + PromptResult, + ReadFileRequest, + ThoughtChunk, + ToolCall, + ToolCallUpdate, + UnknownUpdate, + Usage, + UserMessageChunk, + WriteFileRequest, +) +from .fs import FsAccessDenied, FsError, WorkspaceFS # noqa: E402 +from .session import PromptStream, Session, allow_all, reject_all # noqa: E402 +from .task import TaskResult, TaskUsage, run_task # noqa: E402 + +__all__ = [ + "__version__", + "run_task", + "TaskResult", + "TaskUsage", + "Session", + "PromptStream", + "allow_all", + "reject_all", + "Event", + "MessageChunk", + "ThoughtChunk", + "UserMessageChunk", + "ToolCall", + "ToolCallUpdate", + "Plan", + "PlanEntry", + "Usage", + "ModeChanged", + "ConfigOptionsChanged", + "AvailableCommands", + "UnknownUpdate", + "PromptResult", + "PermissionOption", + "PermissionRequest", + "ReadFileRequest", + "WriteFileRequest", + "WorkspaceFS", + "FsError", + "FsAccessDenied", + "IncodeError", + "TaskFailed", + "IncodeTimeout", + "ProtocolError", + "AcpError", + "AgentCrashed", +] diff --git a/sdk/python/incode_sdk/aio.py b/sdk/python/incode_sdk/aio.py new file mode 100644 index 0000000..8515027 --- /dev/null +++ b/sdk/python/incode_sdk/aio.py @@ -0,0 +1,77 @@ +"""asyncio wrappers. The work still happens on threads; this only makes it awaitable. + +Callbacks (``on_permission``, ``on_read_file``, ...) stay plain functions and run +on the session's worker threads. +""" + +import asyncio +import functools +from typing import Any, AsyncIterator, Dict, List, Mapping, Optional, Sequence, Union + +from .events import Event, PromptResult +from .session import PromptStream, Session +from .task import TaskResult, run_task + +__all__ = ["AsyncSession", "run_task_async"] + +_END = object() + + +async def _in_thread(fn: Any, *args: Any, **kwargs: Any) -> Any: + loop = asyncio.get_running_loop() + return await loop.run_in_executor(None, functools.partial(fn, *args, **kwargs)) + + +async def run_task_async(task: str, **kwargs: Any) -> TaskResult: + """:func:`incode_sdk.run_task`, awaitable.""" + return await _in_thread(run_task, task, **kwargs) + + +class AsyncSession: + """:class:`incode_sdk.Session`, awaitable. Takes the same arguments. + + :: + + async with AsyncSession(workspace=".") as s: + async for event in s.prompt("hello"): + print(event) + """ + + def __init__(self, *args: Any, **kwargs: Any): + self.sync = Session(*args, **kwargs) + + async def __aenter__(self) -> "AsyncSession": + await self.start() + return self + + async def __aexit__(self, *exc: Any) -> None: + await self.close() + + async def start(self) -> str: + return await _in_thread(self.sync.start) + + async def close(self) -> None: + await _in_thread(self.sync.close) + + @property + def session_id(self) -> Optional[str]: + return self.sync.session_id + + async def prompt( + self, prompt: Union[str, Sequence[Mapping[str, Any]]], *, timeout: Optional[float] = None + ) -> AsyncIterator[Union[Event, PromptResult]]: + stream: PromptStream = await _in_thread(self.sync.prompt, prompt, timeout=timeout) + while True: + item = await _in_thread(next, stream, _END) + if item is _END: + return + yield item + + async def cancel(self) -> None: + await _in_thread(self.sync.cancel) + + async def set_mode(self, mode_id: str) -> None: + await _in_thread(self.sync.set_mode, mode_id) + + async def set_config_option(self, config_id: str, value: str) -> List[Dict[str, Any]]: + return await _in_thread(self.sync.set_config_option, config_id, value) diff --git a/sdk/python/incode_sdk/errors.py b/sdk/python/incode_sdk/errors.py new file mode 100644 index 0000000..f5a727c --- /dev/null +++ b/sdk/python/incode_sdk/errors.py @@ -0,0 +1,69 @@ +"""Exceptions raised by the SDK.""" + +from typing import Any, Optional + +__all__ = [ + "IncodeError", + "TaskFailed", + "IncodeTimeout", + "ProtocolError", + "AcpError", + "AgentCrashed", +] + + +class IncodeError(Exception): + """Base class for every error the SDK raises. + + ``stderr`` holds what incode wrote to stderr (the tail, for a session), + ``exit_code`` the process's exit status when it has exited. + """ + + def __init__(self, message: str, *, stderr: str = "", exit_code: Optional[int] = None): + super().__init__(message) + self.message = message + self.stderr = stderr + self.exit_code = exit_code + + def __str__(self) -> str: + text = self.message + if self.exit_code is not None: + text += " (exit code %s)" % self.exit_code + tail = self.stderr.strip() + if tail: + tail = tail[-2000:] + text += "\n--- incode stderr ---\n" + tail + return text + + +class TaskFailed(IncodeError): + """``incode -t`` ran and reported ``is_error: true``. ``result`` is the parsed TaskResult.""" + + def __init__(self, message: str, *, result: Any, stderr: str = "", exit_code: Optional[int] = None): + super().__init__(message, stderr=stderr, exit_code=exit_code) + self.result = result + + +class IncodeTimeout(IncodeError): + """The process or a request did not finish in time.""" + + +class ProtocolError(IncodeError): + """incode wrote something the SDK could not understand where it needed to.""" + + +class AcpError(IncodeError): + """incode answered an ACP request with a JSON-RPC error.""" + + def __init__(self, method: str, code: int, message: str, data: Any = None, *, stderr: str = ""): + detail = "%s failed: %s (code %s)" % (method, message, code) + if data is not None: + detail += ": %s" % (data,) + super().__init__(detail, stderr=stderr) + self.method = method + self.code = code + self.data = data + + +class AgentCrashed(IncodeError): + """The ``incode --acp`` process went away while the SDK was waiting on it.""" diff --git a/sdk/python/incode_sdk/events.py b/sdk/python/incode_sdk/events.py new file mode 100644 index 0000000..a6e2e50 --- /dev/null +++ b/sdk/python/incode_sdk/events.py @@ -0,0 +1,322 @@ +"""Typed ``session/update`` events, permission requests and fs requests.""" + +from dataclasses import dataclass, field +from typing import Any, Dict, List, Mapping, Optional, Union + +__all__ = [ + "Event", + "MessageChunk", + "ThoughtChunk", + "UserMessageChunk", + "ToolCall", + "ToolCallUpdate", + "PlanEntry", + "Plan", + "Usage", + "ModeChanged", + "ConfigOptionsChanged", + "AvailableCommands", + "UnknownUpdate", + "PromptResult", + "PermissionOption", + "PermissionRequest", + "ReadFileRequest", + "WriteFileRequest", + "parse_update", +] + + +def _text_of(content: Any) -> str: + if isinstance(content, Mapping) and content.get("type") == "text": + return str(content.get("text") or "") + return "" + + +@dataclass +class MessageChunk: + """Part of the agent's reply (``agent_message_chunk``).""" + + session_id: str + text: str + content: Dict[str, Any] = field(default_factory=dict) + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class ThoughtChunk: + """Part of the agent's reasoning (``agent_thought_chunk``).""" + + session_id: str + text: str + content: Dict[str, Any] = field(default_factory=dict) + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class UserMessageChunk: + """The person's own words, replayed by ``session/load`` (``user_message_chunk``).""" + + session_id: str + text: str + content: Dict[str, Any] = field(default_factory=dict) + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class ToolCall: + """A tool call starts (``tool_call``).""" + + session_id: str + tool_call_id: str + title: str + kind: Optional[str] + status: Optional[str] + raw_input: Any = None + content: List[Any] = field(default_factory=list) + locations: List[Any] = field(default_factory=list) + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class ToolCallUpdate: + """A tool call progresses or ends (``tool_call_update``). Unset fields are ``None``.""" + + session_id: str + tool_call_id: str + status: Optional[str] = None + title: Optional[str] = None + kind: Optional[str] = None + content: Optional[List[Any]] = None + raw_input: Any = None + raw_output: Any = None + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class PlanEntry: + content: str + priority: Optional[str] + status: Optional[str] + + +@dataclass +class Plan: + """The task list as it now stands (``plan``); every entry, every time.""" + + session_id: str + entries: List[PlanEntry] + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class Usage: + """The context window's fill (``usage_update``): ``used`` of ``size`` tokens.""" + + session_id: str + used: Optional[int] + size: Optional[int] + cost: Any = None + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class ModeChanged: + """The session's permission mode changed (``current_mode_update``).""" + + session_id: str + mode_id: str + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class ConfigOptionsChanged: + """The pickers changed (``config_option_update``).""" + + session_id: str + config_options: List[Dict[str, Any]] + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class AvailableCommands: + """The slash commands the session offers (``available_commands_update``).""" + + session_id: str + commands: List[Dict[str, Any]] + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class UnknownUpdate: + """A ``session/update`` kind this SDK does not model; ``kind`` names it.""" + + session_id: str + kind: str + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +@dataclass +class PromptResult: + """How a prompt ended. ``stop_reason``: end_turn, cancelled, max_tokens, max_turn_requests, refusal.""" + + stop_reason: str + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + +Event = Union[ + MessageChunk, + ThoughtChunk, + UserMessageChunk, + ToolCall, + ToolCallUpdate, + Plan, + Usage, + ModeChanged, + ConfigOptionsChanged, + AvailableCommands, + UnknownUpdate, +] + + +def parse_update(session_id: str, update: Mapping[str, Any]) -> Event: + """Turn one ``params.update`` object into a typed event.""" + raw = dict(update) + kind = str(update.get("sessionUpdate") or "") + if kind in ("agent_message_chunk", "agent_thought_chunk", "user_message_chunk"): + content = update.get("content") + content = dict(content) if isinstance(content, Mapping) else {} + cls = {"agent_message_chunk": MessageChunk, "agent_thought_chunk": ThoughtChunk}.get(kind, UserMessageChunk) + return cls(session_id=session_id, text=_text_of(content), content=content, raw=raw) + if kind == "tool_call": + return ToolCall( + session_id=session_id, + tool_call_id=str(update.get("toolCallId") or ""), + title=str(update.get("title") or ""), + kind=update.get("kind"), + status=update.get("status"), + raw_input=update.get("rawInput"), + content=list(update.get("content") or []), + locations=list(update.get("locations") or []), + raw=raw, + ) + if kind == "tool_call_update": + content = update.get("content") + return ToolCallUpdate( + session_id=session_id, + tool_call_id=str(update.get("toolCallId") or ""), + status=update.get("status"), + title=update.get("title"), + kind=update.get("kind"), + content=list(content) if isinstance(content, list) else None, + raw_input=update.get("rawInput"), + raw_output=update.get("rawOutput"), + raw=raw, + ) + if kind == "plan": + entries = [ + PlanEntry(content=str(e.get("content") or ""), priority=e.get("priority"), status=e.get("status")) + for e in update.get("entries") or [] + if isinstance(e, Mapping) + ] + return Plan(session_id=session_id, entries=entries, raw=raw) + if kind == "usage_update": + used, size = update.get("used"), update.get("size") + return Usage( + session_id=session_id, + used=int(used) if isinstance(used, (int, float)) else None, + size=int(size) if isinstance(size, (int, float)) else None, + cost=update.get("cost"), + raw=raw, + ) + if kind == "current_mode_update": + return ModeChanged(session_id=session_id, mode_id=str(update.get("currentModeId") or ""), raw=raw) + if kind == "config_option_update": + return ConfigOptionsChanged(session_id=session_id, config_options=list(update.get("configOptions") or []), raw=raw) + if kind == "available_commands_update": + return AvailableCommands(session_id=session_id, commands=list(update.get("availableCommands") or []), raw=raw) + return UnknownUpdate(session_id=session_id, kind=kind, raw=raw) + + +# ---------------------------------------------------------------- agent -> client requests + + +@dataclass +class PermissionOption: + option_id: str + name: str + kind: str # allow_once | allow_always | reject_once | reject_always + + +@dataclass +class PermissionRequest: + """``session/request_permission``: incode asks before a tool call runs. + + Your ``on_permission`` callback returns one of ``options``' ids (or the + option itself), or ``None`` to answer ``cancelled``. ``allow()``, + ``allow_always()`` and ``reject()`` pick the matching option for you. + """ + + session_id: str + tool_call: Dict[str, Any] + options: List[PermissionOption] + raw: Dict[str, Any] = field(default_factory=dict, repr=False) + + @property + def title(self) -> str: + return str(self.tool_call.get("title") or "") + + @property + def tool_call_id(self) -> str: + return str(self.tool_call.get("toolCallId") or "") + + def option_of_kind(self, *kinds: str) -> Optional[str]: + for kind in kinds: + for option in self.options: + if option.kind == kind: + return option.option_id + return None + + def allow(self) -> Optional[str]: + """The allow-once option (or allow-always when that is all there is).""" + return self.option_of_kind("allow_once", "allow_always") + + def allow_always(self) -> Optional[str]: + return self.option_of_kind("allow_always", "allow_once") + + def reject(self) -> Optional[str]: + """The reject-once option (or reject-always). ``None`` (cancelled) when there is none.""" + return self.option_of_kind("reject_once", "reject_always") + + @classmethod + def from_params(cls, params: Mapping[str, Any]) -> "PermissionRequest": + options = [ + PermissionOption(option_id=str(o.get("optionId")), name=str(o.get("name") or ""), kind=str(o.get("kind") or "")) + for o in params.get("options") or [] + if isinstance(o, Mapping) + ] + tool_call = params.get("toolCall") + return cls( + session_id=str(params.get("sessionId") or ""), + tool_call=dict(tool_call) if isinstance(tool_call, Mapping) else {}, + options=options, + raw=dict(params), + ) + + +@dataclass +class ReadFileRequest: + """``fs/read_text_file``. ``line`` is 1-based; ``limit`` is a number of lines.""" + + session_id: str + path: str + line: Optional[int] = None + limit: Optional[int] = None + + +@dataclass +class WriteFileRequest: + """``fs/write_text_file``.""" + + session_id: str + path: str + content: str diff --git a/sdk/python/incode_sdk/fs.py b/sdk/python/incode_sdk/fs.py new file mode 100644 index 0000000..9231cc3 --- /dev/null +++ b/sdk/python/incode_sdk/fs.py @@ -0,0 +1,93 @@ +"""The client's file system, as offered to incode (``fs/read_text_file``, ``fs/write_text_file``). + +The default handlers serve files inside the session's workspace only. A path +is resolved first — symlinks followed, ``..`` collapsed — and refused when the +real path is not under the workspace's real path. +""" + +import os +from typing import Optional, Union + +from .events import ReadFileRequest, WriteFileRequest + +__all__ = ["FsError", "FsAccessDenied", "WorkspaceFS", "INVALID_PARAMS", "RESOURCE_NOT_FOUND", "INTERNAL_ERROR"] + +INVALID_PARAMS = -32602 +RESOURCE_NOT_FOUND = -32002 +INTERNAL_ERROR = -32603 + + +class FsError(Exception): + """Raise from an fs callback to answer with this JSON-RPC error.""" + + def __init__(self, message: str, code: int = INTERNAL_ERROR): + super().__init__(message) + self.code = code + self.message = message + + +class FsAccessDenied(FsError): + """The path is outside the workspace (after resolving symlinks and ``..``).""" + + def __init__(self, message: str): + super().__init__(message, INVALID_PARAMS) + + +class WorkspaceFS: + """Reads and writes confined to one directory tree.""" + + def __init__(self, root: Union[str, "os.PathLike[str]"]): + self.root = os.path.realpath(os.fspath(root)) + + def resolve(self, path: str) -> str: + """The real path of ``path``, or :class:`FsAccessDenied` when it is outside the root.""" + if not isinstance(path, str) or not path: + raise FsAccessDenied("access denied: no path given") + if "\x00" in path: + raise FsAccessDenied("access denied: the path contains a NUL byte") + if not os.path.isabs(path): + # ACP paths are absolute; a relative one is taken against the root. + path = os.path.join(self.root, path) + real = os.path.realpath(path) + if not self.contains(real): + raise FsAccessDenied("access denied: %s is outside the workspace %s" % (path, self.root)) + return real + + def contains(self, real: str) -> bool: + try: + return os.path.commonpath([self.root, real]) == self.root + except ValueError: # different drives on Windows + return False + + def read(self, request: ReadFileRequest) -> str: + real = self.resolve(request.path) + try: + with open(real, "r", encoding="utf-8", errors="replace", newline="") as f: + text = f.read() + except FileNotFoundError: + raise FsError("file not found: %s" % request.path, RESOURCE_NOT_FOUND) + except IsADirectoryError: + raise FsError("is a directory: %s" % request.path, INVALID_PARAMS) + return slice_lines(text, request.line, request.limit) + + def write(self, request: WriteFileRequest) -> None: + real = self.resolve(request.path) + parent = os.path.dirname(real) + os.makedirs(parent, exist_ok=True) + # Resolve again now that the parents exist: nothing may have been + # swapped for a symlink out of the tree in between. + real = self.resolve(real) + if os.path.isdir(real): + raise FsError("is a directory: %s" % request.path, INVALID_PARAMS) + with open(real, "w", encoding="utf-8", newline="") as f: + f.write(request.content) + + +def slice_lines(text: str, line: Optional[int], limit: Optional[int]) -> str: + """Lines ``line`` (1-based) onward, at most ``limit`` of them.""" + if line is None and limit is None: + return text + lines = text.splitlines(keepends=True) + start = max((line or 1) - 1, 0) + end = len(lines) if limit is None else start + max(limit, 0) + return "".join(lines[start:end]) diff --git a/sdk/python/incode_sdk/py.typed b/sdk/python/incode_sdk/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/sdk/python/incode_sdk/session.py b/sdk/python/incode_sdk/session.py new file mode 100644 index 0000000..dc2a5bc --- /dev/null +++ b/sdk/python/incode_sdk/session.py @@ -0,0 +1,681 @@ +"""Interactive sessions: ``incode --acp`` driven over ACP (JSON-RPC 2.0, one message per line). + +One :class:`Session` is one ``incode --acp`` process holding one ACP session. +A reader thread parses incode's stdout; requests incode sends the client +(permission, file reads and writes) are answered on threads of their own, so a +slow callback never stops ``session/update`` or a cancel from flowing. +""" + +import collections +import itertools +import json +import os +import queue +import subprocess +import threading +import time +from typing import Any, Callable, Deque, Dict, Iterator, List, Mapping, Optional, Sequence, Union + +from . import __version__ +from .errors import AcpError, AgentCrashed, IncodeError, IncodeTimeout +from .events import ( + ConfigOptionsChanged, + Event, + MessageChunk, + ModeChanged, + PermissionOption, + PermissionRequest, + PromptResult, + ReadFileRequest, + WriteFileRequest, + parse_update, +) +from .fs import INTERNAL_ERROR, INVALID_PARAMS, RESOURCE_NOT_FOUND, FsError, WorkspaceFS + +__all__ = ["Session", "PromptStream", "reject_all", "allow_all", "PROTOCOL_VERSION"] + +PROTOCOL_VERSION = 1 +METHOD_NOT_FOUND = -32601 +STDERR_TAIL_BYTES = 64 * 1024 + +PermissionDecision = Union[str, PermissionOption, bool, None] +PermissionHandler = Callable[[PermissionRequest], PermissionDecision] +ReadHandler = Callable[[ReadFileRequest], str] +WriteHandler = Callable[[WriteFileRequest], None] + + +def reject_all(request: PermissionRequest) -> PermissionDecision: + """The default permission handler: pick the reject option (``cancelled`` if there is none).""" + return request.reject() + + +def allow_all(request: PermissionRequest) -> PermissionDecision: + """Allow every call once. Only for trusted, sandboxed work.""" + return request.allow() + + +class _Pending: + __slots__ = ("method", "done", "message", "callback") + + def __init__(self, method: str, callback: Optional[Callable[[Optional[dict], Optional[BaseException]], None]] = None): + self.method = method + self.done = threading.Event() + self.message: Optional[dict] = None + self.callback = callback + + + +class PromptStream: + """The events of one prompt, in order, ending with a :class:`PromptResult`. + + Iterate it (``for event in stream``). ``text`` accumulates the agent's + message chunks; ``result`` is set once the prompt ends. ``wait()`` consumes + the rest and returns the result. + """ + + def __init__(self, session: "Session", timeout: Optional[float]): + self._session = session + self._queue: "queue.Queue[Any]" = queue.Queue() + self._deadline = None if timeout is None else time.monotonic() + timeout + self._timeout = timeout + self._finished = False + self.text = "" + self.result: Optional[PromptResult] = None + self.events: List[Event] = [] + + def __iter__(self) -> "PromptStream": + return self + + def __next__(self) -> Union[Event, PromptResult]: + if self._finished: + raise StopIteration + try: + if self._deadline is None: + item = self._queue.get() + else: + item = self._queue.get(timeout=max(self._deadline - time.monotonic(), 0)) + except queue.Empty: + self._finished = True + self._session.cancel() + raise IncodeTimeout("the prompt did not end within %ss (a cancel was sent)" % self._timeout, stderr=self._session.stderr) + if isinstance(item, PromptResult): + self._finished = True + self.result = item + return item + if isinstance(item, BaseException): + self._finished = True + raise item + if isinstance(item, MessageChunk): + self.text += item.text + self.events.append(item) + return item + + def wait(self) -> PromptResult: + """Consume the remaining events and return how the prompt ended.""" + for _ in self: + pass + assert self.result is not None + return self.result + + def cancel(self) -> None: + self._session.cancel() + + # Called from the reader thread. + def _put(self, item: Any) -> None: + self._queue.put(item) + + +class Session: + """``incode --acp`` as a context manager. + + :: + + with Session(workspace="/path/to/repo") as s: + for event in s.prompt("Explain src/main.rs"): + ... + + ``on_permission(request) -> decision`` answers ``session/request_permission``: + return an option id (``request.allow()``, ``request.reject()``), ``True`` / + ``False``, or ``None`` for ``cancelled``. The default rejects. + + ``on_read_file(ReadFileRequest) -> str`` and ``on_write_file(WriteFileRequest)`` + answer ``fs/read_text_file`` and ``fs/write_text_file``. The defaults serve the + workspace only (symlinks and ``..`` resolved first). Pass ``False`` to not + offer the capability at all. + + ``on_update(event)`` receives ``session/update`` events that arrive while no + prompt is running (the slash commands after ``session/new``, MCP server + status, history replayed by ``load_session_id``); they are also kept in + ``idle_events``. ``on_protocol_error(line, error)`` hears about lines on + incode's stdout that are not JSON-RPC; they are skipped. + """ + + def __init__( + self, + workspace: Optional[Union[str, "os.PathLike[str]"]] = None, + *, + incode_path: Union[str, "os.PathLike[str]", Sequence[str]] = "incode", + model: Optional[str] = None, + permission_mode: Optional[str] = None, + on_permission: Optional[PermissionHandler] = None, + on_read_file: Union[ReadHandler, None, bool] = None, + on_write_file: Union[WriteHandler, None, bool] = None, + on_update: Optional[Callable[[Event], None]] = None, + on_protocol_error: Optional[Callable[[str, Exception], None]] = None, + load_session_id: Optional[str] = None, + mcp_servers: Optional[List[Mapping[str, Any]]] = None, + env: Optional[Mapping[str, str]] = None, + extra_args: Sequence[str] = (), + request_timeout: Optional[float] = 120.0, + ): + self.workspace = os.path.abspath(os.fspath(workspace) if workspace is not None else os.getcwd()) + self.incode_path = incode_path + self.model = model + self.permission_mode = permission_mode + self.on_permission: PermissionHandler = on_permission or reject_all + self.fs = WorkspaceFS(self.workspace) + self._read: Optional[ReadHandler] = None if on_read_file is False else (on_read_file if callable(on_read_file) else self.fs.read) + self._write: Optional[WriteHandler] = None if on_write_file is False else (on_write_file if callable(on_write_file) else self.fs.write) + self.on_update = on_update + self.on_protocol_error = on_protocol_error + self.load_session_id = load_session_id + self.mcp_servers = list(mcp_servers or []) + self.env = env + self.extra_args = list(extra_args) + self.request_timeout = request_timeout + + # Filled by start(). + self.session_id: Optional[str] = None + self.agent_info: Dict[str, Any] = {} + self.agent_capabilities: Dict[str, Any] = {} + self.protocol_version: Optional[int] = None + self.current_mode: Optional[str] = None + self.available_modes: List[Dict[str, Any]] = [] + self.config_options: List[Dict[str, Any]] = [] + self.idle_events: Deque[Event] = collections.deque(maxlen=1000) + self.protocol_errors: Deque[str] = collections.deque(maxlen=100) + self.callback_errors: Deque[BaseException] = collections.deque(maxlen=100) + + self._proc: Optional[subprocess.Popen] = None + self._ids = itertools.count(1) + self._write_lock = threading.Lock() + self._lock = threading.Lock() + self._pending: Dict[Any, _Pending] = {} + self._active: Optional[PromptStream] = None + self._open_permissions: Dict[Any, str] = {} # request id -> session id, until answered + self._answered: set = set() + self._stderr: Deque[bytes] = collections.deque() + self._stderr_size = 0 + self._dead: Optional[IncodeError] = None + self._closing = False + self._threads: List[threading.Thread] = [] + + # ------------------------------------------------------------ lifecycle + + def __enter__(self) -> "Session": + if self._proc is None: + self.start() + return self + + def __exit__(self, *exc: Any) -> None: + self.close() + + def argv(self) -> List[str]: + """The command line ``start()`` runs.""" + if isinstance(self.incode_path, (str, bytes)) or hasattr(self.incode_path, "__fspath__"): + argv = [os.fspath(self.incode_path)] # type: ignore[arg-type] + else: + argv = [os.fspath(p) for p in self.incode_path] + argv.append("--acp") + if self.model: + argv += ["-m", self.model] + if self.permission_mode: + argv += ["-p", self.permission_mode] + return argv + self.extra_args + + def start(self) -> str: + """Start ``incode --acp``, ``initialize``, and open (or load) the session. Returns its id.""" + if self._proc is not None: + raise IncodeError("this Session was already started") + full_env = None + if self.env is not None: + full_env = dict(os.environ) + full_env.update(self.env) + argv = self.argv() + try: + self._proc = subprocess.Popen( + argv, + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + env=full_env, + bufsize=-1, + ) + except OSError as e: + raise IncodeError("could not start incode: %s (%r)" % (e.strerror or e, argv[0])) from e + for target, name in ((self._read_stdout, "incode-acp-reader"), (self._read_stderr, "incode-acp-stderr")): + t = threading.Thread(target=target, name=name, daemon=True) + t.start() + self._threads.append(t) + try: + init = self.request( + "initialize", + { + "protocolVersion": PROTOCOL_VERSION, + "clientCapabilities": { + "fs": {"readTextFile": self._read is not None, "writeTextFile": self._write is not None}, + "terminal": False, + }, + "clientInfo": {"name": "incode-sdk-python", "version": __version__}, + }, + ) + self.protocol_version = init.get("protocolVersion") + self.agent_capabilities = dict(init.get("agentCapabilities") or {}) + self.agent_info = dict(init.get("agentInfo") or {}) + if self.load_session_id: + opened = self.request( + "session/load", + {"sessionId": self.load_session_id, "cwd": self.workspace, "mcpServers": self.mcp_servers}, + ) + self.session_id = self.load_session_id + else: + opened = self.request("session/new", {"cwd": self.workspace, "mcpServers": self.mcp_servers}) + self.session_id = str(opened["sessionId"]) + except BaseException: + self.close() + raise + modes = opened.get("modes") or {} + self.current_mode = modes.get("currentModeId") + self.available_modes = list(modes.get("availableModes") or []) + self.config_options = list(opened.get("configOptions") or []) + return self.session_id + + def close(self, timeout: float = 5.0) -> None: + """Close the session and stop the process (stdin closed, then terminate, then kill).""" + proc = self._proc + if proc is None or self._closing: + return + if self._dead is None and self.session_id and "close" in (self.agent_capabilities.get("sessionCapabilities") or {}): + try: + self.request("session/close", {"sessionId": self.session_id}, timeout=min(timeout, 2.0)) + except IncodeError: + pass + self._closing = True + try: + if proc.stdin: + proc.stdin.close() + except OSError: + pass + try: + proc.wait(timeout=timeout) + except subprocess.TimeoutExpired: + proc.terminate() + try: + proc.wait(timeout=2) + except subprocess.TimeoutExpired: + proc.kill() + proc.wait() + for t in self._threads: + if t is not threading.current_thread(): + t.join(timeout=2) + for pipe in (proc.stdout, proc.stderr): + try: + if pipe: + pipe.close() + except OSError: + pass + self._fail_all(IncodeError("the session was closed", stderr=self.stderr, exit_code=proc.returncode)) + + @property + def stderr(self) -> str: + """The last 64 KiB incode wrote to stderr.""" + with self._lock: + data = b"".join(self._stderr) + return data.decode("utf-8", errors="replace") + + @property + def returncode(self) -> Optional[int]: + return None if self._proc is None else self._proc.poll() + + # ------------------------------------------------------------ requests + + def request(self, method: str, params: Optional[Mapping[str, Any]] = None, timeout: Optional[float] = -1) -> Dict[str, Any]: + """Send a JSON-RPC request and wait for its result (``AcpError`` on an error reply). + + ``timeout`` defaults to the session's ``request_timeout``; ``None`` waits forever. + """ + if timeout == -1: + timeout = self.request_timeout + pending = self._send_request(method, params) + if not pending.done.wait(timeout): + with self._lock: + self._pending = {k: v for k, v in self._pending.items() if v is not pending} + raise IncodeTimeout("no answer to %s within %ss" % (method, timeout), stderr=self.stderr) + return self._result_of(pending) + + def notify(self, method: str, params: Optional[Mapping[str, Any]] = None) -> None: + """Send a JSON-RPC notification.""" + self._send({"jsonrpc": "2.0", "method": method, "params": dict(params or {})}) + + def _send_request(self, method: str, params: Optional[Mapping[str, Any]], callback: Any = None) -> _Pending: + if self._dead is not None: + raise self._dead + if self._proc is None: + raise IncodeError("the session is not started") + rid = next(self._ids) + pending = _Pending(method, callback) + with self._lock: + self._pending[rid] = pending + try: + self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": dict(params or {})}) + except BaseException: + with self._lock: + self._pending.pop(rid, None) + raise + return pending + + def _result_of(self, pending: _Pending) -> Dict[str, Any]: + message = pending.message + if message is None: + raise self._dead or IncodeError("the session was closed") + if "error" in message and message["error"] is not None: + error = message["error"] if isinstance(message["error"], dict) else {"message": str(message["error"])} + raise AcpError(pending.method, int(error.get("code") or 0), str(error.get("message") or ""), error.get("data"), stderr=self.stderr) + result = message.get("result") + return result if isinstance(result, dict) else {} + + def _send(self, message: Mapping[str, Any]) -> None: + data = (json.dumps(message, ensure_ascii=False) + "\n").encode("utf-8") + proc = self._proc + if proc is None or proc.stdin is None: + raise IncodeError("the session is not started") + with self._write_lock: + try: + proc.stdin.write(data) + proc.stdin.flush() + except (BrokenPipeError, OSError, ValueError) as e: + raise self._dead or AgentCrashed("incode is no longer reading its stdin: %s" % e, stderr=self.stderr, exit_code=proc.poll()) from e + + # ------------------------------------------------------------ session methods + + def prompt(self, prompt: Union[str, Sequence[Mapping[str, Any]]], *, timeout: Optional[float] = None) -> PromptStream: + """Send ``session/prompt``. Returns a :class:`PromptStream` of events ending with a :class:`PromptResult`. + + ``prompt`` is text, or a list of ACP content blocks. ``timeout`` bounds the + whole prompt; when it passes, a cancel is sent and :class:`IncodeTimeout` raised. + """ + if self.session_id is None: + raise IncodeError("the session is not started") + blocks = [{"type": "text", "text": prompt}] if isinstance(prompt, str) else [dict(b) for b in prompt] + stream = PromptStream(self, timeout) + with self._lock: + if self._active is not None: + raise IncodeError("a prompt is already running in this session") + self._active = stream + + def done(message: Optional[dict], error: Optional[BaseException]) -> None: + # On the reader thread, after every update that came before the reply. + with self._lock: + if self._active is stream: + self._active = None + if error is not None: + stream._put(error) + return + assert message is not None + if message.get("error") is not None: + e = message["error"] if isinstance(message["error"], dict) else {"message": str(message["error"])} + stream._put(AcpError("session/prompt", int(e.get("code") or 0), str(e.get("message") or ""), e.get("data"), stderr=self.stderr)) + return + result = message.get("result") if isinstance(message.get("result"), dict) else {} + stream._put(PromptResult(stop_reason=str(result.get("stopReason") or ""), raw=result)) + + try: + self._send_request("session/prompt", {"sessionId": self.session_id, "prompt": blocks}, callback=done) + except BaseException: + with self._lock: + self._active = None + raise + return stream + + def cancel(self) -> None: + """Send ``session/cancel``; the running prompt ends with ``stop_reason == "cancelled"``. + + Any permission question still open is answered ``cancelled``, as ACP asks of a client. + """ + if self.session_id is None or self._dead is not None: + return + self.notify("session/cancel", {"sessionId": self.session_id}) + with self._lock: + open_ids = [rid for rid, sid in self._open_permissions.items() if sid == self.session_id] + for rid in open_ids: + self._answer(rid, result={"outcome": {"outcome": "cancelled"}}) + + def set_mode(self, mode_id: str) -> None: + """``session/set_mode``: ``read-only``, ``workspace-write`` or ``danger-full-access``.""" + self.request("session/set_mode", {"sessionId": self.session_id, "modeId": mode_id}) + self.current_mode = mode_id + + def set_config_option(self, config_id: str, value: str) -> List[Dict[str, Any]]: + """``session/set_config_option`` (``agent`` or ``role``). Returns every option as it now stands.""" + result = self.request("session/set_config_option", {"sessionId": self.session_id, "configId": config_id, "value": value}) + self.config_options = list(result.get("configOptions") or []) + return self.config_options + + def list_sessions(self) -> List[Dict[str, Any]]: + """``session/list`` for this workspace.""" + return list(self.request("session/list", {"cwd": self.workspace}).get("sessions") or []) + + # ------------------------------------------------------------ reader side + + def _read_stdout(self) -> None: + proc = self._proc + assert proc is not None and proc.stdout is not None + try: + for raw in iter(proc.stdout.readline, b""): + line = raw.decode("utf-8", errors="replace").strip() + if line: + self._dispatch(line) + except (OSError, ValueError): + pass + self._stdout_closed() + + def _read_stderr(self) -> None: + proc = self._proc + assert proc is not None and proc.stderr is not None + try: + for chunk in iter(lambda: proc.stderr.read1(4096) if hasattr(proc.stderr, "read1") else proc.stderr.read(4096), b""): + with self._lock: + self._stderr.append(chunk) + self._stderr_size += len(chunk) + while self._stderr_size > STDERR_TAIL_BYTES and len(self._stderr) > 1: + self._stderr_size -= len(self._stderr.popleft()) + except (OSError, ValueError): + pass + + def _protocol_error(self, line: str, error: Exception) -> None: + self.protocol_errors.append(line[:1000]) + if self.on_protocol_error is not None: + try: + self.on_protocol_error(line, error) + except Exception as e: # a callback must not stop the reader + self.callback_errors.append(e) + + def _dispatch(self, line: str) -> None: + try: + message = json.loads(line) + except ValueError as e: + self._protocol_error(line, e) + return + if not isinstance(message, dict): + self._protocol_error(line, ValueError("not a JSON-RPC object")) + return + method = message.get("method") + if isinstance(method, str): + params = message.get("params") if isinstance(message.get("params"), dict) else {} + if message.get("id") is not None: + t = threading.Thread(target=self._serve, args=(message["id"], method, params), daemon=True) + t.start() + elif method == "session/update": + self._update(params) + return + if "id" in message and ("result" in message or "error" in message): + with self._lock: + pending = self._pending.pop(message["id"], None) + if pending is None: + self._protocol_error(line, ValueError("a response to no request this client sent")) + return + pending.message = message + pending.done.set() + if pending.callback is not None: + pending.callback(message, None) + return + self._protocol_error(line, ValueError("neither a request, a notification nor a response")) + + def _update(self, params: Mapping[str, Any]) -> None: + update = params.get("update") + if not isinstance(update, Mapping): + self._protocol_error(json.dumps(params)[:1000], ValueError("session/update without an update")) + return + event = parse_update(str(params.get("sessionId") or ""), update) + if isinstance(event, ModeChanged): + self.current_mode = event.mode_id + elif isinstance(event, ConfigOptionsChanged): + self.config_options = list(event.config_options) + with self._lock: + active = self._active + if active is not None: + active._put(event) + return + self.idle_events.append(event) + if self.on_update is not None: + try: + self.on_update(event) + except Exception as e: + self.callback_errors.append(e) + + def _stdout_closed(self) -> None: + proc = self._proc + code = None + if proc is not None: + try: + code = proc.wait(timeout=5) + except subprocess.TimeoutExpired: + code = proc.poll() + # Let the stderr reader catch the process's last words. + for t in self._threads: + if t.name == "incode-acp-stderr" and t is not threading.current_thread(): + t.join(timeout=1) + if self._closing: + error: IncodeError = IncodeError("the session was closed", stderr=self.stderr, exit_code=code) + else: + error = AgentCrashed("incode --acp exited unexpectedly", stderr=self.stderr, exit_code=code) + self._fail_all(error) + + def _fail_all(self, error: IncodeError) -> None: + with self._lock: + if self._dead is None: + self._dead = error + pending = list(self._pending.values()) + self._pending.clear() + active, self._active = self._active, None + for p in pending: + p.done.set() + if p.callback is not None: + p.callback(None, error) + if active is not None: + active._put(error) + + # ------------------------------------------------------------ agent -> client requests + + def _answer(self, rid: Any, result: Any = None, error: Optional[Mapping[str, Any]] = None) -> None: + with self._lock: + if rid in self._answered: + return + self._answered.add(rid) + self._open_permissions.pop(rid, None) + message: Dict[str, Any] = {"jsonrpc": "2.0", "id": rid} + if error is not None: + message["error"] = dict(error) + else: + message["result"] = result if result is not None else {} + try: + self._send(message) + except IncodeError: + pass + + def _serve(self, rid: Any, method: str, params: Mapping[str, Any]) -> None: + try: + if method == "session/request_permission": + self._serve_permission(rid, params) + elif method == "fs/read_text_file" and self._read is not None: + self._serve_fs(rid, lambda: {"content": self._read(_read_request(params))}) # type: ignore[misc] + elif method == "fs/write_text_file" and self._write is not None: + self._serve_fs(rid, lambda: (self._write(_write_request(params)), {})[1]) # type: ignore[misc] + else: + self._answer(rid, error={"code": METHOD_NOT_FOUND, "message": "Method not found", "data": method}) + except Exception as e: # never leave incode waiting + self.callback_errors.append(e) + self._answer(rid, error={"code": INTERNAL_ERROR, "message": "client error: %s" % e}) + + def _serve_permission(self, rid: Any, params: Mapping[str, Any]) -> None: + request = PermissionRequest.from_params(params) + with self._lock: + self._open_permissions[rid] = request.session_id + try: + decision = self.on_permission(request) + except Exception as e: + self.callback_errors.append(e) + decision = request.reject() + if decision is True: + decision = request.allow() + elif decision is False: + decision = request.reject() + if isinstance(decision, PermissionOption): + decision = decision.option_id + if decision is None: + outcome: Dict[str, Any] = {"outcome": "cancelled"} + elif decision in [o.option_id for o in request.options]: + outcome = {"outcome": "selected", "optionId": decision} + else: + self.callback_errors.append(ValueError("on_permission returned %r, not one of the offered option ids" % (decision,))) + fallback = request.reject() + outcome = {"outcome": "selected", "optionId": fallback} if fallback else {"outcome": "cancelled"} + self._answer(rid, result={"outcome": outcome}) + + def _serve_fs(self, rid: Any, run: Callable[[], Dict[str, Any]]) -> None: + try: + result = run() + except FsError as e: + self._answer(rid, error={"code": e.code, "message": e.message}) + except FileNotFoundError as e: + self._answer(rid, error={"code": RESOURCE_NOT_FOUND, "message": "file not found: %s" % (e.filename or e)}) + except (TypeError, KeyError) as e: + self._answer(rid, error={"code": INVALID_PARAMS, "message": "invalid params: %s" % e}) + except OSError as e: + self._answer(rid, error={"code": INTERNAL_ERROR, "message": "%s: %s" % (e.strerror or e, e.filename or "")}) + else: + self._answer(rid, result=result) + + +def _read_request(params: Mapping[str, Any]) -> ReadFileRequest: + line, limit = params.get("line"), params.get("limit") + return ReadFileRequest( + session_id=str(params.get("sessionId") or ""), + path=str(params["path"]), + line=int(line) if isinstance(line, (int, float)) else None, + limit=int(limit) if isinstance(limit, (int, float)) else None, + ) + + +def _write_request(params: Mapping[str, Any]) -> WriteFileRequest: + content = params["content"] + if not isinstance(content, str): + raise TypeError("content must be a string") + return WriteFileRequest(session_id=str(params.get("sessionId") or ""), path=str(params["path"]), content=content) + + +def iter_text(stream: Iterator[Any]) -> Iterator[str]: + """Just the agent's message text from a prompt's events.""" + for event in stream: + if isinstance(event, MessageChunk): + yield event.text diff --git a/sdk/python/incode_sdk/task.py b/sdk/python/incode_sdk/task.py new file mode 100644 index 0000000..e5dc0e5 --- /dev/null +++ b/sdk/python/incode_sdk/task.py @@ -0,0 +1,206 @@ +"""One-shot runs: ``incode -t "" --output-format json``.""" + +import json +import os +import subprocess +from dataclasses import dataclass, field +from typing import Any, Dict, List, Mapping, Optional, Sequence, Union + +from .errors import IncodeError, IncodeTimeout, ProtocolError, TaskFailed + +__all__ = ["TaskResult", "TaskUsage", "run_task", "build_task_argv"] + +PathLike = Union[str, "os.PathLike[str]"] + + +@dataclass +class TaskUsage: + """Token counts the agent reported for the run.""" + + input_tokens: int = 0 + output_tokens: int = 0 + cache_creation_tokens: int = 0 + cache_read_tokens: int = 0 + + @classmethod + def from_json(cls, data: Optional[Mapping[str, Any]]) -> "TaskUsage": + data = data or {} + return cls( + input_tokens=int(data.get("input_tokens") or 0), + output_tokens=int(data.get("output_tokens") or 0), + cache_creation_tokens=int(data.get("cache_creation_tokens") or 0), + cache_read_tokens=int(data.get("cache_read_tokens") or 0), + ) + + +@dataclass +class TaskResult: + """The ``result`` object ``incode -t ... --output-format json`` prints (src/task_run.rs). + + ``result`` is the agent's final answer when the run succeeded; ``error`` says + why it did not. ``cost_usd`` is ``None`` for a model incode has no price for. + ``raw`` is the whole object as printed, for fields this class does not name. + """ + + is_error: bool + result: Optional[str] + error: Optional[str] + session_id: str + agent: Optional[str] + model: Optional[str] + agent_session_id: Optional[str] + stop_reason: Optional[str] + served_by: List[str] + usage: TaskUsage + cost_usd: Optional[float] + duration_ms: Optional[int] + spec_gate: Optional[str] + exit_code: int = 0 + stderr: str = "" + raw: Dict[str, Any] = field(default_factory=dict) + + @classmethod + def from_json(cls, data: Mapping[str, Any], *, exit_code: int = 0, stderr: str = "") -> "TaskResult": + cost = data.get("cost_usd") + duration = data.get("duration_ms") + return cls( + is_error=bool(data.get("is_error")), + result=data.get("result"), + error=data.get("error"), + session_id=str(data.get("session_id") or ""), + agent=data.get("agent"), + model=data.get("model"), + agent_session_id=data.get("agent_session_id"), + stop_reason=data.get("stop_reason"), + served_by=list(data.get("served_by") or []), + usage=TaskUsage.from_json(data.get("usage")), + cost_usd=float(cost) if isinstance(cost, (int, float)) else None, + duration_ms=int(duration) if isinstance(duration, (int, float)) else None, + spec_gate=data.get("spec_gate"), + exit_code=exit_code, + stderr=stderr, + raw=dict(data), + ) + + +def build_task_argv( + task: str, + *, + workspace: Optional[PathLike] = None, + model: Optional[str] = None, + permission_mode: Optional[str] = None, + incode_path: Union[PathLike, Sequence[str]] = "incode", + extra_args: Sequence[str] = (), +) -> List[str]: + """The command line :func:`run_task` runs.""" + argv = _command(incode_path) + argv += ["-t", task, "--output-format", "json"] + if workspace is not None: + argv += ["-w", os.fspath(workspace)] + if model: + argv += ["-m", model] + if permission_mode: + argv += ["-p", permission_mode] + argv += list(extra_args) + return argv + + +def _command(incode_path: Union[PathLike, Sequence[str]]) -> List[str]: + if isinstance(incode_path, (str, bytes)) or hasattr(incode_path, "__fspath__"): + return [os.fspath(incode_path)] # type: ignore[arg-type] + return [os.fspath(part) for part in incode_path] + + +def _last_json_object(stdout: str) -> Optional[Dict[str, Any]]: + """The last line of stdout that is a JSON object (the ``result``).""" + for line in reversed(stdout.splitlines()): + line = line.strip() + if not line: + continue + try: + value = json.loads(line) + except ValueError: + return None + return value if isinstance(value, dict) else None + return None + + +def run_task( + task: str, + *, + workspace: Optional[PathLike] = None, + model: Optional[str] = None, + permission_mode: Optional[str] = None, + timeout: Optional[float] = None, + incode_path: Union[PathLike, Sequence[str]] = "incode", + env: Optional[Mapping[str, str]] = None, + extra_args: Sequence[str] = (), +) -> TaskResult: + """Run one instruction with ``incode -t`` and return its parsed result. + + Raises :class:`TaskFailed` when incode reports ``is_error: true`` (the + parsed result is on ``.result``), :class:`IncodeTimeout` when ``timeout`` + seconds pass (the process is killed), and :class:`IncodeError` when incode + cannot be started or exits without a result object. Every error carries + incode's stderr. + + Note: incode 0.1.0 accepts ``-p`` together with ``-t`` but does not apply it; + the one-shot run uses the agent CLI's own permission handling. + """ + argv = build_task_argv( + task, + workspace=workspace, + model=model, + permission_mode=permission_mode, + incode_path=incode_path, + extra_args=extra_args, + ) + full_env = None + if env is not None: + full_env = dict(os.environ) + full_env.update(env) + try: + proc = subprocess.run( + argv, + stdin=subprocess.DEVNULL, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + timeout=timeout, + env=full_env, + ) + except FileNotFoundError as e: + raise IncodeError("could not start incode: %s (looked for %r)" % (e.strerror, argv[0])) from e + except PermissionError as e: + raise IncodeError("could not start incode: %s (%r)" % (e.strerror, argv[0])) from e + except subprocess.TimeoutExpired as e: + stderr = _text(e.stderr) + raise IncodeTimeout("incode -t did not finish within %ss" % timeout, stderr=stderr) from e + + stdout = _text(proc.stdout) + stderr = _text(proc.stderr) + data = _last_json_object(stdout) + if data is None: + if proc.returncode != 0: + raise IncodeError("incode -t failed before producing a result", stderr=stderr, exit_code=proc.returncode) + raise ProtocolError( + "incode -t printed no JSON result object (stdout: %r)" % stdout[-500:], + stderr=stderr, + exit_code=proc.returncode, + ) + result = TaskResult.from_json(data, exit_code=proc.returncode, stderr=stderr) + if result.is_error or proc.returncode != 0: + raise TaskFailed( + "incode -t reported an error: %s" % (result.error or "unknown error"), + result=result, + stderr=stderr, + exit_code=proc.returncode, + ) + return result + + +def _text(data: Any) -> str: + if data is None: + return "" + if isinstance(data, bytes): + return data.decode("utf-8", errors="replace") + return str(data) diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml new file mode 100644 index 0000000..30eeff7 --- /dev/null +++ b/sdk/python/pyproject.toml @@ -0,0 +1,23 @@ +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + +[project] +name = "incode_sdk" +version = "0.1.0" +description = "Drive the incode coding agent from Python: one-shot tasks and ACP sessions" +readme = "README.md" +requires-python = ">=3.9" +license = { text = "Apache-2.0" } +dependencies = [] +classifiers = [ + "Programming Language :: Python :: 3", + "Operating System :: POSIX", + "Typing :: Typed", +] + +[tool.setuptools] +packages = ["incode_sdk"] + +[tool.setuptools.package-data] +incode_sdk = ["py.typed"] diff --git a/sdk/python/tests/_support.py b/sdk/python/tests/_support.py new file mode 100644 index 0000000..7f0fe85 --- /dev/null +++ b/sdk/python/tests/_support.py @@ -0,0 +1,14 @@ +"""Shared test helpers: puts the package on sys.path and names the fake incode.""" + +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +PACKAGE_ROOT = os.path.dirname(HERE) +if PACKAGE_ROOT not in sys.path: + sys.path.insert(0, PACKAGE_ROOT) + +FAKE_INCODE = os.path.join(os.path.dirname(PACKAGE_ROOT), "testing", "fake_incode.py") +# Run through this interpreter, so the tests do not depend on the script's +# executable bit or on a `python3` on PATH. +FAKE = [sys.executable, FAKE_INCODE] diff --git a/sdk/python/tests/test_live.py b/sdk/python/tests/test_live.py new file mode 100644 index 0000000..9be69d7 --- /dev/null +++ b/sdk/python/tests/test_live.py @@ -0,0 +1,32 @@ +"""Against the real binary: set INCODE_BIN=/path/to/incode to run; skipped otherwise. + +Only `initialize` and `session/new` are exercised — no turn is run, so no agent +CLI or subscription is needed. +""" + +import os +import tempfile +import unittest + +import _support # noqa: F401 (puts the package on sys.path) + +from incode_sdk import Session + +INCODE_BIN = os.environ.get("INCODE_BIN") + + +@unittest.skipUnless(INCODE_BIN, "set INCODE_BIN to run the live test against a real incode") +class LiveAcpTest(unittest.TestCase): + def test_initialize_and_session_new(self): + with tempfile.TemporaryDirectory() as ws: + with Session(ws, incode_path=INCODE_BIN, request_timeout=60) as s: + self.assertEqual(s.protocol_version, 1) + self.assertEqual(s.agent_info.get("name"), "incode") + self.assertTrue(s.session_id) + self.assertIn("workspace-write", [m["id"] for m in s.available_modes]) + self.assertTrue(s.current_mode) + self.assertTrue(any(o.get("id") == "agent" for o in s.config_options)) + + +if __name__ == "__main__": + unittest.main() diff --git a/sdk/python/tests/test_session.py b/sdk/python/tests/test_session.py new file mode 100644 index 0000000..9897d97 --- /dev/null +++ b/sdk/python/tests/test_session.py @@ -0,0 +1,355 @@ +import asyncio +import json +import os +import tempfile +import threading +import time +import unittest + +from _support import FAKE + +from incode_sdk import ( + AcpError, + AgentCrashed, + AvailableCommands, + IncodeError, + MessageChunk, + ModeChanged, + Plan, + PromptResult, + Session, + ThoughtChunk, + ToolCall, + ToolCallUpdate, + UnknownUpdate, + Usage, + UserMessageChunk, +) +from incode_sdk.aio import AsyncSession + + +def run(stream): + """Every event of a prompt, and its result.""" + events = list(stream) + assert isinstance(events[-1], PromptResult), events + return events[:-1], events[-1] + + +class SessionTestBase(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.root = os.path.realpath(self.tmp.name) + self.ws = os.path.join(self.root, "ws") + os.mkdir(self.ws) + + def tearDown(self): + self.tmp.cleanup() + + def session(self, **kwargs): + kwargs.setdefault("incode_path", FAKE) + kwargs.setdefault("request_timeout", 10) + return Session(self.ws, **kwargs) + + def started(self, **kwargs): + """Started, and past the available_commands_update incode sends after answering session/new.""" + s = self.session(**kwargs) + s.start() + deadline = time.time() + 5 + while not any(isinstance(e, AvailableCommands) for e in s.idle_events): + if time.time() > deadline: + s.close() + raise AssertionError("no available_commands_update") + time.sleep(0.01) + return s + + +class StartTest(SessionTestBase): + def test_start_opens_a_session(self): + argv_file = os.path.join(self.root, "argv.json") + with self.session(model="opus", permission_mode="read-only", env={"FAKE_INCODE_ARGV": argv_file}) as s: + self.assertEqual(s.session_id, "fake-session-1") + self.assertEqual(s.protocol_version, 1) + self.assertEqual(s.agent_info["name"], "incode") + self.assertTrue(s.agent_capabilities["loadSession"]) + self.assertEqual(s.current_mode, "read-only") + self.assertEqual([m["id"] for m in s.available_modes], ["read-only", "workspace-write", "danger-full-access"]) + self.assertEqual([o["id"] for o in s.config_options], ["agent", "role"]) + deadline = time.time() + 5 + while not s.idle_events and time.time() < deadline: + time.sleep(0.02) + self.assertIsInstance(s.idle_events[0], AvailableCommands) + self.assertEqual(s.idle_events[0].commands[0]["name"], "run") + with open(argv_file) as f: + self.assertEqual(json.load(f), ["--acp", "-m", "opus", "-p", "read-only"]) + self.assertIsNotNone(s.returncode) + + def test_on_update_hears_idle_updates(self): + heard = [] + got = threading.Event() + with self.session(on_update=lambda e: (heard.append(e), got.set())): + self.assertTrue(got.wait(5)) + self.assertIsInstance(heard[0], AvailableCommands) + + def test_a_refused_start_raises_with_stderr(self): + with self.assertRaises(AgentCrashed) as caught: + self.session(permission_mode="prompt").start() + self.assertEqual(caught.exception.exit_code, 1) + self.assertIn("--acp", caught.exception.stderr) + + def test_a_missing_workspace_is_refused_by_the_agent(self): + s = Session(os.path.join(self.root, "missing"), incode_path=FAKE, request_timeout=10) + with self.assertRaises(AcpError) as caught: + s.start() + self.assertEqual(caught.exception.code, -32602) + self.assertEqual(caught.exception.method, "session/new") + + def test_missing_binary(self): + with self.assertRaises(IncodeError): + Session(self.ws, incode_path=os.path.join(self.root, "nope")).start() + + def test_load_replays_history(self): + with self.session(load_session_id="kept-session") as s: + self.assertEqual(s.session_id, "kept-session") + kinds = [type(e) for e in s.idle_events] + self.assertEqual(kinds[:2], [UserMessageChunk, MessageChunk]) + self.assertEqual(s.idle_events[0].text, "remember the parser") + with self.assertRaises(AcpError): + self.session(load_session_id="no-such").start() + + +class PromptTest(SessionTestBase): + def test_prompt_streams_typed_events_then_the_result(self): + with self.started() as s: + stream = s.prompt("hello") + events, result = run(stream) + self.assertEqual(result.stop_reason, "end_turn") + self.assertIs(stream.result, result) + types = [type(e) for e in events] + self.assertEqual( + types, + [ThoughtChunk, MessageChunk, ToolCall, ToolCallUpdate, Plan, Usage, UnknownUpdate, MessageChunk], + ) + self.assertEqual(stream.text, "Hello (mode workspace-write, agent claude-code)\n") + call, done, plan, usage, unknown = events[2], events[3], events[4], events[5], events[6] + self.assertEqual((call.tool_call_id, call.kind, call.status, call.title), ("t1", "read", "in_progress", "Read a.txt")) + self.assertEqual(call.raw_input, {"path": "a.txt"}) + self.assertEqual((done.tool_call_id, done.status, done.raw_output), ("t1", "completed", "contents of a")) + self.assertEqual([(e.content, e.priority, e.status) for e in plan.entries][0], ("Read a.txt", "high", "completed")) + self.assertEqual((usage.used, usage.size), (38833, 1000000)) + self.assertEqual(unknown.kind, "some_future_update") + self.assertEqual(events[0].session_id, "fake-session-1") + # A second prompt in the same session. + self.assertEqual(s.prompt("hello again").wait().stop_reason, "end_turn") + + def test_content_blocks_are_accepted(self): + with self.started() as s: + stream = s.prompt([{"type": "text", "text": "hello"}]) + self.assertEqual(stream.wait().stop_reason, "end_turn") + + def test_one_prompt_at_a_time(self): + with self.started() as s: + stream = s.prompt("wait") + with self.assertRaises(IncodeError): + s.prompt("hello") + s.cancel() + self.assertEqual(stream.wait().stop_reason, "cancelled") + + def test_set_mode_and_config_option(self): + with self.started() as s: + s.set_mode("read-only") + self.assertEqual(s.current_mode, "read-only") + options = s.set_config_option("agent", "codex") + agent = [o for o in options if o["id"] == "agent"][0] + self.assertEqual(agent["currentValue"], "codex") + stream = s.prompt("hello") + stream.wait() + self.assertIn("mode read-only, agent codex", stream.text) + self.assertTrue(any(isinstance(e, ModeChanged) and e.mode_id == "read-only" for e in s.idle_events)) + with self.assertRaises(AcpError) as caught: + s.set_mode("yolo") + self.assertEqual(caught.exception.code, -32602) + with self.assertRaises(AcpError): + s.set_config_option("agent", "not-installed") + + def test_async_session(self): + async def go(): + async with AsyncSession(self.ws, incode_path=FAKE) as s: + seen = [e async for e in s.prompt("hello")] + await s.set_mode("read-only") + return seen + + seen = asyncio.run(go()) + self.assertIsInstance(seen[-1], PromptResult) + self.assertEqual(seen[-1].stop_reason, "end_turn") + + +class PermissionTest(SessionTestBase): + def test_default_rejects(self): + with self.started() as s: + stream = s.prompt("permission") + events, result = run(stream) + self.assertEqual(result.stop_reason, "end_turn") + self.assertIn("permission: reject", stream.text) + update = [e for e in events if isinstance(e, ToolCallUpdate)][0] + self.assertEqual(update.status, "failed") + + def test_round_trip_allow(self): + asked = [] + + def decide(request): + asked.append(request) + return request.allow() + + with self.started(on_permission=decide) as s: + stream = s.prompt("permission") + stream.wait() + self.assertIn("permission: allow", stream.text) + request = asked[0] + self.assertEqual(request.session_id, "fake-session-1") + self.assertEqual(request.tool_call_id, "g1") + self.assertIn("writing here needs the owner", request.title) + self.assertEqual([o.kind for o in request.options], ["allow_once", "reject_once"]) + + def test_bool_none_and_bad_answers(self): + for decision, said in ((True, "permission: allow"), (False, "permission: reject"), (None, "permission: cancelled"), ("bogus", "permission: reject")): + with self.started(on_permission=lambda r, d=decision: d) as s: + stream = s.prompt("permission") + stream.wait() + self.assertIn(said, stream.text, decision) + + def test_a_raising_callback_rejects(self): + def boom(request): + raise RuntimeError("callback bug") + + with self.started(on_permission=boom) as s: + stream = s.prompt("permission") + stream.wait() + self.assertIn("permission: reject", stream.text) + self.assertIn("callback bug", str(s.callback_errors[0])) + + def test_cancel_answers_an_open_question_cancelled(self): + asked = threading.Event() + release = threading.Event() + + def slow(request): + asked.set() + release.wait(10) + return request.allow() + + with self.started(on_permission=slow) as s: + stream = s.prompt("permission-wait") + self.assertTrue(asked.wait(5)) + s.cancel() + result = stream.wait() + release.set() + self.assertEqual(result.stop_reason, "cancelled") + self.assertIn("permission answer after cancel: cancelled", stream.text) + + +class FsTest(SessionTestBase): + def fs_prompt(self, s, read_path, write_path): + stream = s.prompt("fs %s %s" % (read_path, write_path)) + self.assertEqual(stream.wait().stop_reason, "end_turn") + return stream.text + + def test_read_and_write_inside_the_workspace(self): + with open(os.path.join(self.ws, "in.txt"), "w") as f: + f.write("hello from the workspace") + with self.started() as s: + text = self.fs_prompt(s, os.path.join(self.ws, "in.txt"), os.path.join(self.ws, "sub", "out.txt")) + self.assertIn("read: hello from the workspace", text) + self.assertIn("write: ok", text) + with open(os.path.join(self.ws, "sub", "out.txt")) as f: + self.assertEqual(f.read(), "written by fake\n") + + def test_refused_outside_the_workspace(self): + secret = os.path.join(self.root, "secret.txt") + with open(secret, "w") as f: + f.write("do not read") + outside = os.path.join(self.root, "out.txt") + os.symlink(self.root, os.path.join(self.ws, "escape")) + cases = [ + (secret, outside), + (os.path.join(self.ws, "..", "secret.txt"), os.path.join(self.ws, "..", "out.txt")), + (os.path.join(self.ws, "escape", "secret.txt"), os.path.join(self.ws, "escape", "out.txt")), + # A symlink followed by `..`: resolved as the OS does, not lexically. + (self.ws + "/escape/ws/../secret.txt", self.ws + "/escape/ws/../out.txt"), + ] + with self.started() as s: + for read_path, write_path in cases: + text = self.fs_prompt(s, read_path, write_path) + self.assertIn("read error: -32602 access denied", text) + self.assertIn("write error: -32602 access denied", text) + self.assertNotIn("do not read", text) + self.assertFalse(os.path.exists(outside)) + + def test_missing_file_is_resource_not_found(self): + with self.started() as s: + text = self.fs_prompt(s, os.path.join(self.ws, "nope.txt"), os.path.join(self.ws, "ok.txt")) + self.assertIn("read error: -32002", text) + + def test_disabled_and_custom_handlers(self): + writes = [] + with self.started(on_read_file=False, on_write_file=lambda req: writes.append(req)) as s: + text = self.fs_prompt(s, "/anything", "/virtual/out.txt") + self.assertIn("read error: -32601", text) + self.assertIn("write: ok", text) + self.assertEqual(writes[0].path, "/virtual/out.txt") + self.assertEqual(writes[0].content, "written by fake\n") + + +class FailureTest(SessionTestBase): + def test_cancel_ends_the_prompt_cancelled(self): + with self.started() as s: + stream = s.prompt("wait") + first = next(stream) + self.assertIsInstance(first, MessageChunk) + self.assertEqual(first.text, "working") + started = time.monotonic() + stream.cancel() + self.assertEqual(stream.wait().stop_reason, "cancelled") + self.assertLess(time.monotonic() - started, 5) + # The session is usable afterwards. + self.assertEqual(s.prompt("hello").wait().stop_reason, "end_turn") + + def test_agent_crash_mid_prompt(self): + with self.started() as s: + stream = s.prompt("crash") + first = next(stream) + self.assertEqual(first.text, "about to crash") + with self.assertRaises(AgentCrashed) as caught: + next(stream) + self.assertEqual(caught.exception.exit_code, 3) + self.assertIn("crashed mid-prompt", caught.exception.stderr) + with self.assertRaises(AgentCrashed): + s.prompt("hello") + with self.assertRaises(AgentCrashed): + s.set_mode("read-only") + + def test_malformed_lines_are_skipped(self): + heard = [] + with self.started(on_protocol_error=lambda line, e: heard.append(line)) as s: + stream = s.prompt("malformed") + self.assertEqual(stream.wait().stop_reason, "end_turn") + self.assertEqual(stream.text, "still alive") + self.assertEqual(s.prompt("hello").wait().stop_reason, "end_turn") + self.assertEqual(len(heard), 4, heard) + self.assertIn("this is not json", heard) + + def test_unknown_agent_request_is_method_not_found(self): + with self.started() as s: + stream = s.prompt("unknown-request") + stream.wait() + self.assertIn("terminal/create -> -32601", stream.text) + + def test_prompt_timeout(self): + from incode_sdk import IncodeTimeout + + with self.started() as s: + stream = s.prompt("wait", timeout=0.5) + with self.assertRaises(IncodeTimeout): + stream.wait() + + +if __name__ == "__main__": + unittest.main() diff --git a/sdk/python/tests/test_task.py b/sdk/python/tests/test_task.py new file mode 100644 index 0000000..2e0b7f0 --- /dev/null +++ b/sdk/python/tests/test_task.py @@ -0,0 +1,118 @@ +import asyncio +import json +import os +import tempfile +import unittest + +from _support import FAKE + +from incode_sdk import IncodeError, IncodeTimeout, ProtocolError, TaskFailed, TaskResult, run_task +from incode_sdk.aio import run_task_async +from incode_sdk.task import build_task_argv + + +class RunTaskTest(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.ws = self.tmp.name + + def tearDown(self): + self.tmp.cleanup() + + def test_success_is_parsed(self): + argv_file = os.path.join(self.ws, "argv.json") + result = run_task( + "add a test", + workspace=self.ws, + model="sonnet", + permission_mode="read-only", + incode_path=FAKE, + env={"FAKE_INCODE_ARGV": argv_file}, + ) + self.assertIsInstance(result, TaskResult) + self.assertFalse(result.is_error) + self.assertEqual(result.result, "done: add a test") + self.assertIsNone(result.error) + self.assertEqual(result.model, "sonnet") + self.assertEqual(result.agent, "claude-code") + self.assertEqual(result.stop_reason, "end_turn") + self.assertEqual(result.served_by, ["claude-code"]) + self.assertEqual(result.usage.input_tokens, 120) + self.assertEqual(result.usage.output_tokens, 45) + self.assertEqual(result.usage.cache_creation_tokens, 7) + self.assertEqual(result.usage.cache_read_tokens, 300) + self.assertAlmostEqual(result.cost_usd, 0.0123) + self.assertEqual(result.duration_ms, 42) + self.assertEqual(result.spec_gate, "on") + self.assertEqual(result.exit_code, 0) + self.assertIn("fake: running", result.stderr) + with open(argv_file) as f: + argv = json.load(f) + self.assertEqual( + argv, + ["-t", "add a test", "--output-format", "json", "-w", self.ws, "-m", "sonnet", "-p", "read-only"], + ) + + def test_reported_failure_raises_task_failed_with_result_and_stderr(self): + with self.assertRaises(TaskFailed) as caught: + run_task("fail please", workspace=self.ws, incode_path=FAKE) + e = caught.exception + self.assertEqual(e.exit_code, 1) + self.assertTrue(e.result.is_error) + self.assertEqual(e.result.error, "the agent failed: fake failure") + self.assertIsNone(e.result.cost_usd) + self.assertIn("fake: running", e.stderr) + self.assertIn("fake failure", str(e)) + + def test_crash_without_result_raises_incode_error_with_stderr(self): + with self.assertRaises(IncodeError) as caught: + run_task("crash", workspace=self.ws, incode_path=FAKE) + e = caught.exception + self.assertNotIsInstance(e, TaskFailed) + self.assertEqual(e.exit_code, 2) + self.assertIn("could not start", e.stderr) + self.assertIn("could not start", str(e)) + + def test_bad_workspace_is_an_error(self): + with self.assertRaises(IncodeError) as caught: + run_task("x", workspace=os.path.join(self.ws, "missing"), incode_path=FAKE) + self.assertIn("not a directory", caught.exception.stderr) + + def test_non_json_stdout_is_a_protocol_error(self): + with self.assertRaises(ProtocolError): + run_task("garbage", workspace=self.ws, incode_path=FAKE) + + def test_timeout_kills_and_raises(self): + with self.assertRaises(IncodeTimeout): + run_task("sleep", workspace=self.ws, incode_path=FAKE, timeout=1) + + def test_missing_binary(self): + with self.assertRaises(IncodeError) as caught: + run_task("x", incode_path=os.path.join(self.ws, "no-such-incode")) + self.assertIn("could not start incode", str(caught.exception)) + + def test_result_shape_of_the_real_binary_parses(self): + # As printed by incode 0.1.0 for an empty instruction (cost_usd absent). + line = ( + '{"type":"result","is_error":true,"session_id":"","agent":null,"model":null,' + '"agent_session_id":null,"stop_reason":null,"served_by":[],"usage":{"input_tokens":0,' + '"output_tokens":0,"cache_creation_tokens":0,"cache_read_tokens":0},"duration_ms":0,' + '"spec_gate":"on","error":"nothing to do: the instruction is empty"}' + ) + r = TaskResult.from_json(json.loads(line), exit_code=1) + self.assertTrue(r.is_error) + self.assertIsNone(r.cost_usd) + self.assertIsNone(r.result) + self.assertEqual(r.error, "nothing to do: the instruction is empty") + self.assertEqual(r.raw["type"], "result") + + def test_argv(self): + self.assertEqual(build_task_argv("hi"), ["incode", "-t", "hi", "--output-format", "json"]) + + def test_async(self): + result = asyncio.run(run_task_async("hello", workspace=self.ws, incode_path=FAKE)) + self.assertEqual(result.result, "done: hello") + + +if __name__ == "__main__": + unittest.main() diff --git a/sdk/testing/fake_incode.py b/sdk/testing/fake_incode.py new file mode 100755 index 0000000..a9935cd --- /dev/null +++ b/sdk/testing/fake_incode.py @@ -0,0 +1,497 @@ +#!/usr/bin/env python3 +"""A fake `incode` for the SDK test suites. + +It speaks just enough of the two interfaces the SDKs drive: + +* ``fake_incode.py -t --output-format json [-w DIR] [-m MODEL] [-p MODE]`` + prints one result object in the shape of ``src/task_run.rs`` (``Report::finish``). + The task text picks the scenario: + + ``fail`` -> ``is_error: true`` result, exit 1 + ``crash`` -> nothing on stdout, a message on stderr, exit 2 + ``garbage`` -> a line that is not JSON on stdout, exit 0 + ``sleep`` -> sleeps 30 s (for timeouts) + otherwise -> success, ``result`` is ``"done: "`` + +* ``fake_incode.py --acp`` speaks ACP (newline-delimited JSON-RPC 2.0) on + stdin/stdout, mirroring ``src/acp_agent``: ``initialize``, ``session/new``, + ``session/load``, ``session/prompt``, ``session/cancel``, ``session/set_mode``, + ``session/set_config_option``, ``session/close``. The prompt text picks the + scenario (the first word): + + ``hello`` thought, two message chunks, a tool call and its update, + a plan, a usage_update; ``end_turn`` (also the default) + ``permission`` sends ``session/request_permission`` and reports the answer + ``permission-wait`` sends ``session/request_permission`` and waits for a cancel + ``fs R W`` ``fs/read_text_file`` R, then ``fs/write_text_file`` W + ``wait`` says ``working`` and waits for ``session/cancel`` + ``crash`` one chunk, then the process exits 3 mid-prompt + ``malformed`` writes lines that are not JSON-RPC, then carries on + ``unknown-request`` sends ``terminal/create`` and reports the error it gets + +If ``FAKE_INCODE_ARGV`` is set, the argv is written there as JSON (both modes). +Python 3.9+, stdlib only. +""" + +import json +import os +import queue +import sys +import threading +import time + +PROTOCOL_VERSION = 1 +MODES = [ + {"id": "read-only", "name": "Read only", "description": "Proposes changes without making them."}, + {"id": "workspace-write", "name": "Workspace write", "description": "Edits files in the workspace."}, + {"id": "danger-full-access", "name": "Full access", "description": "Full access."}, +] + + +def record_argv(): + path = os.environ.get("FAKE_INCODE_ARGV") + if path: + with open(path, "w", encoding="utf-8") as f: + json.dump(sys.argv[1:], f) + + +def flag(args, *names): + for i, a in enumerate(args): + if a in names and i + 1 < len(args): + return args[i + 1] + return None + + +# ---------------------------------------------------------------- -t mode + + +def run_task(args): + task = flag(args, "-t", "--task") + fmt = flag(args, "--output-format") or "text" + model = flag(args, "-m", "--model") + workspace = flag(args, "-w", "--workspace") or os.getcwd() + if not os.path.isdir(workspace): + sys.stderr.write("Error: workspace `%s` is not a directory\n" % workspace) + return 1 + word = task.strip().split()[0] if task.strip() else "" + if word == "crash": + sys.stderr.write("fake: the agent could not start\n") + return 2 + if word == "sleep": + time.sleep(30) + return 0 + if word == "garbage": + sys.stdout.write("this is not json\n") + return 0 + sys.stderr.write("fake: running %r\n" % task) + failed = word == "fail" or not task.strip() + result = { + "type": "result", + "is_error": failed, + "session_id": "11111111-2222-3333-4444-555555555555", + "agent": "claude-code", + "model": model or "fake-model", + "agent_session_id": "agent-sess-1", + "stop_reason": None if failed else "end_turn", + "served_by": ["claude-code"], + "usage": { + "input_tokens": 120, + "output_tokens": 45, + "cache_creation_tokens": 7, + "cache_read_tokens": 300, + }, + "cost_usd": None if failed else 0.0123, + "duration_ms": 42, + "spec_gate": "on", + } + if failed: + result["error"] = "nothing to do: the instruction is empty" if not task.strip() else "the agent failed: fake failure" + else: + result["result"] = "done: " + task + if fmt in ("json", "stream-json"): + sys.stdout.write(json.dumps(result) + "\n") + else: + sys.stdout.write(result.get("result", "") + "\n") + sys.stdout.flush() + return 1 if failed else 0 + + +# ---------------------------------------------------------------- --acp mode + + +class Agent: + def __init__(self): + self.out_lock = threading.Lock() + self.next_id = 1000 + self.waiting = {} # request id -> queue for the client's answer + self.waiting_lock = threading.Lock() + self.sessions = {} # id -> dict(mode, agent, role, cancel Event, busy) + + # -- output + def write_raw(self, text): + with self.out_lock: + sys.stdout.write(text + "\n") + sys.stdout.flush() + + def send(self, message): + message = dict(message) + message["jsonrpc"] = "2.0" + self.write_raw(json.dumps(message)) + + def respond(self, rid, result=None, error=None): + if error is not None: + self.send({"id": rid, "error": error}) + else: + self.send({"id": rid, "result": result if result is not None else {}}) + + def update(self, session_id, update): + self.send({"method": "session/update", "params": {"sessionId": session_id, "update": update}}) + + def chunk(self, session_id, text, kind="agent_message_chunk"): + self.update(session_id, {"sessionUpdate": kind, "content": {"type": "text", "text": text}}) + + def ask(self, method, params, timeout=20.0): + """Send a request to the client; return its whole response message.""" + with self.waiting_lock: + self.next_id += 1 + rid = self.next_id + box = queue.Queue() + self.waiting[rid] = box + self.send({"id": rid, "method": method, "params": params}) + try: + return box.get(timeout=timeout) + except queue.Empty: + return {"error": {"code": -1, "message": "fake: no answer"}} + finally: + with self.waiting_lock: + self.waiting.pop(rid, None) + + # -- session state + def config_options(self, s): + return [ + { + "id": "agent", + "name": "Agent", + "type": "select", + "currentValue": s["agent"], + "options": [ + {"value": "claude-code", "name": "Claude Code"}, + {"value": "codex", "name": "Codex"}, + ], + }, + { + "id": "role", + "name": "Role", + "category": "model", + "type": "select", + "currentValue": s["role"], + "options": [{"value": v, "name": v.title()} for v in ("explore", "diagnose", "plan")], + }, + ] + + def open_session(self, sid, mode): + s = {"mode": mode, "agent": "claude-code", "role": "plan", "cancel": threading.Event(), "busy": False} + self.sessions[sid] = s + return s + + # -- dispatch + def handle_line(self, line): + if not line.strip(): + return + try: + msg = json.loads(line) + except ValueError as e: + self.respond(None, error={"code": -32700, "message": "Parse error", "data": str(e)}) + return + if not isinstance(msg, dict): + self.respond(None, error={"code": -32600, "message": "Invalid Request"}) + return + if "method" not in msg: + with self.waiting_lock: + box = self.waiting.get(msg.get("id")) + if box is not None: + box.put(msg) + return + method, params, rid = msg["method"], msg.get("params") or {}, msg.get("id") + if rid is None: + if method == "session/cancel": + s = self.sessions.get(params.get("sessionId")) + if s and s["busy"]: + s["cancel"].set() + return + handler = getattr(self, "m_" + method.replace("/", "_"), None) + if handler is None: + self.respond(rid, error={"code": -32601, "message": "Method not found"}) + return + handler(rid, params) + + def m_initialize(self, rid, params): + self.client_caps = params.get("clientCapabilities") or {} + self.respond( + rid, + { + "protocolVersion": PROTOCOL_VERSION, + "agentCapabilities": { + "loadSession": True, + "promptCapabilities": {"image": True, "audio": False, "embeddedContext": True}, + "mcpCapabilities": {"http": True, "sse": False}, + "sessionCapabilities": {"list": {}, "close": {}}, + }, + "authMethods": [], + "agentInfo": {"name": "incode", "title": "incode (fake)", "version": "0.0.0-fake"}, + }, + ) + + def check_cwd(self, rid, params): + cwd = params.get("cwd") + if not isinstance(cwd, str) or not os.path.isabs(cwd) or not os.path.isdir(cwd): + self.respond(rid, error={"code": -32602, "message": "Invalid params", "data": "cwd must be an absolute directory"}) + return False + return True + + def session_answer(self, sid, s): + return { + "sessionId": sid, + "modes": {"currentModeId": s["mode"], "availableModes": MODES}, + "configOptions": self.config_options(s), + } + + def m_session_new(self, rid, params): + if not self.check_cwd(rid, params): + return + sid = "fake-session-%d" % (len(self.sessions) + 1) + s = self.open_session(sid, START_MODE) + self.respond(rid, self.session_answer(sid, s)) + self.update( + sid, + { + "sessionUpdate": "available_commands_update", + "availableCommands": [{"name": "run", "description": "Work the ledger"}], + }, + ) + + def m_session_load(self, rid, params): + if not self.check_cwd(rid, params): + return + sid = params.get("sessionId") + if sid != "kept-session": + self.respond(rid, error={"code": -32602, "message": "Invalid params", "data": "no session `%s`" % sid}) + return + s = self.open_session(sid, START_MODE) + self.chunk(sid, "remember the parser", "user_message_chunk") + self.chunk(sid, "I will.") + self.respond(rid, self.session_answer(sid, s)) + + def m_session_close(self, rid, params): + s = self.sessions.pop(params.get("sessionId"), None) + if s: + s["cancel"].set() + self.respond(rid, {}) + + def m_session_set_mode(self, rid, params): + s = self.sessions.get(params.get("sessionId")) + mode = params.get("modeId") + if s is None or mode not in [m["id"] for m in MODES]: + self.respond(rid, error={"code": -32602, "message": "Invalid params", "data": "unknown mode or session"}) + return + s["mode"] = mode + self.respond(rid, {}) + self.update(params["sessionId"], {"sessionUpdate": "current_mode_update", "currentModeId": mode}) + + def m_session_set_config_option(self, rid, params): + s = self.sessions.get(params.get("sessionId")) + cid, value = params.get("configId"), params.get("value") + allowed = {"agent": ["claude-code", "codex"], "role": ["explore", "diagnose", "plan"]} + if s is None or cid not in allowed or value not in allowed[cid]: + self.respond(rid, error={"code": -32602, "message": "Invalid params", "data": "unknown option or value"}) + return + s[cid] = value + self.respond(rid, {"configOptions": self.config_options(s)}) + + def m_session_prompt(self, rid, params): + sid = params.get("sessionId") + s = self.sessions.get(sid) + if s is None: + self.respond(rid, error={"code": -32602, "message": "Invalid params", "data": "no session"}) + return + if s["busy"]: + self.respond(rid, error={"code": -32600, "message": "Invalid Request", "data": "a prompt is already running in this session"}) + return + s["busy"] = True + s["cancel"].clear() + text = "".join(b.get("text", "") for b in params.get("prompt") or [] if isinstance(b, dict)) + threading.Thread(target=self.turn, args=(rid, sid, s, text), daemon=True).start() + + # -- the scripted turns + def turn(self, rid, sid, s, text): + words = text.split() + word = words[0] if words else "hello" + try: + stop = getattr(self, "turn_" + word.replace("-", "_"), self.turn_hello)(sid, s, words[1:]) + finally: + s["busy"] = False + if stop is not None: + self.respond(rid, {"stopReason": stop}) + + def turn_hello(self, sid, s, args): + self.chunk(sid, "Thinking it over", "agent_thought_chunk") + self.chunk(sid, "Hel") + self.update( + sid, + { + "sessionUpdate": "tool_call", + "toolCallId": "t1", + "title": "Read a.txt", + "kind": "read", + "status": "in_progress", + "rawInput": {"path": "a.txt"}, + "locations": [{"path": "/ws/a.txt"}], + }, + ) + self.update( + sid, + { + "sessionUpdate": "tool_call_update", + "toolCallId": "t1", + "status": "completed", + "content": [{"type": "content", "content": {"type": "text", "text": "contents of a"}}], + "rawOutput": "contents of a", + }, + ) + self.update( + sid, + { + "sessionUpdate": "plan", + "entries": [ + {"content": "Read a.txt", "priority": "high", "status": "completed"}, + {"content": "Report", "priority": "medium", "status": "in_progress"}, + ], + }, + ) + self.update(sid, {"sessionUpdate": "usage_update", "used": 38833, "size": 1000000}) + self.update(sid, {"sessionUpdate": "some_future_update", "whatever": 1}) + self.chunk(sid, "lo (mode %s, agent %s)\n" % (s["mode"], s["agent"])) + return "end_turn" + + def permission_params(self, sid): + return { + "sessionId": sid, + "toolCall": { + "toolCallId": "g1", + "title": "Write guarded.txt — writing here needs the owner", + "kind": "edit", + "status": "pending", + "rawInput": {"path": "guarded.txt"}, + }, + "options": [ + {"optionId": "allow", "name": "Allow", "kind": "allow_once"}, + {"optionId": "reject", "name": "Reject", "kind": "reject_once"}, + ], + } + + def turn_permission(self, sid, s, args): + self.update(sid, {"sessionUpdate": "tool_call", "toolCallId": "g1", "title": "Write guarded.txt", "kind": "edit", "status": "pending"}) + answer = self.ask("session/request_permission", self.permission_params(sid)) + outcome = (answer.get("result") or {}).get("outcome") or {} + if outcome.get("outcome") == "selected": + said = "permission: " + str(outcome.get("optionId")) + elif outcome.get("outcome") == "cancelled": + said = "permission: cancelled" + else: + said = "permission: error %s" % json.dumps(answer.get("error")) + allowed = outcome.get("optionId") == "allow" + self.update(sid, {"sessionUpdate": "tool_call_update", "toolCallId": "g1", "status": "completed" if allowed else "failed"}) + self.chunk(sid, said) + return "end_turn" + + def turn_permission_wait(self, sid, s, args): + box = {} + + def ask(): + box["answer"] = self.ask("session/request_permission", self.permission_params(sid)) + + asker = threading.Thread(target=ask, daemon=True) + asker.start() + s["cancel"].wait(10) + asker.join(5) + outcome = ((box.get("answer") or {}).get("result") or {}).get("outcome") or {} + self.chunk(sid, "permission answer after cancel: %s" % outcome.get("outcome")) + return "cancelled" if s["cancel"].is_set() else "end_turn" + + def turn_fs(self, sid, s, args): + read_path = args[0] if args else "/nonexistent" + write_path = args[1] if len(args) > 1 else "/nonexistent-out" + got = self.ask("fs/read_text_file", {"sessionId": sid, "path": read_path}) + if "result" in got: + self.chunk(sid, "read: %s\n" % got["result"].get("content")) + else: + self.chunk(sid, "read error: %s %s\n" % (got["error"].get("code"), got["error"].get("message"))) + got = self.ask("fs/write_text_file", {"sessionId": sid, "path": write_path, "content": "written by fake\n"}) + if "result" in got: + self.chunk(sid, "write: ok\n") + else: + self.chunk(sid, "write error: %s %s\n" % (got["error"].get("code"), got["error"].get("message"))) + return "end_turn" + + def turn_wait(self, sid, s, args): + self.chunk(sid, "working") + if s["cancel"].wait(10): + return "cancelled" + self.chunk(sid, "nobody cancelled") + return "end_turn" + + def turn_crash(self, sid, s, args): + self.chunk(sid, "about to crash") + sys.stderr.write("fake: crashed mid-prompt\n") + sys.stderr.flush() + os._exit(3) + + def turn_malformed(self, sid, s, args): + self.write_raw("this is not json") + self.write_raw('{"jsonrpc": "2.0", "method": "session/update"') + self.write_raw("[1, 2, 3]") + self.write_raw('{"jsonrpc": "2.0", "id": 987654, "result": {}}') + self.chunk(sid, "still alive") + return "end_turn" + + def turn_unknown_request(self, sid, s, args): + got = self.ask("terminal/create", {"sessionId": sid, "command": "ls"}) + self.chunk(sid, "terminal/create -> %s" % json.dumps(got.get("error", {}).get("code"))) + return "end_turn" + + +START_MODE = "workspace-write" + + +def run_acp(args): + global START_MODE + mode = flag(args, "-p", "--permission-mode") + if mode: + if mode not in [m["id"] for m in MODES]: + sys.stderr.write("`--acp` runs as read-only, workspace-write or danger-full-access, not `%s`\n" % mode) + return 1 + START_MODE = mode + sys.stderr.write("incode ACP agent ready on stdio (fake)\n") + sys.stderr.flush() + agent = Agent() + for line in sys.stdin: + agent.handle_line(line.rstrip("\r\n")) + return 0 + + +def main(): + args = sys.argv[1:] + record_argv() + if "--acp" in args: + return run_acp(args) + if "-t" in args or "--task" in args: + return run_task(args) + if "-V" in args or "--version" in args: + print("incode 0.0.0-fake") + return 0 + sys.stderr.write("fake incode: unsupported invocation %r\n" % (args,)) + return 64 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md new file mode 100644 index 0000000..b8e37d4 --- /dev/null +++ b/sdk/typescript/README.md @@ -0,0 +1,113 @@ +# @incord/incode-sdk (TypeScript) + +Drive [incode](../../README.md) from Node 18+. No runtime dependencies; ESM with +type declarations. + +```sh +cd sdk/typescript && npm install && npm run build # dist/index.js + dist/index.d.ts +``` + +## One-shot: `runTask` + +Runs `incode -t "" --output-format json` and parses the result object. + +```ts +import { runTask, TaskFailed, IncodeError } from "@incord/incode-sdk"; + +try { + const r = await runTask("Add a unit test for parse_args", { + workspace: "/path/to/repo", + model: "sonnet", + timeoutMs: 600_000, + }); + console.log(r.result, r.usage.inputTokens, r.usage.outputTokens, r.costUsd /* may be null */); +} catch (e) { + if (e instanceof TaskFailed) console.error("failed:", e.result.error, e.exitCode); + else if (e instanceof IncodeError) console.error(e.message, e.stderr); + else throw e; +} +``` + +`TaskResult`: `isError, result, error, sessionId, agent, model, agentSessionId, +stopReason, servedBy, usage {inputTokens, outputTokens, cacheCreationTokens, +cacheReadTokens}, costUsd, durationMs, specGate, exitCode, stderr, raw`. +Options: `workspace`, `model`, `permissionMode` (note: incode does not currently +apply `-p` to `-t` runs), `timeoutMs`, `signal` (AbortSignal), `incodePath` (a +path, or a command prefix array), `env`, `extraArgs`. + +## Interactive: `Session` + +`incode --acp`, spoken over stdin/stdout as ACP (JSON-RPC 2.0, one message per +line). One `Session` is one process holding one ACP session. + +```ts +import { Session } from "@incord/incode-sdk"; + +const session = await Session.start({ + workspace: "/path/to/repo", + permissionMode: "workspace-write", + onPermission: async (request) => { + console.log("asked:", request.title); + return request.allow(); // or request.reject(), true/false, null (= cancelled) + }, +}); +try { + for await (const event of session.prompt("Explain what src/main.rs does")) { + switch (event.type) { + case "message_chunk": process.stdout.write(event.text); break; + case "tool_call": console.log(`\n[tool] ${event.title}`); break; + case "plan": console.log(event.entries); break; + case "prompt_result": console.log(`\nstop: ${event.stopReason}`); break; + } + } + await session.setMode("read-only"); + await session.setConfigOption("agent", "codex"); + const stream = session.prompt("And now?"); + const result = await stream.wait(); // stream.text holds the reply +} finally { + await session.close(); +} +``` + +- `prompt(textOrBlocks, { timeoutMs })` returns a `PromptStream`, an async + iterator whose last item is `{ type: "prompt_result", stopReason }`. It keeps + `.text`, `.events` and `.result`. One prompt at a time per session. +- `cancel()` sends `session/cancel` (the prompt ends `cancelled`) and answers + any open permission question `cancelled`. +- Event `type`s: `message_chunk`, `thought_chunk`, `user_message_chunk`, + `tool_call`, `tool_call_update`, `plan`, `usage` (context window + `used`/`size`), `mode_changed`, `config_options_changed`, + `available_commands`, `unknown`. Each has `sessionId` and `raw`. +- Updates that arrive while no prompt is running go to `onUpdate(event)` and + `idleEvents`. Updates are per session, not per prompt: one sent just as a + prompt starts lands in that prompt's stream. +- `onReadFile` / `onWriteFile` answer `fs/read_text_file` / `fs/write_text_file` + (sync or async). The defaults (`WorkspaceFs`) refuse any path whose real path + — symlinks followed, `..` resolved as the OS does — is outside the workspace, + with JSON-RPC error -32602. Pass `false` to not offer the capability. Throw + `new FsError(message, code)` from a custom handler to choose the error. +- Lines on incode's stdout that are not JSON-RPC are skipped and reported to + `onProtocolError(line, error)` and `protocolErrors`. +- If incode exits, every pending call and the running prompt reject with + `AgentCrashed` (`exitCode`, `stderr`). +- Other options: `loadSessionId`, `mcpServers`, `env`, `extraArgs`, + `requestTimeoutMs` (default 120000). Raw access: `request()`, `notify()`. + +## Errors + +`IncodeError` (base; `stderr`, `exitCode`) → `TaskFailed` (`result`), +`IncodeTimeout`, `ProtocolError`, `AcpError` (`method`, `code`, `data`), +`AgentCrashed`. + +## Tests + +```sh +cd sdk/typescript +npm install # once; needs the registry (typescript, @types/node) +npm test # compiles src+test to dist-test/, runs node --test; offline +# plus the live test against a real binary (initialize + session/new only): +INCODE_BIN=/path/to/incode npm test +``` + +The suite runs against `../testing/fake_incode.py` through `python3` (override +with `PYTHON=/path/to/python3`). diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json new file mode 100644 index 0000000..b6fad63 --- /dev/null +++ b/sdk/typescript/package-lock.json @@ -0,0 +1,51 @@ +{ + "name": "@incord/incode-sdk", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@incord/incode-sdk", + "version": "0.1.0", + "license": "Apache-2.0", + "devDependencies": { + "@types/node": "18.19.130", + "typescript": "5.9.3" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/@types/node": { + "version": "18.19.130", + "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz", + "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~5.26.4" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "5.26.5", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz", + "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==", + "dev": true, + "license": "MIT" + } + } +} diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json new file mode 100644 index 0000000..3d3a49b --- /dev/null +++ b/sdk/typescript/package.json @@ -0,0 +1,31 @@ +{ + "name": "@incord/incode-sdk", + "version": "0.1.0", + "description": "Drive the incode coding agent from Node: one-shot tasks and ACP sessions", + "license": "Apache-2.0", + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "scripts": { + "build": "tsc -p tsconfig.json", + "typecheck": "tsc -p tsconfig.test.json --noEmit", + "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js", + "prepack": "npm run build" + }, + "devDependencies": { + "@types/node": "18.19.130", + "typescript": "5.9.3" + } +} diff --git a/sdk/typescript/src/errors.ts b/sdk/typescript/src/errors.ts new file mode 100644 index 0000000..3151e5e --- /dev/null +++ b/sdk/typescript/src/errors.ts @@ -0,0 +1,59 @@ +/** Errors raised by the SDK. Every one carries incode's stderr (the tail, for a session). */ + +export interface ErrorDetails { + stderr?: string; + exitCode?: number | null; +} + +export class IncodeError extends Error { + readonly stderr: string; + readonly exitCode: number | null; + + constructor(message: string, details: ErrorDetails = {}) { + const stderr = details.stderr ?? ""; + const exitCode = details.exitCode ?? null; + let full = message; + if (exitCode !== null) full += ` (exit code ${exitCode})`; + const tail = stderr.trim(); + if (tail) full += `\n--- incode stderr ---\n${tail.slice(-2000)}`; + super(full); + this.name = new.target.name; + this.stderr = stderr; + this.exitCode = exitCode; + } +} + +/** `incode -t` ran and reported `is_error: true`; `result` is the parsed result. */ +export class TaskFailed extends IncodeError { + constructor( + message: string, + readonly result: import("./task.js").TaskResult, + details: ErrorDetails = {}, + ) { + super(message, details); + } +} + +/** The process or a request did not finish in time. */ +export class IncodeTimeout extends IncodeError {} + +/** incode wrote something the SDK could not understand where it needed to. */ +export class ProtocolError extends IncodeError {} + +/** incode answered an ACP request with a JSON-RPC error. */ +export class AcpError extends IncodeError { + constructor( + readonly method: string, + readonly code: number, + readonly rpcMessage: string, + readonly data?: unknown, + details: ErrorDetails = {}, + ) { + let text = `${method} failed: ${rpcMessage} (code ${code})`; + if (data !== undefined && data !== null) text += `: ${typeof data === "string" ? data : JSON.stringify(data)}`; + super(text, details); + } +} + +/** The `incode --acp` process went away while the SDK was waiting on it. */ +export class AgentCrashed extends IncodeError {} diff --git a/sdk/typescript/src/events.ts b/sdk/typescript/src/events.ts new file mode 100644 index 0000000..849e448 --- /dev/null +++ b/sdk/typescript/src/events.ts @@ -0,0 +1,271 @@ +/** Typed `session/update` events, permission requests and fs requests. */ + +export type Json = Record; + +interface Base { + sessionId: string; + /** The update object as sent. */ + raw: Json; +} + +export interface ContentChunkBase extends Base { + text: string; + content: Json; +} + +/** Part of the agent's reply (`agent_message_chunk`). */ +export interface MessageChunk extends ContentChunkBase { + type: "message_chunk"; +} +/** Part of the agent's reasoning (`agent_thought_chunk`). */ +export interface ThoughtChunk extends ContentChunkBase { + type: "thought_chunk"; +} +/** The person's own words, replayed by `session/load` (`user_message_chunk`). */ +export interface UserMessageChunk extends ContentChunkBase { + type: "user_message_chunk"; +} + +/** A tool call starts (`tool_call`). */ +export interface ToolCall extends Base { + type: "tool_call"; + toolCallId: string; + title: string; + kind: string | null; + status: string | null; + rawInput: unknown; + content: unknown[]; + locations: unknown[]; +} + +/** A tool call progresses or ends (`tool_call_update`). Unset fields are `null`. */ +export interface ToolCallUpdate extends Base { + type: "tool_call_update"; + toolCallId: string; + status: string | null; + title: string | null; + kind: string | null; + content: unknown[] | null; + rawInput: unknown; + rawOutput: unknown; +} + +export interface PlanEntry { + content: string; + priority: string | null; + status: string | null; +} + +/** The task list as it now stands (`plan`). */ +export interface Plan extends Base { + type: "plan"; + entries: PlanEntry[]; +} + +/** The context window's fill (`usage_update`). */ +export interface Usage extends Base { + type: "usage"; + used: number | null; + size: number | null; + cost: unknown; +} + +/** The permission mode changed (`current_mode_update`). */ +export interface ModeChanged extends Base { + type: "mode_changed"; + modeId: string; +} + +/** The pickers changed (`config_option_update`). */ +export interface ConfigOptionsChanged extends Base { + type: "config_options_changed"; + configOptions: Json[]; +} + +/** The slash commands on offer (`available_commands_update`). */ +export interface AvailableCommands extends Base { + type: "available_commands"; + commands: Json[]; +} + +/** A `session/update` kind this SDK does not model. */ +export interface UnknownUpdate extends Base { + type: "unknown"; + kind: string; +} + +export type SessionEvent = + | MessageChunk + | ThoughtChunk + | UserMessageChunk + | ToolCall + | ToolCallUpdate + | Plan + | Usage + | ModeChanged + | ConfigOptionsChanged + | AvailableCommands + | UnknownUpdate; + +/** How a prompt ended: end_turn, cancelled, max_tokens, max_turn_requests, refusal. */ +export interface PromptResult { + type: "prompt_result"; + stopReason: string; + raw: Json; +} + +function str(v: unknown): string | null { + return typeof v === "string" ? v : null; +} +function num(v: unknown): number | null { + return typeof v === "number" && Number.isFinite(v) ? v : null; +} +function obj(v: unknown): Json { + return v && typeof v === "object" && !Array.isArray(v) ? (v as Json) : {}; +} +function arr(v: unknown): unknown[] { + return Array.isArray(v) ? v : []; +} + +/** Turn one `params.update` object into a typed event. */ +export function parseUpdate(sessionId: string, update: Json): SessionEvent { + const raw = update; + const kind = str(update["sessionUpdate"]) ?? ""; + switch (kind) { + case "agent_message_chunk": + case "agent_thought_chunk": + case "user_message_chunk": { + const content = obj(update["content"]); + const text = content["type"] === "text" ? (str(content["text"]) ?? "") : ""; + const type = + kind === "agent_message_chunk" ? "message_chunk" : kind === "agent_thought_chunk" ? "thought_chunk" : "user_message_chunk"; + return { type, sessionId, text, content, raw }; + } + case "tool_call": + return { + type: "tool_call", + sessionId, + toolCallId: str(update["toolCallId"]) ?? "", + title: str(update["title"]) ?? "", + kind: str(update["kind"]), + status: str(update["status"]), + rawInput: update["rawInput"], + content: arr(update["content"]), + locations: arr(update["locations"]), + raw, + }; + case "tool_call_update": + return { + type: "tool_call_update", + sessionId, + toolCallId: str(update["toolCallId"]) ?? "", + status: str(update["status"]), + title: str(update["title"]), + kind: str(update["kind"]), + content: Array.isArray(update["content"]) ? update["content"] : null, + rawInput: update["rawInput"], + rawOutput: update["rawOutput"], + raw, + }; + case "plan": + return { + type: "plan", + sessionId, + entries: arr(update["entries"]).map((e) => { + const entry = obj(e); + return { content: str(entry["content"]) ?? "", priority: str(entry["priority"]), status: str(entry["status"]) }; + }), + raw, + }; + case "usage_update": + return { type: "usage", sessionId, used: num(update["used"]), size: num(update["size"]), cost: update["cost"], raw }; + case "current_mode_update": + return { type: "mode_changed", sessionId, modeId: str(update["currentModeId"]) ?? "", raw }; + case "config_option_update": + return { type: "config_options_changed", sessionId, configOptions: arr(update["configOptions"]).map(obj), raw }; + case "available_commands_update": + return { type: "available_commands", sessionId, commands: arr(update["availableCommands"]).map(obj), raw }; + default: + return { type: "unknown", sessionId, kind, raw }; + } +} + +// ------------------------------------------------------------ agent -> client requests + +export interface PermissionOption { + optionId: string; + name: string; + /** allow_once | allow_always | reject_once | reject_always */ + kind: string; +} + +/** + * `session/request_permission`: incode asks before a tool call runs. + * + * `onPermission` returns one of `options`' ids (or the option), `true` / + * `false`, or `null` for `cancelled`. `allow()` and `reject()` pick the + * matching option for you. + */ +export class PermissionRequest { + readonly sessionId: string; + readonly toolCall: Json; + readonly options: PermissionOption[]; + readonly raw: Json; + + constructor(params: Json) { + this.raw = params; + this.sessionId = str(params["sessionId"]) ?? ""; + this.toolCall = obj(params["toolCall"]); + this.options = arr(params["options"]).map((o) => { + const option = obj(o); + return { optionId: String(option["optionId"]), name: str(option["name"]) ?? "", kind: str(option["kind"]) ?? "" }; + }); + } + + get title(): string { + return str(this.toolCall["title"]) ?? ""; + } + + get toolCallId(): string { + return str(this.toolCall["toolCallId"]) ?? ""; + } + + optionOfKind(...kinds: string[]): string | null { + for (const kind of kinds) { + const found = this.options.find((o) => o.kind === kind); + if (found) return found.optionId; + } + return null; + } + + /** The allow-once option (or allow-always when that is all there is). */ + allow(): string | null { + return this.optionOfKind("allow_once", "allow_always"); + } + + allowAlways(): string | null { + return this.optionOfKind("allow_always", "allow_once"); + } + + /** The reject-once option (or reject-always); `null` (cancelled) when there is none. */ + reject(): string | null { + return this.optionOfKind("reject_once", "reject_always"); + } +} + +export type PermissionDecision = string | PermissionOption | boolean | null | undefined; + +/** `fs/read_text_file`. `line` is 1-based; `limit` is a number of lines. */ +export interface ReadFileRequest { + sessionId: string; + path: string; + line: number | null; + limit: number | null; +} + +/** `fs/write_text_file`. */ +export interface WriteFileRequest { + sessionId: string; + path: string; + content: string; +} diff --git a/sdk/typescript/src/fs.ts b/sdk/typescript/src/fs.ts new file mode 100644 index 0000000..2f9f438 --- /dev/null +++ b/sdk/typescript/src/fs.ts @@ -0,0 +1,112 @@ +/** + * The client's file system as offered to incode (`fs/read_text_file`, + * `fs/write_text_file`). The default handlers serve the workspace only: a path + * is resolved first — symlinks followed, `..` taken as the OS takes it — and + * refused when its real path is not under the workspace's real path. + */ + +import * as fs from "node:fs"; +import * as path from "node:path"; + +import type { ReadFileRequest, WriteFileRequest } from "./events.js"; + +export const INVALID_PARAMS = -32602; +export const RESOURCE_NOT_FOUND = -32002; +export const INTERNAL_ERROR = -32603; + +/** Throw from an fs callback to answer with this JSON-RPC error. */ +export class FsError extends Error { + constructor( + message: string, + readonly code: number = INTERNAL_ERROR, + ) { + super(message); + this.name = new.target.name; + } +} + +/** The path is outside the workspace (after resolving symlinks and `..`). */ +export class FsAccessDenied extends FsError { + constructor(message: string) { + super(message, INVALID_PARAMS); + } +} + +/** + * The real path of `p`: the longest prefix that exists is resolved by the OS + * (`realpath(3)`, so a symlink followed by `..` means what it means on disk), + * and the rest — which does not exist yet — is appended and normalised. + */ +export function realPath(p: string): string { + const absolute = path.isAbsolute(p) ? p : path.join(process.cwd(), p); + const { root } = path.parse(absolute); + const parts = absolute.slice(root.length).split(/[\\/]+/).filter((x) => x !== ""); + for (let i = parts.length; i >= 0; i--) { + const prefix = root + parts.slice(0, i).join(path.sep); + let real: string; + try { + real = fs.realpathSync.native(prefix); + } catch { + continue; + } + return path.resolve(real, ...parts.slice(i)); + } + return path.resolve(absolute); +} + +/** Reads and writes confined to one directory tree. */ +export class WorkspaceFs { + readonly root: string; + + constructor(root: string) { + this.root = realPath(path.resolve(root)); + } + + contains(real: string): boolean { + const rel = path.relative(this.root, real); + return rel === "" || (rel !== ".." && !rel.startsWith(".." + path.sep) && !path.isAbsolute(rel)); + } + + /** The real path of `p`, or `FsAccessDenied` when it is outside the root. */ + resolve(p: string): string { + if (typeof p !== "string" || p === "") throw new FsAccessDenied("access denied: no path given"); + if (p.includes("\0")) throw new FsAccessDenied("access denied: the path contains a NUL byte"); + // ACP paths are absolute; a relative one is taken against the root. + const absolute = path.isAbsolute(p) ? p : this.root + path.sep + p; + const real = realPath(absolute); + if (!this.contains(real)) throw new FsAccessDenied(`access denied: ${p} is outside the workspace ${this.root}`); + return real; + } + + async read(request: ReadFileRequest): Promise { + const real = this.resolve(request.path); + let text: string; + try { + text = await fs.promises.readFile(real, "utf8"); + } catch (e) { + const code = (e as NodeJS.ErrnoException).code; + if (code === "ENOENT") throw new FsError(`file not found: ${request.path}`, RESOURCE_NOT_FOUND); + if (code === "EISDIR") throw new FsError(`is a directory: ${request.path}`, INVALID_PARAMS); + throw e; + } + return sliceLines(text, request.line, request.limit); + } + + async write(request: WriteFileRequest): Promise { + let real = this.resolve(request.path); + await fs.promises.mkdir(path.dirname(real), { recursive: true }); + // Again, now that the parents exist: nothing may have become a symlink + // out of the tree in between. + real = this.resolve(real); + await fs.promises.writeFile(real, request.content, "utf8"); + } +} + +/** Lines `line` (1-based) onward, at most `limit` of them. */ +export function sliceLines(text: string, line: number | null, limit: number | null): string { + if (line === null && limit === null) return text; + const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? []; + const start = Math.max((line ?? 1) - 1, 0); + const end = limit === null ? lines.length : start + Math.max(limit, 0); + return lines.slice(start, end).join(""); +} diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts new file mode 100644 index 0000000..082f270 --- /dev/null +++ b/sdk/typescript/src/index.ts @@ -0,0 +1,36 @@ +/** + * Drive the incode coding agent from Node. + * + * - `runTask()` — one instruction, `incode -t ... --output-format json`. + * - `Session` — an interactive session over ACP, `incode --acp`. + */ + +export { AcpError, AgentCrashed, IncodeError, IncodeTimeout, ProtocolError, TaskFailed } from "./errors.js"; +export type { ErrorDetails } from "./errors.js"; +export { buildTaskArgv, parseTaskResult, runTask } from "./task.js"; +export type { IncodePath, RunTaskOptions, TaskResult, TaskUsage } from "./task.js"; +export { parseUpdate, PermissionRequest } from "./events.js"; +export type { + AvailableCommands, + ConfigOptionsChanged, + Json, + MessageChunk, + ModeChanged, + PermissionDecision, + PermissionOption, + Plan, + PlanEntry, + PromptResult, + ReadFileRequest, + SessionEvent, + ThoughtChunk, + ToolCall, + ToolCallUpdate, + UnknownUpdate, + Usage, + UserMessageChunk, + WriteFileRequest, +} from "./events.js"; +export { FsAccessDenied, FsError, INTERNAL_ERROR, INVALID_PARAMS, RESOURCE_NOT_FOUND, WorkspaceFs, realPath } from "./fs.js"; +export { allowAll, PROTOCOL_VERSION, PromptStream, rejectAll, Session } from "./session.js"; +export type { PermissionHandler, PromptOptions, ReadFileHandler, SessionOptions, WriteFileHandler } from "./session.js"; diff --git a/sdk/typescript/src/session.ts b/sdk/typescript/src/session.ts new file mode 100644 index 0000000..392db8f --- /dev/null +++ b/sdk/typescript/src/session.ts @@ -0,0 +1,674 @@ +/** + * Interactive sessions: `incode --acp` driven over ACP (JSON-RPC 2.0, one + * message per line on stdin/stdout). One `Session` is one process holding one + * ACP session. + */ + +import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"; +import * as path from "node:path"; +import { createInterface } from "node:readline"; + +import { AcpError, AgentCrashed, IncodeError, IncodeTimeout } from "./errors.js"; +import { + parseUpdate, + PermissionRequest, + type Json, + type PermissionDecision, + type PromptResult, + type ReadFileRequest, + type SessionEvent, + type WriteFileRequest, +} from "./events.js"; +import { FsError, INTERNAL_ERROR, INVALID_PARAMS, RESOURCE_NOT_FOUND, WorkspaceFs } from "./fs.js"; +import { commandOf, type IncodePath } from "./task.js"; + +export const PROTOCOL_VERSION = 1; +const METHOD_NOT_FOUND = -32601; +const STDERR_TAIL = 64 * 1024; +const SDK_VERSION = "0.1.0"; + +type MaybePromise = T | Promise; +export type PermissionHandler = (request: PermissionRequest) => MaybePromise; +export type ReadFileHandler = (request: ReadFileRequest) => MaybePromise; +export type WriteFileHandler = (request: WriteFileRequest) => MaybePromise; + +/** The default permission handler: pick the reject option (`cancelled` if there is none). */ +export const rejectAll: PermissionHandler = (request) => request.reject(); +/** Allow every call once. Only for trusted, sandboxed work. */ +export const allowAll: PermissionHandler = (request) => request.allow(); + +export interface SessionOptions { + /** The session's workspace (`cwd`). Default: `process.cwd()`. Made absolute. */ + workspace?: string; + /** The incode executable, or a command prefix. Default `"incode"`. */ + incodePath?: IncodePath; + /** `-m`. */ + model?: string; + /** `-p`: read-only | workspace-write | danger-full-access. */ + permissionMode?: string; + /** Answers `session/request_permission`. Default: reject. */ + onPermission?: PermissionHandler; + /** Answers `fs/read_text_file`. Default: the workspace only. `false`: not offered. */ + onReadFile?: ReadFileHandler | false; + /** Answers `fs/write_text_file`. Default: the workspace only. `false`: not offered. */ + onWriteFile?: WriteFileHandler | false; + /** `session/update` events that arrive while no prompt is running. Also kept in `idleEvents`. */ + onUpdate?: (event: SessionEvent) => void; + /** Lines on incode's stdout that are not JSON-RPC (they are skipped). */ + onProtocolError?: (line: string, error: Error) => void; + /** Load this kept session (`session/load`) instead of opening a new one. */ + loadSessionId?: string; + /** MCP servers for the session, in ACP's shape. */ + mcpServers?: Json[]; + /** Extra environment variables, on top of `process.env`. */ + env?: Record; + /** Extra arguments after `--acp`. */ + extraArgs?: readonly string[]; + /** How long to wait for a request's answer. Default 120000. `0` waits forever. */ + requestTimeoutMs?: number; +} + +export interface PromptOptions { + /** Bound the whole prompt; when it passes, a cancel is sent and the stream throws IncodeTimeout. */ + timeoutMs?: number; +} + +interface Pending { + method: string; + resolve: (message: Json) => void; + reject: (error: Error) => void; +} + +type Item = SessionEvent | PromptResult | Error; + +/** + * The events of one prompt, in order, ending with a `PromptResult` + * (`for await (const event of stream)`). `text` accumulates the agent's message + * chunks; `result` is set when the prompt ends; `wait()` consumes the rest. + */ +export class PromptStream implements AsyncIterableIterator { + text = ""; + result: PromptResult | undefined; + readonly events: SessionEvent[] = []; + private readonly items: Item[] = []; + private waiter: ((item: Item) => void) | undefined; + private finished = false; + private readonly deadline: number | undefined; + + constructor( + private readonly session: Session, + private readonly timeoutMs: number | undefined, + ) { + this.deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs; + } + + /** @internal */ + push(item: Item): void { + const waiter = this.waiter; + if (waiter) { + this.waiter = undefined; + waiter(item); + } else { + this.items.push(item); + } + } + + private take(): Promise { + const queued = this.items.shift(); + if (queued !== undefined) return Promise.resolve(queued); + return new Promise((resolve) => { + let timer: NodeJS.Timeout | undefined; + this.waiter = (item) => { + if (timer) clearTimeout(timer); + resolve(item); + }; + if (this.deadline !== undefined) { + timer = setTimeout( + () => { + this.waiter = undefined; + resolve("timeout"); + }, + Math.max(this.deadline - Date.now(), 0), + ); + } + }); + } + + async next(): Promise> { + if (this.finished) return { done: true, value: undefined }; + const item = await this.take(); + if (item === "timeout") { + this.finished = true; + this.session.cancel(); + throw new IncodeTimeout(`the prompt did not end within ${this.timeoutMs}ms (a cancel was sent)`, { + stderr: this.session.stderr, + }); + } + if (item instanceof Error) { + this.finished = true; + throw item; + } + if (item.type === "prompt_result") { + this.finished = true; + this.result = item; + return { done: false, value: item }; + } + if (item.type === "message_chunk") this.text += item.text; + this.events.push(item); + return { done: false, value: item }; + } + + async return(): Promise> { + // Breaking out of `for await` leaves the prompt running; cancel() stops it. + this.finished = true; + return { done: true, value: undefined }; + } + + [Symbol.asyncIterator](): this { + return this; + } + + /** Consume the remaining events and return how the prompt ended. */ + async wait(): Promise { + for (;;) { + const r = await this.next(); + if (r.done) break; + } + if (!this.result) throw new IncodeError("the prompt stream was abandoned before it ended"); + return this.result; + } + + cancel(): void { + this.session.cancel(); + } +} + +/** + * `incode --acp`. + * + * ```ts + * const session = await Session.start({ workspace: "/path/to/repo" }); + * try { + * for await (const event of session.prompt("Explain src/main.rs")) { ... } + * } finally { + * await session.close(); + * } + * ``` + */ +export class Session { + readonly workspace: string; + readonly fs: WorkspaceFs; + sessionId: string | undefined; + protocolVersion: number | undefined; + agentInfo: Json = {}; + agentCapabilities: Json = {}; + currentMode: string | undefined; + availableModes: Json[] = []; + configOptions: Json[] = []; + readonly idleEvents: SessionEvent[] = []; + readonly protocolErrors: string[] = []; + readonly callbackErrors: unknown[] = []; + + private readonly options: SessionOptions; + private readonly onPermission: PermissionHandler; + private readonly readFile: ReadFileHandler | undefined; + private readonly writeFile: WriteFileHandler | undefined; + private child: ChildProcessWithoutNullStreams | undefined; + private nextId = 1; + private readonly pending = new Map(); + private active: PromptStream | undefined; + private readonly openPermissions = new Map(); + private readonly answered = new Set(); + private stderrTail = ""; + private dead: IncodeError | undefined; + private closing = false; + private exited: Promise | undefined; + private exitCodeValue: number | null = null; + + constructor(options: SessionOptions = {}) { + this.options = options; + this.workspace = path.resolve(options.workspace ?? process.cwd()); + this.fs = new WorkspaceFs(this.workspace); + this.onPermission = options.onPermission ?? rejectAll; + this.readFile = options.onReadFile === false ? undefined : (options.onReadFile ?? ((r) => this.fs.read(r))); + this.writeFile = options.onWriteFile === false ? undefined : (options.onWriteFile ?? ((r) => this.fs.write(r))); + } + + /** Construct and `start()` in one step. */ + static async start(options: SessionOptions = {}): Promise { + const session = new Session(options); + await session.start(); + return session; + } + + /** The command line `start()` runs. */ + argv(): string[] { + const argv = commandOf(this.options.incodePath); + argv.push("--acp"); + if (this.options.model) argv.push("-m", this.options.model); + if (this.options.permissionMode) argv.push("-p", this.options.permissionMode); + argv.push(...(this.options.extraArgs ?? [])); + return argv; + } + + /** The last 64 KiB incode wrote to stderr. */ + get stderr(): string { + return this.stderrTail; + } + + /** The process's exit code once it has exited. */ + get exitCode(): number | null { + return this.exitCodeValue; + } + + /** Start `incode --acp`, `initialize`, and open (or load) the session. Resolves with its id. */ + async start(): Promise { + if (this.child) throw new IncodeError("this Session was already started"); + const [command, ...args] = this.argv(); + const child = spawn(command as string, args, { + stdio: ["pipe", "pipe", "pipe"], + env: this.options.env ? { ...process.env, ...this.options.env } : process.env, + }); + this.child = child; + child.stdin.on("error", () => { + /* EPIPE after the agent exits: reported through `close` instead. */ + }); + child.stderr.setEncoding("utf8"); + child.stderr.on("data", (d: string) => { + this.stderrTail = (this.stderrTail + d).slice(-STDERR_TAIL); + }); + const lines = createInterface({ input: child.stdout, crlfDelay: Infinity }); + lines.on("line", (line) => { + if (line.trim()) this.dispatch(line.trim()); + }); + this.exited = new Promise((resolve) => { + let spawnError: Error | undefined; + child.on("error", (err) => { + spawnError = err; + // A spawn failure may not be followed by `close`. + setTimeout(() => { + if (!this.dead) this.failAll(new IncodeError(`could not start incode: ${err.message} (${command})`, { stderr: this.stderr })); + resolve(); + }, 50); + }); + child.on("close", (code) => { + this.exitCodeValue = code; + let error: IncodeError; + if (spawnError) error = new IncodeError(`could not start incode: ${spawnError.message} (${command})`, { stderr: this.stderr }); + else if (this.closing) error = new IncodeError("the session was closed", { stderr: this.stderr, exitCode: code }); + else error = new AgentCrashed("incode --acp exited unexpectedly", { stderr: this.stderr, exitCode: code }); + this.failAll(error); + resolve(); + }); + }); + + try { + const init = await this.request("initialize", { + protocolVersion: PROTOCOL_VERSION, + clientCapabilities: { + fs: { readTextFile: this.readFile !== undefined, writeTextFile: this.writeFile !== undefined }, + terminal: false, + }, + clientInfo: { name: "incode-sdk-typescript", version: SDK_VERSION }, + }); + this.protocolVersion = typeof init["protocolVersion"] === "number" ? init["protocolVersion"] : undefined; + this.agentCapabilities = asObject(init["agentCapabilities"]); + this.agentInfo = asObject(init["agentInfo"]); + const mcpServers = this.options.mcpServers ?? []; + let opened: Json; + if (this.options.loadSessionId) { + opened = await this.request("session/load", { sessionId: this.options.loadSessionId, cwd: this.workspace, mcpServers }); + this.sessionId = this.options.loadSessionId; + } else { + opened = await this.request("session/new", { cwd: this.workspace, mcpServers }); + this.sessionId = String(opened["sessionId"]); + } + const modes = asObject(opened["modes"]); + this.currentMode = typeof modes["currentModeId"] === "string" ? modes["currentModeId"] : undefined; + this.availableModes = asArray(modes["availableModes"]).map(asObject); + this.configOptions = asArray(opened["configOptions"]).map(asObject); + return this.sessionId; + } catch (e) { + await this.close(); + throw e; + } + } + + /** Close the session and stop the process (stdin closed, then SIGTERM, then SIGKILL). */ + async close(timeoutMs = 5000): Promise { + const child = this.child; + if (!child || this.closing) { + await this.exited; + return; + } + const caps = asObject(this.agentCapabilities["sessionCapabilities"]); + if (!this.dead && this.sessionId && "close" in caps) { + try { + await this.request("session/close", { sessionId: this.sessionId }, Math.min(timeoutMs, 2000)); + } catch { + /* closing anyway */ + } + } + this.closing = true; + child.stdin.end(); + const exited = this.exited ?? Promise.resolve(); + const within = (ms: number): Promise => + Promise.race([exited.then(() => true), new Promise((r) => setTimeout(() => r(false), ms).unref())]); + if (!(await within(timeoutMs))) { + child.kill("SIGTERM"); + if (!(await within(2000))) child.kill("SIGKILL"); + } + await exited; + } + + // ------------------------------------------------------------ requests + + /** Send a JSON-RPC request and resolve with its result (AcpError on an error reply). `0` waits forever. */ + request(method: string, params: Json = {}, timeoutMs: number = this.options.requestTimeoutMs ?? 120_000): Promise { + return new Promise((resolve, reject) => { + let timer: NodeJS.Timeout | undefined; + let id: number; + try { + id = this.sendRequest(method, params, { + method, + resolve: (m) => { + if (timer) clearTimeout(timer); + try { + resolve(this.resultOf(method, m)); + } catch (e) { + reject(e); + } + }, + reject: (e) => { + if (timer) clearTimeout(timer); + reject(e); + }, + }); + } catch (e) { + reject(e); + return; + } + if (timeoutMs > 0) { + timer = setTimeout(() => { + this.pending.delete(id); + reject(new IncodeTimeout(`no answer to ${method} within ${timeoutMs}ms`, { stderr: this.stderr })); + }, timeoutMs); + } + }); + } + + /** Register `pending` and send the request; its callbacks run synchronously on the reader. */ + private sendRequest(method: string, params: Json, pending: Pending): number { + if (this.dead) throw this.dead; + if (!this.child) throw new IncodeError("the session is not started"); + const id = this.nextId++; + this.pending.set(id, pending); + this.send({ jsonrpc: "2.0", id, method, params }); + return id; + } + + private resultOf(method: string, message: Json): Json { + const error = message["error"]; + if (error !== undefined && error !== null) { + const e = asObject(error); + throw new AcpError(method, typeof e["code"] === "number" ? e["code"] : 0, String(e["message"] ?? ""), e["data"], { + stderr: this.stderr, + }); + } + return asObject(message["result"]); + } + + /** Send a JSON-RPC notification. */ + notify(method: string, params: Json = {}): void { + if (this.dead || !this.child) return; + this.send({ jsonrpc: "2.0", method, params }); + } + + private send(message: Json): void { + const child = this.child; + if (!child || child.stdin.destroyed || !child.stdin.writable) return; + child.stdin.write(JSON.stringify(message) + "\n"); + } + + // ------------------------------------------------------------ session methods + + /** + * Send `session/prompt`. Returns a `PromptStream` of events ending with a + * `PromptResult`. `prompt` is text or a list of ACP content blocks. + */ + prompt(prompt: string | Json[], options: PromptOptions = {}): PromptStream { + if (this.dead) throw this.dead; + if (!this.sessionId) throw new IncodeError("the session is not started"); + if (this.active) throw new IncodeError("a prompt is already running in this session"); + const blocks = typeof prompt === "string" ? [{ type: "text", text: prompt }] : prompt; + const stream = new PromptStream(this, options.timeoutMs); + this.active = stream; + const done = (item: PromptResult | Error): void => { + // On the reader, after every update that came before the reply. + if (this.active === stream) this.active = undefined; + stream.push(item); + }; + try { + this.sendRequest( + "session/prompt", + { sessionId: this.sessionId, prompt: blocks }, + { + method: "session/prompt", + resolve: (message) => { + try { + const result = this.resultOf("session/prompt", message); + done({ type: "prompt_result", stopReason: String(result["stopReason"] ?? ""), raw: result }); + } catch (e) { + done(e as Error); + } + }, + reject: done, + }, + ); + } catch (e) { + this.active = undefined; + throw e; + } + return stream; + } + + /** + * Send `session/cancel`; the running prompt ends with `stopReason: "cancelled"`. + * Any permission question still open is answered `cancelled`, as ACP asks. + */ + cancel(): void { + if (!this.sessionId || this.dead) return; + this.notify("session/cancel", { sessionId: this.sessionId }); + for (const [id, sid] of [...this.openPermissions]) { + if (sid === this.sessionId) this.answer(id, { outcome: { outcome: "cancelled" } }); + } + } + + /** `session/set_mode`: read-only, workspace-write or danger-full-access. */ + async setMode(modeId: string): Promise { + await this.request("session/set_mode", { sessionId: this.sessionId, modeId }); + this.currentMode = modeId; + } + + /** `session/set_config_option` (`agent` or `role`). Resolves with every option as it now stands. */ + async setConfigOption(configId: string, value: string): Promise { + const result = await this.request("session/set_config_option", { sessionId: this.sessionId, configId, value }); + this.configOptions = asArray(result["configOptions"]).map(asObject); + return this.configOptions; + } + + /** `session/list` for this workspace. */ + async listSessions(): Promise { + return asArray((await this.request("session/list", { cwd: this.workspace }))["sessions"]).map(asObject); + } + + // ------------------------------------------------------------ reader side + + private protocolError(line: string, error: Error): void { + this.protocolErrors.push(line.slice(0, 1000)); + if (this.protocolErrors.length > 100) this.protocolErrors.shift(); + try { + this.options.onProtocolError?.(line, error); + } catch (e) { + this.callbackErrors.push(e); + } + } + + private dispatch(line: string): void { + let message: unknown; + try { + message = JSON.parse(line); + } catch (e) { + this.protocolError(line, e as Error); + return; + } + if (!message || typeof message !== "object" || Array.isArray(message)) { + this.protocolError(line, new Error("not a JSON-RPC object")); + return; + } + const m = message as Json; + const method = m["method"]; + if (typeof method === "string") { + const params = asObject(m["params"]); + if (m["id"] !== undefined && m["id"] !== null) void this.serve(m["id"], method, params); + else if (method === "session/update") this.update(params); + return; + } + if ("id" in m && ("result" in m || "error" in m)) { + const id = m["id"] as number | string; + const pending = this.pending.get(id); + if (!pending) { + this.protocolError(line, new Error("a response to no request this client sent")); + return; + } + this.pending.delete(id); + pending.resolve(m); + return; + } + this.protocolError(line, new Error("neither a request, a notification nor a response")); + } + + private update(params: Json): void { + const update = params["update"]; + if (!update || typeof update !== "object") { + this.protocolError(JSON.stringify(params).slice(0, 1000), new Error("session/update without an update")); + return; + } + const event = parseUpdate(String(params["sessionId"] ?? ""), update as Json); + if (event.type === "mode_changed") this.currentMode = event.modeId; + else if (event.type === "config_options_changed") this.configOptions = event.configOptions; + if (this.active) { + this.active.push(event); + return; + } + this.idleEvents.push(event); + if (this.idleEvents.length > 1000) this.idleEvents.shift(); + try { + this.options.onUpdate?.(event); + } catch (e) { + this.callbackErrors.push(e); + } + } + + private failAll(error: IncodeError): void { + if (!this.dead) this.dead = error; + const pending = [...this.pending.values()]; + this.pending.clear(); + for (const p of pending) p.reject(error); + // A running prompt hears about it through its own pending request. + } + + // ------------------------------------------------------------ agent -> client requests + + private answer(id: unknown, result?: unknown, error?: Json): void { + if (this.answered.has(id)) return; + this.answered.add(id); + this.openPermissions.delete(id); + if (error) this.send({ jsonrpc: "2.0", id, error }); + else this.send({ jsonrpc: "2.0", id, result: result ?? {} }); + } + + private async serve(id: unknown, method: string, params: Json): Promise { + try { + if (method === "session/request_permission") { + await this.servePermission(id, params); + } else if (method === "fs/read_text_file" && this.readFile) { + const read = this.readFile; + await this.serveFs(id, async () => ({ content: await read(readRequest(params)) })); + } else if (method === "fs/write_text_file" && this.writeFile) { + const write = this.writeFile; + await this.serveFs(id, async () => { + await write(writeRequest(params)); + return {}; + }); + } else { + this.answer(id, undefined, { code: METHOD_NOT_FOUND, message: "Method not found", data: method }); + } + } catch (e) { + this.callbackErrors.push(e); + this.answer(id, undefined, { code: INTERNAL_ERROR, message: `client error: ${(e as Error).message}` }); + } + } + + private async servePermission(id: unknown, params: Json): Promise { + const request = new PermissionRequest(params); + this.openPermissions.set(id, request.sessionId); + let decision: PermissionDecision; + try { + decision = await this.onPermission(request); + } catch (e) { + this.callbackErrors.push(e); + decision = request.reject(); + } + if (decision === true) decision = request.allow(); + else if (decision === false) decision = request.reject(); + if (decision && typeof decision === "object") decision = decision.optionId; + let outcome: Json; + if (decision === null || decision === undefined) { + outcome = { outcome: "cancelled" }; + } else if (request.options.some((o) => o.optionId === decision)) { + outcome = { outcome: "selected", optionId: decision }; + } else { + this.callbackErrors.push(new Error(`onPermission returned ${JSON.stringify(decision)}, not one of the offered option ids`)); + const fallback = request.reject(); + outcome = fallback ? { outcome: "selected", optionId: fallback } : { outcome: "cancelled" }; + } + this.answer(id, { outcome }); + } + + private async serveFs(id: unknown, run: () => Promise): Promise { + try { + this.answer(id, await run()); + } catch (e) { + if (e instanceof FsError) return this.answer(id, undefined, { code: e.code, message: e.message }); + const err = e as NodeJS.ErrnoException; + if (err.code === "ENOENT") return this.answer(id, undefined, { code: RESOURCE_NOT_FOUND, message: `file not found: ${err.path ?? ""}` }); + if (e instanceof TypeError) return this.answer(id, undefined, { code: INVALID_PARAMS, message: `invalid params: ${e.message}` }); + this.answer(id, undefined, { code: INTERNAL_ERROR, message: err.message }); + } + } +} + +function asObject(v: unknown): Json { + return v && typeof v === "object" && !Array.isArray(v) ? (v as Json) : {}; +} + +function asArray(v: unknown): unknown[] { + return Array.isArray(v) ? v : []; +} + +function readRequest(params: Json): ReadFileRequest { + if (typeof params["path"] !== "string") throw new TypeError("path must be a string"); + return { + sessionId: String(params["sessionId"] ?? ""), + path: params["path"], + line: typeof params["line"] === "number" ? params["line"] : null, + limit: typeof params["limit"] === "number" ? params["limit"] : null, + }; +} + +function writeRequest(params: Json): WriteFileRequest { + if (typeof params["path"] !== "string") throw new TypeError("path must be a string"); + if (typeof params["content"] !== "string") throw new TypeError("content must be a string"); + return { sessionId: String(params["sessionId"] ?? ""), path: params["path"], content: params["content"] }; +} diff --git a/sdk/typescript/src/task.ts b/sdk/typescript/src/task.ts new file mode 100644 index 0000000..49acdda --- /dev/null +++ b/sdk/typescript/src/task.ts @@ -0,0 +1,199 @@ +/** One-shot runs: `incode -t "" --output-format json`. */ + +import { spawn } from "node:child_process"; + +import { IncodeError, IncodeTimeout, ProtocolError, TaskFailed } from "./errors.js"; + +export type IncodePath = string | readonly string[]; + +export interface TaskUsage { + inputTokens: number; + outputTokens: number; + cacheCreationTokens: number; + cacheReadTokens: number; +} + +/** The `result` object `incode -t ... --output-format json` prints (src/task_run.rs). */ +export interface TaskResult { + isError: boolean; + /** The agent's final answer, when the run succeeded. */ + result: string | null; + /** Why it did not. */ + error: string | null; + sessionId: string; + agent: string | null; + model: string | null; + agentSessionId: string | null; + stopReason: string | null; + servedBy: string[]; + usage: TaskUsage; + /** `null` for a model incode has no price for. */ + costUsd: number | null; + durationMs: number | null; + specGate: string | null; + exitCode: number | null; + stderr: string; + /** The whole object as printed. */ + raw: Record; +} + +export interface RunTaskOptions { + /** Workspace root (`-w`). Default: incode's current directory. */ + workspace?: string; + /** Model (`-m`). */ + model?: string; + /** + * Permission mode (`-p`). Note: incode 0.1.0 accepts `-p` with `-t` but does + * not apply it; the one-shot run uses the agent CLI's own handling. + */ + permissionMode?: string; + /** Kill the run after this many milliseconds and reject with IncodeTimeout. */ + timeoutMs?: number; + /** The incode executable, or a command prefix such as `["python3", "fake_incode.py"]`. Default `"incode"`. */ + incodePath?: IncodePath; + /** Extra environment variables, on top of `process.env`. */ + env?: Record; + /** Extra arguments, appended last (for example `["--spec-gate=off"]`). */ + extraArgs?: readonly string[]; + /** Abort the run (the process is killed). */ + signal?: AbortSignal; +} + +function asString(v: unknown): string | null { + return typeof v === "string" ? v : null; +} + +function asNumber(v: unknown): number | null { + return typeof v === "number" && Number.isFinite(v) ? v : null; +} + +/** Parse one result object. */ +export function parseTaskResult(data: Record, exitCode: number | null = 0, stderr = ""): TaskResult { + const usage = (data["usage"] && typeof data["usage"] === "object" ? data["usage"] : {}) as Record; + return { + isError: data["is_error"] === true, + result: asString(data["result"]), + error: asString(data["error"]), + sessionId: asString(data["session_id"]) ?? "", + agent: asString(data["agent"]), + model: asString(data["model"]), + agentSessionId: asString(data["agent_session_id"]), + stopReason: asString(data["stop_reason"]), + servedBy: Array.isArray(data["served_by"]) ? data["served_by"].filter((x): x is string => typeof x === "string") : [], + usage: { + inputTokens: asNumber(usage["input_tokens"]) ?? 0, + outputTokens: asNumber(usage["output_tokens"]) ?? 0, + cacheCreationTokens: asNumber(usage["cache_creation_tokens"]) ?? 0, + cacheReadTokens: asNumber(usage["cache_read_tokens"]) ?? 0, + }, + costUsd: asNumber(data["cost_usd"]), + durationMs: asNumber(data["duration_ms"]), + specGate: asString(data["spec_gate"]), + exitCode, + stderr, + raw: data, + }; +} + +/** The command line `runTask` runs, as `[command, ...args]`. */ +export function buildTaskArgv(task: string, options: RunTaskOptions = {}): string[] { + const argv = commandOf(options.incodePath); + argv.push("-t", task, "--output-format", "json"); + if (options.workspace !== undefined) argv.push("-w", options.workspace); + if (options.model) argv.push("-m", options.model); + if (options.permissionMode) argv.push("-p", options.permissionMode); + argv.push(...(options.extraArgs ?? [])); + return argv; +} + +export function commandOf(incodePath: IncodePath | undefined): string[] { + if (incodePath === undefined) return ["incode"]; + return typeof incodePath === "string" ? [incodePath] : [...incodePath]; +} + +function lastJsonObject(stdout: string): Record | null { + const lines = stdout.split(/\r?\n/).filter((l) => l.trim() !== ""); + const last = lines[lines.length - 1]; + if (last === undefined) return null; + try { + const value: unknown = JSON.parse(last); + return value && typeof value === "object" && !Array.isArray(value) ? (value as Record) : null; + } catch { + return null; + } +} + +/** + * Run one instruction with `incode -t` and resolve with its parsed result. + * + * Rejects with `TaskFailed` when incode reports `is_error: true` (the parsed + * result is on `.result`), `IncodeTimeout` after `timeoutMs`, and `IncodeError` + * when incode cannot start or exits without a result object. + */ +export function runTask(task: string, options: RunTaskOptions = {}): Promise { + const [command, ...args] = buildTaskArgv(task, options); + return new Promise((resolve, reject) => { + let stdout = ""; + let stderr = ""; + let settled = false; + let timedOut = false; + let aborted = false; + const child = spawn(command as string, args, { + stdio: ["ignore", "pipe", "pipe"], + env: options.env ? { ...process.env, ...options.env } : process.env, + }); + child.stdout.setEncoding("utf8"); + child.stderr.setEncoding("utf8"); + child.stdout.on("data", (d: string) => (stdout += d)); + child.stderr.on("data", (d: string) => (stderr += d)); + + const timer = + options.timeoutMs !== undefined + ? setTimeout(() => { + timedOut = true; + child.kill("SIGKILL"); + }, options.timeoutMs) + : undefined; + const onAbort = (): void => { + aborted = true; + child.kill("SIGKILL"); + }; + options.signal?.addEventListener("abort", onAbort, { once: true }); + + const finish = (fn: () => void): void => { + if (settled) return; + settled = true; + if (timer) clearTimeout(timer); + options.signal?.removeEventListener("abort", onAbort); + fn(); + }; + + child.on("error", (err: NodeJS.ErrnoException) => { + finish(() => reject(new IncodeError(`could not start incode: ${err.message} (${command})`, { stderr }))); + }); + child.on("close", (code) => { + finish(() => { + if (timedOut) return reject(new IncodeTimeout(`incode -t did not finish within ${options.timeoutMs}ms`, { stderr })); + if (aborted) return reject(new IncodeError("incode -t was aborted", { stderr })); + const data = lastJsonObject(stdout); + if (data === null) { + if (code !== 0) return reject(new IncodeError("incode -t failed before producing a result", { stderr, exitCode: code })); + return reject( + new ProtocolError(`incode -t printed no JSON result object (stdout: ${JSON.stringify(stdout.slice(-500))})`, { + stderr, + exitCode: code, + }), + ); + } + const result = parseTaskResult(data, code, stderr); + if (result.isError || code !== 0) { + return reject( + new TaskFailed(`incode -t reported an error: ${result.error ?? "unknown error"}`, result, { stderr, exitCode: code }), + ); + } + resolve(result); + }); + }); + if (options.signal?.aborted) onAbort(); + }); +} diff --git a/sdk/typescript/test/live.test.ts b/sdk/typescript/test/live.test.ts new file mode 100644 index 0000000..eb2614f --- /dev/null +++ b/sdk/typescript/test/live.test.ts @@ -0,0 +1,26 @@ +// Against the real binary: set INCODE_BIN=/path/to/incode to run; skipped otherwise. +// Only `initialize` and `session/new` — no turn runs, so no agent CLI is needed. +import assert from "node:assert/strict"; +import { it } from "node:test"; + +import { Session } from "../src/index.js"; +import { tempDirs } from "./support.js"; + +const INCODE_BIN = process.env["INCODE_BIN"]; + +it("live: initialize + session/new against INCODE_BIN", { skip: INCODE_BIN ? false : "set INCODE_BIN to run" }, async () => { + const dirs = tempDirs(); + const session = new Session({ workspace: dirs.ws, incodePath: INCODE_BIN, requestTimeoutMs: 60_000 }); + try { + await session.start(); + assert.equal(session.protocolVersion, 1); + assert.equal(session.agentInfo["name"], "incode"); + assert.ok(session.sessionId); + assert.ok(session.availableModes.some((m) => m["id"] === "workspace-write")); + assert.ok(session.currentMode); + assert.ok(session.configOptions.some((o) => o["id"] === "agent")); + } finally { + await session.close(); + dirs.cleanup(); + } +}); diff --git a/sdk/typescript/test/session.test.ts b/sdk/typescript/test/session.test.ts new file mode 100644 index 0000000..b4a0629 --- /dev/null +++ b/sdk/typescript/test/session.test.ts @@ -0,0 +1,361 @@ +import assert from "node:assert/strict"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import { afterEach, beforeEach, describe, it } from "node:test"; + +import { + AcpError, + AgentCrashed, + IncodeError, + IncodeTimeout, + Session, + type PermissionRequest, + type PromptResult, + type PromptStream, + type SessionEvent, + type SessionOptions, + type WriteFileRequest, +} from "../src/index.js"; +import { FAKE, tempDirs, waitFor, type TempDirs } from "./support.js"; + +async function all(stream: PromptStream): Promise<{ events: SessionEvent[]; result: PromptResult }> { + const seen: Array = []; + for await (const e of stream) seen.push(e); + const last = seen.pop(); + assert.ok(last && last.type === "prompt_result", JSON.stringify(last)); + return { events: seen as SessionEvent[], result: last }; +} + +let dirs: TempDirs; +const open: Session[] = []; + +function session(options: SessionOptions = {}): Session { + const s = new Session({ workspace: dirs.ws, incodePath: FAKE, requestTimeoutMs: 10_000, ...options }); + open.push(s); + return s; +} + +/** Started, and past the `available_commands_update` incode sends after answering `session/new`. */ +async function started(options: SessionOptions = {}): Promise { + const s = session(options); + await s.start(); + if (!options.loadSessionId) await waitFor(() => s.idleEvents.some((e) => e.type === "available_commands")); + return s; +} + +beforeEach(() => { + dirs = tempDirs(); +}); +afterEach(async () => { + await Promise.all(open.splice(0).map((s) => s.close())); + dirs.cleanup(); +}); + +describe("start", () => { + it("opens a session and passes the flags", async () => { + const argvFile = path.join(dirs.root, "argv.json"); + const s = await started({ model: "opus", permissionMode: "read-only", env: { FAKE_INCODE_ARGV: argvFile } }); + assert.equal(s.sessionId, "fake-session-1"); + assert.equal(s.protocolVersion, 1); + assert.equal(s.agentInfo["name"], "incode"); + assert.equal(s.agentCapabilities["loadSession"], true); + assert.equal(s.currentMode, "read-only"); + assert.deepEqual( + s.availableModes.map((m) => m["id"]), + ["read-only", "workspace-write", "danger-full-access"], + ); + assert.deepEqual( + s.configOptions.map((o) => o["id"]), + ["agent", "role"], + ); + await waitFor(() => s.idleEvents.length > 0); + const first = s.idleEvents[0]; + assert.equal(first?.type, "available_commands"); + assert.deepEqual(JSON.parse(fs.readFileSync(argvFile, "utf8")), ["--acp", "-m", "opus", "-p", "read-only"]); + await s.close(); + assert.equal(s.exitCode, 0); + }); + + it("onUpdate hears idle updates", async () => { + const heard: SessionEvent[] = []; + await started({ onUpdate: (e) => heard.push(e) }); + await waitFor(() => heard.length > 0); + assert.equal(heard[0]?.type, "available_commands"); + }); + + it("a refused start rejects with stderr", async () => { + await assert.rejects(session({ permissionMode: "prompt" }).start(), (e: unknown) => { + assert.ok(e instanceof AgentCrashed); + assert.equal(e.exitCode, 1); + assert.match(e.stderr, /--acp/); + return true; + }); + }); + + it("a missing workspace is refused by the agent", async () => { + await assert.rejects(session({ workspace: path.join(dirs.root, "missing") }).start(), (e: unknown) => { + assert.ok(e instanceof AcpError); + assert.equal(e.code, -32602); + assert.equal(e.method, "session/new"); + return true; + }); + }); + + it("a missing binary rejects", async () => { + await assert.rejects(session({ incodePath: path.join(dirs.root, "nope") }).start(), /could not start incode/); + }); + + it("loads a kept session and replays its history", async () => { + const s = await started({ loadSessionId: "kept-session" }); + assert.equal(s.sessionId, "kept-session"); + assert.deepEqual( + s.idleEvents.slice(0, 2).map((e) => e.type), + ["user_message_chunk", "message_chunk"], + ); + await assert.rejects(session({ loadSessionId: "no-such" }).start(), AcpError); + }); +}); + +describe("prompt", () => { + it("streams typed events then the result", async () => { + const s = await started(); + const stream = s.prompt("hello"); + const { events, result } = await all(stream); + assert.equal(result.stopReason, "end_turn"); + assert.equal(stream.result, result); + assert.deepEqual( + events.map((e) => e.type), + ["thought_chunk", "message_chunk", "tool_call", "tool_call_update", "plan", "usage", "unknown", "message_chunk"], + ); + assert.equal(stream.text, "Hello (mode workspace-write, agent claude-code)\n"); + const [, , call, done, plan, usage, unknown] = events; + assert.ok(call?.type === "tool_call"); + assert.deepEqual([call.toolCallId, call.kind, call.status, call.title], ["t1", "read", "in_progress", "Read a.txt"]); + assert.deepEqual(call.rawInput, { path: "a.txt" }); + assert.ok(done?.type === "tool_call_update"); + assert.deepEqual([done.toolCallId, done.status, done.rawOutput], ["t1", "completed", "contents of a"]); + assert.ok(plan?.type === "plan"); + assert.deepEqual(plan.entries[0], { content: "Read a.txt", priority: "high", status: "completed" }); + assert.ok(usage?.type === "usage"); + assert.deepEqual([usage.used, usage.size], [38833, 1000000]); + assert.ok(unknown?.type === "unknown"); + assert.equal(unknown.kind, "some_future_update"); + assert.equal((await s.prompt("hello again").wait()).stopReason, "end_turn"); + }); + + it("accepts content blocks", async () => { + const s = await started(); + assert.equal((await s.prompt([{ type: "text", text: "hello" }]).wait()).stopReason, "end_turn"); + }); + + it("allows one prompt at a time", async () => { + const s = await started(); + const stream = s.prompt("wait"); + assert.throws(() => s.prompt("hello"), IncodeError); + s.cancel(); + assert.equal((await stream.wait()).stopReason, "cancelled"); + }); + + it("sets the mode and a config option", async () => { + const s = await started(); + await s.setMode("read-only"); + assert.equal(s.currentMode, "read-only"); + const options = await s.setConfigOption("agent", "codex"); + assert.equal(options.find((o) => o["id"] === "agent")?.["currentValue"], "codex"); + const stream = s.prompt("hello"); + await stream.wait(); + assert.match(stream.text, /mode read-only, agent codex/); + assert.ok(s.idleEvents.some((e) => e.type === "mode_changed" && e.modeId === "read-only")); + await assert.rejects(s.setMode("yolo"), (e: unknown) => e instanceof AcpError && e.code === -32602); + await assert.rejects(s.setConfigOption("agent", "not-installed"), AcpError); + }); +}); + +describe("permission", () => { + it("rejects by default", async () => { + const s = await started(); + const stream = s.prompt("permission"); + const { events, result } = await all(stream); + assert.equal(result.stopReason, "end_turn"); + assert.match(stream.text, /permission: reject/); + const update = events.find((e) => e.type === "tool_call_update"); + assert.ok(update?.type === "tool_call_update"); + assert.equal(update.status, "failed"); + }); + + it("round-trips an allow", async () => { + const asked: PermissionRequest[] = []; + const s = await started({ + onPermission: async (request) => { + asked.push(request); + await new Promise((r) => setTimeout(r, 10)); + return request.allow(); + }, + }); + const stream = s.prompt("permission"); + await stream.wait(); + assert.match(stream.text, /permission: allow/); + const request = asked[0]; + assert.ok(request); + assert.equal(request.sessionId, "fake-session-1"); + assert.equal(request.toolCallId, "g1"); + assert.match(request.title, /writing here needs the owner/); + assert.deepEqual( + request.options.map((o) => o.kind), + ["allow_once", "reject_once"], + ); + }); + + for (const [decision, said] of [ + [true, /permission: allow/], + [false, /permission: reject/], + [null, /permission: cancelled/], + ["bogus", /permission: reject/], + ] as const) { + it(`answers ${JSON.stringify(decision)}`, async () => { + const s = await started({ onPermission: () => decision }); + const stream = s.prompt("permission"); + await stream.wait(); + assert.match(stream.text, said); + }); + } + + it("a throwing callback rejects", async () => { + const s = await started({ + onPermission: () => { + throw new Error("callback bug"); + }, + }); + const stream = s.prompt("permission"); + await stream.wait(); + assert.match(stream.text, /permission: reject/); + assert.match(String(s.callbackErrors[0]), /callback bug/); + }); + + it("cancel answers an open question cancelled", async () => { + let release: () => void = () => {}; + let asked = false; + const s = await started({ + onPermission: (request) => + new Promise((resolve) => { + asked = true; + release = () => resolve(request.allow()); + }), + }); + const stream = s.prompt("permission-wait"); + await waitFor(() => asked); + s.cancel(); + const result = await stream.wait(); + release(); + assert.equal(result.stopReason, "cancelled"); + assert.match(stream.text, /permission answer after cancel: cancelled/); + }); +}); + +describe("fs", () => { + async function fsPrompt(s: Session, readPath: string, writePath: string): Promise { + const stream = s.prompt(`fs ${readPath} ${writePath}`); + assert.equal((await stream.wait()).stopReason, "end_turn"); + return stream.text; + } + + it("reads and writes inside the workspace", async () => { + fs.writeFileSync(path.join(dirs.ws, "in.txt"), "hello from the workspace"); + const s = await started(); + const text = await fsPrompt(s, path.join(dirs.ws, "in.txt"), path.join(dirs.ws, "sub", "out.txt")); + assert.match(text, /read: hello from the workspace/); + assert.match(text, /write: ok/); + assert.equal(fs.readFileSync(path.join(dirs.ws, "sub", "out.txt"), "utf8"), "written by fake\n"); + }); + + it("refuses outside the workspace, through .. and symlinks", async () => { + const secret = path.join(dirs.root, "secret.txt"); + fs.writeFileSync(secret, "do not read"); + const outside = path.join(dirs.root, "out.txt"); + fs.symlinkSync(dirs.root, path.join(dirs.ws, "escape")); + // Raw strings: `..` must reach incode's client unnormalised. + const cases: Array<[string, string]> = [ + [secret, outside], + [`${dirs.ws}/../secret.txt`, `${dirs.ws}/../out.txt`], + [`${dirs.ws}/escape/secret.txt`, `${dirs.ws}/escape/out.txt`], + [`${dirs.ws}/escape/ws/../secret.txt`, `${dirs.ws}/escape/ws/../out.txt`], + ]; + const s = await started(); + for (const [readPath, writePath] of cases) { + const text = await fsPrompt(s, readPath, writePath); + assert.match(text, /read error: -32602 access denied/, readPath); + assert.match(text, /write error: -32602 access denied/, writePath); + assert.doesNotMatch(text, /do not read/); + } + assert.equal(fs.existsSync(outside), false); + }); + + it("a missing file is resource-not-found", async () => { + const s = await started(); + const text = await fsPrompt(s, path.join(dirs.ws, "nope.txt"), path.join(dirs.ws, "ok.txt")); + assert.match(text, /read error: -32002/); + }); + + it("disabled and custom handlers", async () => { + const writes: WriteFileRequest[] = []; + const s = await started({ onReadFile: false, onWriteFile: (r) => void writes.push(r) }); + const text = await fsPrompt(s, "/anything", "/virtual/out.txt"); + assert.match(text, /read error: -32601/); + assert.match(text, /write: ok/); + assert.equal(writes[0]?.path, "/virtual/out.txt"); + assert.equal(writes[0]?.content, "written by fake\n"); + }); +}); + +describe("failures", () => { + it("cancel ends the prompt cancelled", async () => { + const s = await started(); + const stream = s.prompt("wait"); + const first = await stream.next(); + assert.ok(!first.done && first.value.type === "message_chunk"); + assert.equal(first.value.text, "working"); + const began = Date.now(); + stream.cancel(); + assert.equal((await stream.wait()).stopReason, "cancelled"); + assert.ok(Date.now() - began < 5000); + assert.equal((await s.prompt("hello").wait()).stopReason, "end_turn"); + }); + + it("an agent crash mid-prompt rejects the stream", async () => { + const s = await started(); + const stream = s.prompt("crash"); + const first = await stream.next(); + assert.ok(!first.done && first.value.type === "message_chunk" && first.value.text === "about to crash"); + await assert.rejects(stream.next(), (e: unknown) => { + assert.ok(e instanceof AgentCrashed); + assert.equal(e.exitCode, 3); + assert.match(e.stderr, /crashed mid-prompt/); + return true; + }); + assert.throws(() => s.prompt("hello"), AgentCrashed); + await assert.rejects(s.setMode("read-only"), AgentCrashed); + }); + + it("skips malformed lines", async () => { + const heard: string[] = []; + const s = await started({ onProtocolError: (line) => heard.push(line) }); + const stream = s.prompt("malformed"); + assert.equal((await stream.wait()).stopReason, "end_turn"); + assert.equal(stream.text, "still alive"); + assert.equal((await s.prompt("hello").wait()).stopReason, "end_turn"); + assert.equal(heard.length, 4, JSON.stringify(heard)); + assert.ok(heard.includes("this is not json")); + }); + + it("answers an unknown agent request with method-not-found", async () => { + const s = await started(); + const stream = s.prompt("unknown-request"); + await stream.wait(); + assert.match(stream.text, /terminal\/create -> -32601/); + }); + + it("times a prompt out", async () => { + const s = await started(); + await assert.rejects(s.prompt("wait", { timeoutMs: 500 }).wait(), IncodeTimeout); + }); +}); diff --git a/sdk/typescript/test/support.ts b/sdk/typescript/test/support.ts new file mode 100644 index 0000000..1e3ea7b --- /dev/null +++ b/sdk/typescript/test/support.ts @@ -0,0 +1,31 @@ +import * as fs from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; + +// Compiled to dist-test/test/support.js; the fake lives in sdk/testing/. +export const FAKE_INCODE = fileURLToPath(new URL("../../../testing/fake_incode.py", import.meta.url)); +/** Run through python3 so the tests do not depend on the script's executable bit. */ +export const FAKE: string[] = [process.env["PYTHON"] ?? "python3", FAKE_INCODE]; + +export interface TempDirs { + root: string; + ws: string; + cleanup(): void; +} + +/** A real temp root with a `ws` workspace inside it. */ +export function tempDirs(): TempDirs { + const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "incode-sdk-"))); + const ws = path.join(root, "ws"); + fs.mkdirSync(ws); + return { root, ws, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) }; +} + +export async function waitFor(check: () => boolean, ms = 5000): Promise { + const deadline = Date.now() + ms; + while (!check()) { + if (Date.now() > deadline) throw new Error("timed out waiting"); + await new Promise((r) => setTimeout(r, 20)); + } +} diff --git a/sdk/typescript/test/task.test.ts b/sdk/typescript/test/task.test.ts new file mode 100644 index 0000000..40cbd8a --- /dev/null +++ b/sdk/typescript/test/task.test.ts @@ -0,0 +1,117 @@ +import assert from "node:assert/strict"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import { afterEach, beforeEach, describe, it } from "node:test"; + +import { buildTaskArgv, IncodeError, IncodeTimeout, parseTaskResult, ProtocolError, runTask, TaskFailed } from "../src/index.js"; +import { FAKE, tempDirs, type TempDirs } from "./support.js"; + +describe("runTask", () => { + let dirs: TempDirs; + beforeEach(() => { + dirs = tempDirs(); + }); + afterEach(() => dirs.cleanup()); + + it("parses a successful result and passes the flags", async () => { + const argvFile = path.join(dirs.root, "argv.json"); + const result = await runTask("add a test", { + workspace: dirs.ws, + model: "sonnet", + permissionMode: "read-only", + incodePath: FAKE, + env: { FAKE_INCODE_ARGV: argvFile }, + }); + assert.equal(result.isError, false); + assert.equal(result.result, "done: add a test"); + assert.equal(result.error, null); + assert.equal(result.model, "sonnet"); + assert.equal(result.agent, "claude-code"); + assert.equal(result.stopReason, "end_turn"); + assert.deepEqual(result.servedBy, ["claude-code"]); + assert.deepEqual(result.usage, { inputTokens: 120, outputTokens: 45, cacheCreationTokens: 7, cacheReadTokens: 300 }); + assert.equal(result.costUsd, 0.0123); + assert.equal(result.durationMs, 42); + assert.equal(result.specGate, "on"); + assert.equal(result.exitCode, 0); + assert.match(result.stderr, /fake: running/); + assert.deepEqual(JSON.parse(fs.readFileSync(argvFile, "utf8")), [ + "-t", + "add a test", + "--output-format", + "json", + "-w", + dirs.ws, + "-m", + "sonnet", + "-p", + "read-only", + ]); + }); + + it("rejects with TaskFailed carrying the result and stderr", async () => { + await assert.rejects(runTask("fail please", { workspace: dirs.ws, incodePath: FAKE }), (e: unknown) => { + assert.ok(e instanceof TaskFailed); + assert.equal(e.exitCode, 1); + assert.equal(e.result.isError, true); + assert.equal(e.result.error, "the agent failed: fake failure"); + assert.equal(e.result.costUsd, null); + assert.match(e.stderr, /fake: running/); + assert.match(e.message, /fake failure/); + return true; + }); + }); + + it("rejects with IncodeError when there is no result", async () => { + await assert.rejects(runTask("crash", { workspace: dirs.ws, incodePath: FAKE }), (e: unknown) => { + assert.ok(e instanceof IncodeError); + assert.ok(!(e instanceof TaskFailed)); + assert.equal(e.exitCode, 2); + assert.match(e.stderr, /could not start/); + return true; + }); + }); + + it("reports a bad workspace", async () => { + await assert.rejects(runTask("x", { workspace: path.join(dirs.ws, "missing"), incodePath: FAKE }), (e: unknown) => { + assert.ok(e instanceof IncodeError); + assert.match(e.stderr, /not a directory/); + return true; + }); + }); + + it("rejects non-JSON stdout as a ProtocolError", async () => { + await assert.rejects(runTask("garbage", { workspace: dirs.ws, incodePath: FAKE }), ProtocolError); + }); + + it("times out", async () => { + await assert.rejects(runTask("sleep", { workspace: dirs.ws, incodePath: FAKE, timeoutMs: 1000 }), IncodeTimeout); + }); + + it("aborts", async () => { + const controller = new AbortController(); + const running = runTask("sleep", { workspace: dirs.ws, incodePath: FAKE, signal: controller.signal }); + setTimeout(() => controller.abort(), 200); + await assert.rejects(running, /aborted/); + }); + + it("reports a missing binary", async () => { + await assert.rejects(runTask("x", { incodePath: path.join(dirs.root, "no-such-incode") }), /could not start incode/); + }); + + it("parses the real binary's failure shape", () => { + const line = + '{"type":"result","is_error":true,"session_id":"","agent":null,"model":null,"agent_session_id":null,' + + '"stop_reason":null,"served_by":[],"usage":{"input_tokens":0,"output_tokens":0,"cache_creation_tokens":0,' + + '"cache_read_tokens":0},"duration_ms":0,"spec_gate":"on","error":"nothing to do: the instruction is empty"}'; + const r = parseTaskResult(JSON.parse(line) as Record, 1); + assert.equal(r.isError, true); + assert.equal(r.costUsd, null); + assert.equal(r.result, null); + assert.equal(r.error, "nothing to do: the instruction is empty"); + }); + + it("builds the argv", () => { + assert.deepEqual(buildTaskArgv("hi"), ["incode", "-t", "hi", "--output-format", "json"]); + }); +}); diff --git a/sdk/typescript/tsconfig.json b/sdk/typescript/tsconfig.json new file mode 100644 index 0000000..4c9eeaf --- /dev/null +++ b/sdk/typescript/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022"], + "module": "NodeNext", + "moduleResolution": "NodeNext", + "types": ["node"], + "strict": true, + "noImplicitOverride": true, + "noUncheckedIndexedAccess": true, + "exactOptionalPropertyTypes": false, + "declaration": true, + "sourceMap": true, + "outDir": "dist", + "rootDir": "src", + "skipLibCheck": true + }, + "include": ["src"] +} diff --git a/sdk/typescript/tsconfig.test.json b/sdk/typescript/tsconfig.test.json new file mode 100644 index 0000000..a430e78 --- /dev/null +++ b/sdk/typescript/tsconfig.test.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "dist-test", + "rootDir": ".", + "declaration": false + }, + "include": ["src", "test"] +} From edfe2f8de37e3b29933035be520e14fe04d21079 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:46:25 +0000 Subject: [PATCH 4/9] -t honours -p; a -t run that fails to start still answers in JSON Found while building the SDKs: - `-p` with `-t` was parsed and then dropped. It now rides the task and is applied to every candidate agent (the agent's own mode on a CLI route, the toolbox's on the API route, and the sandbox policy). Unset, the run keeps its default. `incode review` uses it: a review is now read-only. - `-t --output-format json|stream-json` that failed before the run began (a bad -w, -p or --spec-gate) printed nothing on stdout. It now prints the one result object a script reads: {"type":"result","is_error":true, "error":...}. - run_task_as takes its optional parts as RunOptions. - The ACP module docs said text-only prompts and stdio-only client MCP servers; incode advertises images and HTTP servers too. - CI runs the Python and TypeScript SDK and VS Code extension suites. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- .github/workflows/ci.yml | 17 +++++++ README.md | 3 +- TESTING.md | 2 +- scripts/test-all.sh | 2 +- sdk/README.md | 9 ++-- src/acp_agent/mod.rs | 6 +-- src/main.rs | 97 ++++++++++++++++++++++++++++++++++++++-- src/review.rs | 14 ++++-- src/task_run.rs | 71 ++++++++++++++++++++++++----- 9 files changed, 191 insertions(+), 30 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 48070b3..9a3e4f3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,6 +27,23 @@ jobs: components: rustfmt - run: cargo fmt --check + # The SDKs and the VS Code extension, against their fake incode/agent. + sdk-and-editor: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: python3 -m unittest discover sdk/python/tests + - run: npm ci && npm test + working-directory: sdk/typescript + - run: npm ci && npm run compile && npm test + working-directory: editors/vscode + test: name: test (${{ matrix.os }}) strategy: diff --git a/README.md b/README.md index 93a83d0..cc35517 100644 --- a/README.md +++ b/README.md @@ -538,7 +538,8 @@ Prices for `/cost`, the status line and `-t --output-format json` (`cost_usd`) a `incode review` (and `/review` in a session) hands the model the change and one job: report correctness bugs first, then security problems, then -simplifications, each cited as `path:line` — or say "No issues found." +simplifications, each cited as `path:line` — or say "No issues found." It +runs read-only: the agent may read the code and run nothing that writes. ```sh incode review # the branch since it forked from origin's default branch, plus uncommitted and untracked work diff --git a/TESTING.md b/TESTING.md index 7397494..74620b7 100644 --- a/TESTING.md +++ b/TESTING.md @@ -32,7 +32,7 @@ an email (`git config --global user.name ...`, `user.email ...`). | rust | `cargo fmt --all -- --check` · `cargo clippy --all-targets -- -D warnings` · `cargo test --lib` · `cargo test --bins` | incode itself: about 2,100 library and 50 binary tests | | rust | `cargo test --test sbx_engine` | Real shell commands run under `sandbox_engine = "sbx"`: a write outside the workspace refused (with an unconfined control), a planted git hook undone, `GIT_DIR` stripped. Linux; says it skipped elsewhere | | sbx | `cargo clippy -p incord-sandbox --all-targets -- -D warnings` · `cargo test -p incord-sandbox` | The standalone sandbox: escape tests per OS, the MCP server, `.git` protection, WSL path translation | -| python | `python3 -m unittest discover -s sdk/python/tests -t sdk/python` | The Python SDK, against a fake incode | +| python | `python3 -m unittest discover sdk/python/tests` | The Python SDK, against a fake incode | | ts | `cd sdk/typescript && npm install && npm test` | The TypeScript SDK, against the same fake | | vscode | `cd editors/vscode && npm install && npm run compile && npm test` | The VS Code extension's ACP client, against a fake agent | diff --git a/scripts/test-all.sh b/scripts/test-all.sh index c0072ea..f52f53f 100755 --- a/scripts/test-all.sh +++ b/scripts/test-all.sh @@ -60,7 +60,7 @@ fi if wants python; then if have python3 && [ -d sdk/python ]; then - step python python3 -m unittest discover -s sdk/python/tests -t sdk/python + step python python3 -m unittest discover sdk/python/tests else skipped="$skipped python" fi diff --git a/sdk/README.md b/sdk/README.md index adf72ef..e01572a 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -58,10 +58,11 @@ an SDK at it with `incode_path=[sys.executable, ".../fake_incode.py"]` / ## Things to know about incode itself -- `-p` is accepted with `-t` but not applied (the one-shot run ignores it). -- An error found before the run starts (bad `-w`, bad `-p`) prints nothing on - stdout even with `--output-format json`: only stderr and exit code 1. The SDKs - raise `IncodeError` with that stderr. +- `-p` with `-t` sets what every candidate agent may do (`read-only`, `workspace-write`, ...). +- An error found before the run starts (bad `-w`, bad `-p`) still prints one + result object with `--output-format json` (`{"type": "result", "is_error": + true, "error": ...}`) and exits 1; the SDKs raise `TaskFailed` with it, or + `IncodeError` with stderr from an older incode that printed nothing. - `session/update` notifications are per session, not per prompt. incode sends `available_commands_update` just *after* answering `session/new`, so a prompt sent at once can see it in its stream. diff --git a/src/acp_agent/mod.rs b/src/acp_agent/mod.rs index 178c817..9d33ac8 100644 --- a/src/acp_agent/mod.rs +++ b/src/acp_agent/mod.rs @@ -13,9 +13,9 @@ //! # Methods answered //! //! - `initialize` — protocol version 1, and the capabilities incode really -//! has: text and embedded-context prompts, loading and listing sessions, -//! and stdio MCP servers from the client (no HTTP or SSE ones). No -//! authentication methods. +//! has: text, image and embedded-context prompts, loading and listing +//! sessions, and stdio and HTTP MCP servers from the client (no SSE ones). +//! No authentication methods. //! - `authenticate` — refused as invalid params: the method id must be one //! `initialize` advertised, and none is. The subscription CLIs hold their //! own logins. diff --git a/src/main.rs b/src/main.rs index 53825a8..f1771b5 100644 --- a/src/main.rs +++ b/src/main.rs @@ -144,7 +144,13 @@ fn main() -> anyhow::Result<()> { // errors) but no subscriber is installed, so they currently go nowhere. // Installing one needs a new dependency, which is a decision to take // deliberately rather than as a side effect of adding this entry point. - let parsed = parse_args(std::env::args().skip(1))?; + let parsed = match parse_args(std::env::args().skip(1)) { + Ok(parsed) => parsed, + Err(e) => { + json_failure(std::env::args().skip(1), &e.to_string()); + return Err(e); + } + }; // Before anything reads `~/.incode/` or a project's `.incode/`: state left // under the old names (`~/.incord-code/`, `.incord/`) is carried over. // stderr, never stdout: several modes speak a protocol on stdout. @@ -185,6 +191,7 @@ fn main() -> anyhow::Result<()> { model, format, spec_gate, + permission_mode, } => { let spec_gate = incord_code::spec::SpecGate::resolve( spec_gate, @@ -192,7 +199,10 @@ fn main() -> anyhow::Result<()> { .ok() .as_deref(), ) - .map_err(|e| anyhow::anyhow!(e))?; + .map_err(|e| { + json_failure(std::env::args().skip(1), &e); + anyhow::anyhow!(e) + })?; // `-t "/name args"` runs the operator's custom command, held to // its `allowed-tools`. let task = incord_code::custom_commands::expand_task(&workspace, instruction, model); @@ -201,10 +211,13 @@ fn main() -> anyhow::Result<()> { &workspace, &task.instruction, task.model.as_deref(), - &task.allowed_tools, format, spec_gate, - &created_outside, + &incord_code::task_run::RunOptions { + command_tools: &task.allowed_tools, + permission_mode, + created: &created_outside, + }, ) })? .map(|_| ()) @@ -421,6 +434,35 @@ fn on_a_runtime(work: impl FnOnce() -> T) -> anyhow::Result { } /// What the arguments asked for. +/// A `-t --output-format json|stream-json` run that fails before it starts +/// still ends with the one result object a script reads, on stdout: without +/// it the script sees no JSON at all, only an exit code and stderr. The +/// message is the error's first paragraph (the usage text after it is for a +/// person). +fn json_failure(args: impl Iterator, error: &str) { + if let Some(line) = json_failure_line(args, error) { + println!("{line}"); + } +} + +fn json_failure_line(args: impl Iterator, error: &str) -> Option { + let args: Vec = args.collect(); + let is_task = args.iter().any(|a| a == "-t" || a == "--task"); + let json = args.iter().enumerate().any(|(i, a)| { + let value = match a.strip_prefix("--output-format=") { + Some(v) => Some(v), + None if a == "--output-format" => args.get(i + 1).map(String::as_str), + None => None, + }; + matches!(value, Some("json" | "stream-json")) + }); + if !(is_task && json) { + return None; + } + let message = error.split("\n\n").next().unwrap_or(error).trim(); + Some(serde_json::json!({"type": "result", "is_error": true, "error": message}).to_string()) +} + #[derive(Debug)] enum Parsed { Run(Box), @@ -434,6 +476,10 @@ enum Parsed { /// `--spec-gate`, when given. The environment is read in `main`, not /// here, so parsing stays a function of the arguments alone. spec_gate: Option, + /// `-p`, when given: what every candidate agent may do. Unset, the run + /// keeps its default (workspace-write, or `INCODE_PERMISSION_MODE` on + /// a CLI agent). + permission_mode: Option, }, Exit(String), /// Serve what the run is doing to a local interface, and nothing else. @@ -595,6 +641,8 @@ fn parse_args(args: impl Iterator) -> anyhow::Result { let mut task: Option = None; let mut output_format: Option = None; let mut spec_gate: Option = None; + // Whether `-p` was given, so a task applies it rather than the default. + let mut permission_named = false; // A subcommand, not a flag, as `claude update` and the like are: only in // first place, and it takes nothing but its own `--check`. @@ -647,6 +695,7 @@ fn parse_args(args: impl Iterator) -> anyhow::Result { ); } config.permission_mode = value; + permission_named = true; } "--check-findings" => check_findings = Some(next_value(&mut args, &arg)?), "--admin" => admin_only = true, @@ -903,6 +952,9 @@ fn parse_args(args: impl Iterator) -> anyhow::Result { model: config.model_from_flag, format: output_format.unwrap_or_default(), spec_gate, + permission_mode: permission_named + .then(|| PermissionMode::parse(&config.permission_mode)) + .flatten(), }); } // Only a one-shot task has an output to format; ignored anywhere else it @@ -1518,8 +1570,10 @@ mod tests { model, format, spec_gate, + permission_mode, } => { assert_eq!(instruction, "write the brief"); + assert_eq!(permission_mode, None, "no -p, so the run's default"); assert_eq!(workspace, PathBuf::from(".")); assert_eq!(model, None); assert_eq!(format, incord_code::task_run::OutputFormat::Text); @@ -1529,6 +1583,41 @@ mod tests { } } + /// **A SCRIPT THAT ASKED FOR JSON GETS JSON, EVEN WHEN THE RUN NEVER + /// STARTS.** Only for `-t` with a JSON format; the usage text is left + /// out of the message. + #[test] + fn a_task_that_fails_to_start_still_answers_in_json() { + let args = |list: &[&str]| list.iter().map(|s| s.to_string()).collect::>(); + let line = json_failure_line( + args(&["-t", "x", "--output-format", "json", "-w", "/nope"]).into_iter(), + "workspace `/nope` is not a directory\n\nUSAGE: ...", + ) + .expect("json asked for"); + let v: serde_json::Value = serde_json::from_str(&line).expect("json"); + assert_eq!(v["type"], "result"); + assert_eq!(v["is_error"], true); + assert_eq!(v["error"], "workspace `/nope` is not a directory"); + assert!(json_failure_line( + args(&["-t", "x", "--output-format=stream-json"]).into_iter(), + "e" + ) + .is_some()); + assert!(json_failure_line(args(&["-t", "x"]).into_iter(), "e").is_none()); + assert!(json_failure_line(args(&["--output-format", "json"]).into_iter(), "e").is_none()); + } + + /// **`-p` WITH `-t` IS APPLIED, NOT IGNORED.** + #[test] + fn a_task_carries_the_permission_mode_it_was_given() { + match parse(&["-t", "look", "-w", ".", "-p", "read-only"]).expect("valid") { + Parsed::Task { + permission_mode, .. + } => assert_eq!(permission_mode, Some(incord_code::PermissionMode::ReadOnly)), + other => panic!("-t must run a task, got {other:?}"), + } + } + #[test] fn a_task_with_model_flag_carries_model() { match parse(&[ diff --git a/src/review.rs b/src/review.rs index 58b9b00..922340f 100644 --- a/src/review.rs +++ b/src/review.rs @@ -340,12 +340,15 @@ pub fn run( workspace, &ask, model, - &[], crate::task_run::OutputFormat::Text, // A review writes nothing, so the intake the spec gate asks for // would only steer the model away from the diff. crate::spec::SpecGate::Off, - &[], + // A review reads; it never writes. + &crate::task_run::RunOptions { + permission_mode: Some(crate::permissions::PermissionMode::ReadOnly), + ..Default::default() + }, ) .map(|_| ()); } @@ -357,10 +360,13 @@ pub fn run( workspace, &ask, model, - &[], crate::task_run::OutputFormat::Text, crate::spec::SpecGate::Off, - &[], + // A review reads; it never writes. + &crate::task_run::RunOptions { + permission_mode: Some(crate::permissions::PermissionMode::ReadOnly), + ..Default::default() + }, )?; let mut out = claimed.output; std::io::Write::write_all(&mut out, findings.trim().as_bytes()) diff --git a/src/task_run.rs b/src/task_run.rs index 84d69a2..d9222bf 100644 --- a/src/task_run.rs +++ b/src/task_run.rs @@ -271,24 +271,32 @@ impl Report { /// As [`run_task_with_model`]; and, for a JSON format, when stdout cannot be /// taken for it. A JSON run's `result` line says the same error. /// -/// `created` is what the process wrote outside the workspace before the run — -/// the shipped sub-agent definitions on a first run — for the `init` event. -/// -/// `command_tools`, when not empty, are a custom command's `allowed-tools`: -/// the run is held to them ([`crate::custom_commands`]). +/// `options` are what a caller may also set; [`RunOptions::default`] is none +/// of them. pub fn run_task_as( workspace: &Path, instruction: &str, model: Option<&str>, - command_tools: &[String], format: OutputFormat, spec_gate: crate::spec::SpecGate, - created: &[std::path::PathBuf], + options: &RunOptions<'_>, ) -> Result { + let RunOptions { + command_tools, + permission_mode, + created, + } = *options; crate::spec::set_for_this_run(spec_gate); if format == OutputFormat::Text { let mut report = Report::text(); - let ran = run_task_reporting(workspace, instruction, model, command_tools, &mut report); + let ran = run_task_reporting( + workspace, + instruction, + model, + command_tools, + permission_mode, + &mut report, + ); // The run's spend, once, at the end: the per-event lines above it are // each one request, and the question afterwards is what it all cost. if let Some(line) = report.cost_line() { @@ -305,11 +313,31 @@ pub fn run_task_as( .map(|path| path.to_string_lossy().into_owned()) .collect(); let began = std::time::Instant::now(); - let ran = run_task_reporting(workspace, instruction, model, command_tools, &mut report); + let ran = run_task_reporting( + workspace, + instruction, + model, + command_tools, + permission_mode, + &mut report, + ); report.finish(&ran, began.elapsed()); ran } +/// The parts of a run most callers leave alone. +#[derive(Debug, Clone, Copy, Default)] +pub struct RunOptions<'a> { + /// A custom command's `allowed-tools`, when not empty: the run is held to + /// them ([`crate::custom_commands`]). + pub command_tools: &'a [String], + /// `-p`, when given: what every candidate agent may do. + pub permission_mode: Option, + /// What the process wrote outside the workspace before the run — the + /// shipped sub-agent definitions on a first run — for the `init` event. + pub created: &'a [std::path::PathBuf], +} + /// Run one instruction through an installed agent and report what happened. /// /// Returns an error when there is no agent to drive, or when the agent could not @@ -328,7 +356,14 @@ pub fn run_task_with_model( instruction: &str, model: Option<&str>, ) -> Result { - run_task_reporting(workspace, instruction, model, &[], &mut Report::text()) + run_task_reporting( + workspace, + instruction, + model, + &[], + None, + &mut Report::text(), + ) } /// The run itself, telling `report` what happens. @@ -337,6 +372,7 @@ fn run_task_reporting( instruction: &str, model: Option<&str>, command_tools: &[String], + permission_mode: Option, report: &mut Report, ) -> Result { if instruction.trim().is_empty() { @@ -418,6 +454,7 @@ fn run_task_reporting( system: &system, tools: &tools, command_tools, + permission_mode, }; let ran = drive(&task, &mut memory, report); memory.end("other"); @@ -488,6 +525,8 @@ struct Task<'a> { tools: &'a std::sync::Arc, /// The custom command's `allowed-tools` the run is held to, if any. command_tools: &'a [String], + /// `-p`, when given: applied to every candidate agent. + permission_mode: Option, } /// The instruction, through each usable agent in turn until one runs it. @@ -528,6 +567,7 @@ fn drive( system, tools, command_tools, + permission_mode, } = *task; // WHICH ROUTE, and the CLI requirement belongs INSIDE the choice. // @@ -587,8 +627,10 @@ fn drive( .with_code_edits(crate::toolbox::CodeEdits::locate()) .with_operator_hooks(crate::hooks::HookRunner::from_settings()) .with_sandbox( - crate::admin::AdminConfig::load_default() - .sandbox_policy(crate::permissions::PermissionMode::WorkspaceWrite), + crate::admin::AdminConfig::load_default().sandbox_policy( + permission_mode + .unwrap_or(crate::permissions::PermissionMode::WorkspaceWrite), + ), ) .with_tool_allowlist(allowed_tools()), ), @@ -612,6 +654,11 @@ fn drive( // The run's one set of session tools, holding the external tools' // servers, is every candidate's. backend.share_session_tools(std::sync::Arc::clone(tools)); + // `-p`: what the agent may do, decided by the agent's own mode on a + // CLI route and by the toolbox on the API route. + if let Some(mode) = permission_mode { + backend.set_permission_mode(mode.agent_mode()); + } if !command_tools.is_empty() && !backend.runs_tools_here() { outln!( " · {}", From 822ac554a3b1532147e12fa4de8539df83962f17 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:54:31 +0000 Subject: [PATCH 5/9] Fix what the first real CI run found on Linux, Windows and macOS - Windows: an `@C:\...\file` include was not read as one (the scanner stopped at the drive's `:` and knew only `/`), so it stayed text instead of being refused as outside the workspace. `\` now separates, and a leading drive is part of the path; a `:` elsewhere still ends it. - Linux: RenderPdf through a browser that cannot build its own sandbox (the runner's Edge, whose setuid helper is not root's; Ubuntu 23.10+ without unprivileged user namespaces) now says so and what to do. incode still never passes --no-sandbox. The test skips on that machine state, as it does when there is no browser. - Windows: the UI Automation live test checked each element's centre lay on the desktop; a window wider than the runner's screen has buttons only partly on it. It now checks the rectangle overlaps the desktop, which proves the same thing (physical pixels). - macOS: sbx's .git protection is a refusal there (the Seatbelt profile denies the writes), not an undo; the test accepts that. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- crates/sandbox/tests/protect.rs | 8 ++++++- src/custom_commands.rs | 37 ++++++++++++++++++++++++++++----- src/desktop/uia.rs | 13 +++++++----- src/toolbox/pdf.rs | 34 +++++++++++++++++++++++++++++- src/toolbox/picture_tests.rs | 19 +++++++++++------ 5 files changed, 93 insertions(+), 18 deletions(-) diff --git a/crates/sandbox/tests/protect.rs b/crates/sandbox/tests/protect.rs index 9e1b691..509923d 100644 --- a/crates/sandbox/tests/protect.rs +++ b/crates/sandbox/tests/protect.rs @@ -48,7 +48,13 @@ fn a_planted_hook_and_config_are_put_back_after_the_run() { repo.join("work.txt").exists(), "ordinary work stays: {stderr}" ); - assert!(stderr.contains("protected path changed"), "{stderr}"); + // Linux puts the paths back after the run and says so; macOS's profile + // refuses the writes outright, so there is nothing to put back. + if cfg!(target_os = "macos") { + assert!(stderr.contains("Operation not permitted"), "{stderr}"); + } else { + assert!(stderr.contains("protected path changed"), "{stderr}"); + } // Opted out, the change stays. Command::new(env!("CARGO_BIN_EXE_sbx")) diff --git a/src/custom_commands.rs b/src/custom_commands.rs index bc3d840..04d7786 100644 --- a/src/custom_commands.rs +++ b/src/custom_commands.rs @@ -597,13 +597,26 @@ fn pieces(body: &str) -> Vec> { /// The path `rest` starts with, when it looks like one: the characters a /// path is written with, less a sentence's closing `.` or `:`, naming a /// folder or an extension — so `@alice` stays a mention. +/// +/// `\` separates as `/` does, and a drive (`C:\` or `C:/`) may lead, so a +/// Windows path is read whole rather than cut at its `:` — and so is checked +/// against the workspace like any other. A `:` anywhere else ends the path +/// (`@a.rs:12` is `a.rs`). fn include_path(rest: &str) -> Option<&str> { - let end = rest - .find(|c: char| !(c.is_alphanumeric() || matches!(c, '/' | '.' | '_' | '-' | '+' | '~'))) - .unwrap_or(rest.len()); + let bytes = rest.as_bytes(); + let drive = bytes.len() > 2 + && bytes[0].is_ascii_alphabetic() + && bytes[1] == b':' + && matches!(bytes[2], b'\\' | b'/'); + let skip = if drive { 2 } else { 0 }; + let end = rest[skip..] + .find(|c: char| { + !(c.is_alphanumeric() || matches!(c, '/' | '\\' | '.' | '_' | '-' | '+' | '~')) + }) + .map_or(rest.len(), |i| i + skip); let path = rest[..end].trim_end_matches(['.', ':']); - let looks_like_one = - (path.contains('/') || path.contains('.')) && path.chars().any(char::is_alphanumeric); + let looks_like_one = (path.contains(['/', '\\']) || path.contains('.')) + && path.chars().any(char::is_alphanumeric); looks_like_one.then_some(path) } @@ -913,6 +926,20 @@ mod tests { ); } + /// A Windows path is read whole, drive and backslashes included, so it + /// is judged like any other; a `:` that is not a drive still ends one. + #[test] + fn a_windows_path_is_one_include() { + assert_eq!( + include_path(r"C:\Users\me\secret.txt and more"), + Some(r"C:\Users\me\secret.txt") + ); + assert_eq!(include_path("C:/x/y.txt"), Some("C:/x/y.txt")); + assert_eq!(include_path(r"src\a.rs, then"), Some(r"src\a.rs")); + assert_eq!(include_path("a.rs:12"), Some("a.rs")); + assert_eq!(include_path("alice"), None); + } + #[test] fn what_cannot_be_included_leaves_a_marker() { let root = tempfile::tempdir().expect("dir"); diff --git a/src/desktop/uia.rs b/src/desktop/uia.rs index 61285d2..317f836 100644 --- a/src/desktop/uia.rs +++ b/src/desktop/uia.rs @@ -1165,12 +1165,15 @@ mod tests { e.rect.width > 0 && e.rect.height > 0, "kept an empty: {e:?}" ); - let p = e.click_point(); - // Inside the virtual desktop, which is what proves these are - // physical pixels rather than some window-local space. + // On the virtual desktop, which is what proves these are + // physical pixels rather than some window-local space. Its + // rectangle, not its centre: a window wider than a small + // screen (a CI runner's 1024 pixels) has buttons only partly + // on it, whose centres fall off the edge. + let r = e.rect; assert!( - p.x >= bounds.x - 1 && p.x <= bounds.x + bounds.width + 1, - "element {e:?} clicks outside the desktop at {p:?}" + r.x <= bounds.x + bounds.width + 1 && r.x + r.width >= bounds.x - 1, + "element {e:?} is not on the desktop {bounds:?}" ); } } diff --git a/src/toolbox/pdf.rs b/src/toolbox/pdf.rs index 9c9ff03..464703c 100644 --- a/src/toolbox/pdf.rs +++ b/src/toolbox/pdf.rs @@ -390,13 +390,33 @@ fn print_into( String::from_utf8_lossy(&output.stdout), String::from_utf8_lossy(&output.stderr) ); + let why = if cannot_sandbox(&said) { + format!("; {NO_BROWSER_SANDBOX}") + } else { + String::new() + }; Err(format!( - "the browser exited with {} and printed no PDF: {}", + "the browser exited with {} and printed no PDF{why}: {}", output.status, crate::text::truncate(said.trim(), 600) )) } +/// Said when the browser refused to start because it could not build its own +/// sandbox. incode never turns that sandbox off (`--no-sandbox`): the page is +/// a file the model may have written. +pub(crate) const NO_BROWSER_SANDBOX: &str = + "it could not start its own sandbox on this machine (a setuid sandbox helper \ + that is not installed as root, or unprivileged user namespaces turned off, \ + as Ubuntu 23.10 and later do by default); fix the browser's sandbox or set \ + `pdf_renderer` to another program"; + +/// Whether a Chromium-family browser's output says it could not build its +/// sandbox. +fn cannot_sandbox(said: &str) -> bool { + said.contains("SUID sandbox helper") || said.contains("No usable sandbox") +} + /// Whether `path` holds a finished PDF: the header at the start and the /// end-of-file marker at the end. A file still being written has the first /// and not yet the second. @@ -426,6 +446,18 @@ fn is_whole_pdf(path: &Path) -> bool { mod tests { use super::*; + /// A browser that could not build its own sandbox is named as such, so + /// the error says what to fix rather than only quoting the crash. + #[test] + fn a_browser_that_cannot_sandbox_itself_is_recognised() { + assert!(cannot_sandbox( + "FATAL:setuid_sandbox_host.cc(172)] The SUID sandbox helper binary was found, \ + but is not configured correctly." + )); + assert!(cannot_sandbox("No usable sandbox! Update your kernel")); + assert!(!cannot_sandbox("ERROR: net::ERR_FILE_NOT_FOUND")); + } + /// A PDF is whole only once its end marker is written: a print still in /// progress must not be taken and its browser stopped half-way. #[test] diff --git a/src/toolbox/picture_tests.rs b/src/toolbox/picture_tests.rs index 6e60ac4..1043afc 100644 --- a/src/toolbox/picture_tests.rs +++ b/src/toolbox/picture_tests.rs @@ -386,12 +386,19 @@ fn render_pdf_with_the_system_browser_has_extractable_text() { std::fs::write(ws.path().join("article.html"), ARTICLE).expect("seed"); let tools = Toolbox::new(ws.path(), true).with_printer(None, Some(pdf::Printer::Chromium(edge))); - let said = tools - .run( - RENDER_PDF, - &json!({"path": "article.html", "output": "out/article.pdf"}), - ) - .expect("printed"); + let said = match tools.run( + RENDER_PDF, + &json!({"path": "article.html", "output": "out/article.pdf"}), + ) { + Ok(said) => said, + // The machine's browser, not incode: a CI runner's Edge whose + // setuid sandbox helper is not installed as root. + Err(why) if why.contains(pdf::NO_BROWSER_SANDBOX) => { + eprintln!("SKIPPED: the system browser cannot sandbox itself here: {why}"); + return; + } + Err(why) => panic!("printed: {why}"), + }; assert!(!said.contains("IMAGE-ONLY"), "{said}"); let bytes = std::fs::read(ws.path().join("out/article.pdf")).expect("written"); assert!(bytes.starts_with(b"%PDF")); From 6c288f9ca7e1416ebc82ba588705d2b3bd9937d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 20:04:51 +0000 Subject: [PATCH 6/9] desktop: the UIA live test allows controls past a small screen's edge The first fix checked each element's rectangle overlapped the desktop; the runner's 1024-pixel screen has a window whose caption glyph sits wholly past the edge (x 1026), which UI Automation still reports. The test now checks every element is within a desktop's size of it (screen pixels, not garbage) and at least one is on it (the window is in the mouse's space). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- src/desktop/uia.rs | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/src/desktop/uia.rs b/src/desktop/uia.rs index 317f836..23250c3 100644 --- a/src/desktop/uia.rs +++ b/src/desktop/uia.rs @@ -1160,20 +1160,34 @@ mod tests { let screen = crate::desktop::screen_info().expect("screen"); let bounds = screen.virtual_bounds().expect("a desktop"); + let on_desktop = |r: Rect| { + r.x <= bounds.x + bounds.width + && r.x + r.width >= bounds.x + && r.y <= bounds.y + bounds.height + && r.y + r.height >= bounds.y + }; for e in &tree.elements { assert!( e.rect.width > 0 && e.rect.height > 0, "kept an empty: {e:?}" ); - // On the virtual desktop, which is what proves these are - // physical pixels rather than some window-local space. Its - // rectangle, not its centre: a window wider than a small - // screen (a CI runner's 1024 pixels) has buttons only partly - // on it, whose centres fall off the edge. - let r = e.rect; + // Within a desktop's size of the desktop: screen pixels, not + // garbage. Not every element is ON it — a window wider than a + // small screen (a CI runner's 1024 pixels) has controls past + // the edge, which UI Automation still reports. + assert!( + e.rect.x >= bounds.x - bounds.width + && e.rect.x <= bounds.x + 2 * bounds.width + && e.rect.y >= bounds.y - bounds.height + && e.rect.y <= bounds.y + 2 * bounds.height, + "element {e:?} is nowhere near the desktop {bounds:?}" + ); + } + // And the window is on the desktop: the same space the mouse uses. + if !tree.elements.is_empty() { assert!( - r.x <= bounds.x + bounds.width + 1 && r.x + r.width >= bounds.x - 1, - "element {e:?} is not on the desktop {bounds:?}" + tree.elements.iter().any(|e| on_desktop(e.rect)), + "no element of the focused window is on the desktop {bounds:?}" ); } } From e6c8058cf681cae0c917d1c5678985a74264c94f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 20:51:20 +0000 Subject: [PATCH 7/9] tests: a fake server never holds the env lock forever; CI jobs time out Windows CI hung 35 minutes in cargo test --lib: brief's served-brief test joins its one-shot server while holding ENV_LOCK, and when the request never came accept() waited for ever, so every env test queued behind it. Both fake servers in brief.rs now accept within 30 seconds or end, which turns that into a failure that says what check() returned. CI's test jobs time out at 45 minutes instead of GitHub's six hours. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- .github/workflows/ci.yml | 3 +++ src/brief.rs | 32 ++++++++++++++++++++++++++++++-- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9a3e4f3..1aac683 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,6 +51,9 @@ jobs: matrix: os: [windows-latest, macos-latest, ubuntu-latest] runs-on: ${{ matrix.os }} + # A whole run takes under 15 minutes; a test that hangs fails the job + # here instead of holding it for GitHub's 6-hour default. + timeout-minutes: 45 steps: - uses: actions/checkout@v4 # The Linux desktop backends (xcap, enigo's x11rb, AT-SPI over zbus) diff --git a/src/brief.rs b/src/brief.rs index 23b2811..e05d5f3 100644 --- a/src/brief.rs +++ b/src/brief.rs @@ -2460,6 +2460,30 @@ mod tests { /// Proves the real request path, not just the parsing: a served payload /// reaches `check` and resolves to a decision. + /// One connection to a fake server, or `None` after 30 seconds. These + /// servers are joined while the test holds ENV_LOCK, so a request that + /// never comes must end the server rather than hold every env test behind + /// it (seen on Windows CI: four tests stuck for 35 minutes). + fn accept_within(listener: &std::net::TcpListener) -> Option { + listener.set_nonblocking(true).expect("nonblocking"); + let deadline = std::time::Instant::now() + std::time::Duration::from_secs(30); + loop { + match listener.accept() { + Ok((socket, _)) => { + socket.set_nonblocking(false).expect("blocking"); + return Some(socket); + } + Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => { + if std::time::Instant::now() > deadline { + return None; + } + std::thread::sleep(std::time::Duration::from_millis(20)); + } + Err(e) => panic!("accept: {e}"), + } + } + } + #[test] fn a_served_brief_is_read_over_http() { use std::io::{Read as _, Write as _}; @@ -2468,7 +2492,9 @@ mod tests { let addr = listener.local_addr().expect("addr"); let server = std::thread::spawn(move || { - let (mut socket, _) = listener.accept().expect("accept"); + let Some(mut socket) = accept_within(&listener) else { + return; + }; let mut buf = [0u8; 4096]; let _ = socket.read(&mut buf); let body = r#"{"briefs":[{"project":"served-demo","about":"a","goals":"g", @@ -3048,7 +3074,9 @@ No auth in v1. let addr = listener.local_addr().expect("addr"); let server = std::thread::spawn(move || { - let (mut socket, _) = listener.accept().expect("accept"); + let Some(mut socket) = accept_within(&listener) else { + return; + }; let mut buf = [0u8; 4096]; let n = socket.read(&mut buf).expect("read"); let request = String::from_utf8_lossy(&buf[..n]); From 06ce52247109c65caa49d4c8ec339fb67c7feb71 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 21:06:14 +0000 Subject: [PATCH 8/9] tests: every test that sets INCODE_LANES holds ENV_LOCK runner.rs's a_repo() hands back the temp dir as `_guard`, which locks nothing, so five runner tests and one in parallel.rs set and removed INCODE_LANES concurrently. On Windows CI a_single_lane_never_creates_a_ worktree removed it mid-way through what_a_lane_spends_is_charged_to_the_ run, which then ran sequentially and failed. They now hold the env lock the other env tests share. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- src/parallel.rs | 3 +++ src/runner.rs | 15 +++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/src/parallel.rs b/src/parallel.rs index c575e19..bf9f2c9 100644 --- a/src/parallel.rs +++ b/src/parallel.rs @@ -1583,6 +1583,9 @@ mod tests { /// The requested count is read from the environment and clamped. #[test] fn the_requested_count_falls_back_to_one() { + let _env = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); std::env::remove_var(LANES_ENV); assert_eq!( requested_lanes(), diff --git a/src/runner.rs b/src/runner.rs index e61e411..8db3f84 100644 --- a/src/runner.rs +++ b/src/runner.rs @@ -2380,6 +2380,9 @@ mod tests { /// the runner still decided. #[test] fn two_ready_tasks_are_worked_in_parallel_and_both_land() { + let _env = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); let Some((_guard, root)) = a_repo() else { return; }; @@ -2493,6 +2496,9 @@ mod tests { /// and the run must not report plain success. #[test] fn a_lane_that_could_not_merge_is_not_recorded_as_finished() { + let _env = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); let Some((_guard, root)) = a_repo() else { return; }; @@ -2772,6 +2778,9 @@ mod tests { /// task the retry is given names it. #[test] fn a_conflicted_lane_tells_the_retry_where_its_work_is() { + let _env = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); let Some((_guard, root)) = a_repo() else { return; }; @@ -2963,6 +2972,9 @@ mod tests { /// and believes in it. #[test] fn what_a_lane_spends_is_charged_to_the_run() { + let _env = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); let Some((_guard, root)) = a_repo() else { return; }; @@ -3001,6 +3013,9 @@ mod tests { /// nobody's run alters shape because they upgraded. #[test] fn a_single_lane_never_creates_a_worktree() { + let _env = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); let Some((_guard, root)) = a_repo() else { return; }; From d6c1203a8cf2e19e05481d797a8d7bf966750950 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 21:14:54 +0000 Subject: [PATCH 9/9] sbx: the policy doc-example test reads a CRLF checkout too Windows runners check files out with CRLF, so splitting the module source on "//! ```toml\n" found no example. It splits on the fence alone; lines() already takes either ending. Checked with the file converted to CRLF. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT --- crates/sandbox/src/policy.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/sandbox/src/policy.rs b/crates/sandbox/src/policy.rs index 82ca821..e623db7 100644 --- a/crates/sandbox/src/policy.rs +++ b/crates/sandbox/src/policy.rs @@ -370,7 +370,8 @@ mod tests { #[test] fn the_documented_example_parses() { let doc = include_str!("policy.rs") - .split("//! ```toml\n") + // Not `toml\n`: a Windows checkout has CRLF line endings. + .split("//! ```toml") .nth(1) .and_then(|rest| rest.split("//! ```").next()) .expect("the module docs carry an example");