diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 48070b3..1aac683 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: @@ -34,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/README.md b/README.md index f1ecbb9..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 @@ -1352,11 +1353,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..74620b7 --- /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 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 | + +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/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"); 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/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"] +} diff --git a/scripts/test-all.sh b/scripts/test-all.sh new file mode 100755 index 0000000..f52f53f --- /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 sdk/python/tests + 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" 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..e01572a --- /dev/null +++ b/sdk/README.md @@ -0,0 +1,71 @@ +# 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` 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. +- 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"] +} 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/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]); 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..23250c3 100644 --- a/src/desktop/uia.rs +++ b/src/desktop/uia.rs @@ -1160,17 +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:?}" ); - let p = e.click_point(); - // Inside the virtual desktop, which is what proves these are - // physical pixels rather than some window-local space. + // 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!( - p.x >= bounds.x - 1 && p.x <= bounds.x + bounds.width + 1, - "element {e:?} clicks outside the desktop at {p:?}" + tree.elements.iter().any(|e| on_desktop(e.rect)), + "no element of the focused window is on the desktop {bounds:?}" ); } } 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/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/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/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; }; 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!( " · {}", 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"));