acp-port 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+Releases and their changes are recorded here automatically by semantic-release.

package/CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing to ACP Port
+
+ACP Port is a TypeScript ACP agent that connects an editor to an LLM API. Contributions can improve provider compatibility, editor behavior, tool execution, documentation, or the development workflow. The [architecture guide](docs/architecture.md) explains the runtime and extension points; the [README](README.md) covers installation and everyday use.
+
+## Set up a checkout
+
+Use Node.js **24.21.0** and **pnpm 12.8.1**, as pinned in `mise.toml`; run `mise install` if you use mise. Source development requires Node.js **22.14.0 or newer** because of the release tooling. The published CLI itself supports Node.js 22.12.0 or newer. CI checks Node.js 22 and 24. Clone your fork or the repository, enter its directory, and install the versions recorded in the lockfile:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm run build
+```
+
+`pnpm install --frozen-lockfile` requires the committed `pnpm-lock.yaml`. Use `pnpm add <package>` or `pnpm add -D <package>` when intentionally adding dependencies, and commit the manifest and lockfile changes together. Keep pnpm as the package manager and do not create an npm lockfile.
+
+The automated tests use fake providers, temporary workspaces, and local HTTP servers. They do not need API credentials or a running local model server. Tests that open loopback listeners need an environment that permits local networking.
+
+## Run and develop the CLI
+
+Run directly from TypeScript during development:
+
+```sh
+pnpm run dev --help
+pnpm run dev models --base-url http://127.0.0.1:1234/v1
+pnpm run dev models --base-url http://127.0.0.1:11434/v1 --json
+```
+
+The `models` examples require the corresponding endpoint to be running. Model discovery lists available models; it does not download them.
+
+Build and check the executable users will actually run:
+
+```sh
+pnpm run build
+node dist/cli/index.js --help
+node dist/cli/index.js --version
+```
+
+To test your changes in an ACP editor, use an absolute Node executable path and the absolute path to the built `dist/cli/index.js` in the editor's agent configuration. Rebuild after source changes and restart the editor's agent process. Starting a new conversation within the same existing process does not reload JavaScript.
+
+The user-facing examples launch the npm release through `npx -y acp-port`. To test this checkout instead, replace that entry's `command` with your absolute Node executable path and replace its first two arguments, `"-y", "acp-port"`, with the absolute path to `dist/cli/index.js`. Keep the remaining endpoint options and environment unchanged.
+
+For a development entry that skips compilation, launch `tsx` through Node directly:
+
+```json
+{
+  "command": "/absolute/path/to/node",
+  "args": [
+    "--import",
+    "/absolute/path/to/acp-port/node_modules/tsx/dist/loader.mjs",
+    "/absolute/path/to/acp-port/src/cli/index.ts",
+    "--base-url",
+    "http://127.0.0.1:1234/v1"
+  ],
+  "env": {
+    "API_KEY": ""
+  }
+}
+```
+
+This is the launch object; place it in the structure your editor expects, as shown in the [editor integration guide](docs/editor-integration.md), replacing its npx launch settings. The loader path is specific to the installed `tsx` package layout; use the npm release for regular use and the built entry point to check compiled local changes. Restart the agent after edits when using this source entry as well. The empty `API_KEY` is appropriate for an unauthenticated local endpoint.
+
+Launch the Node entry point directly in editor configurations: package-manager script wrappers can write banners to stdout. During ACP operation, stdout must contain only protocol messages. Send diagnostics to stderr.
+
+## Commands and checks
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm run dev <args>` | Run the source CLI using `tsx`. |
+| `pnpm run typecheck` | Check production and test TypeScript without emitting files. |
+| `pnpm test` | Run `src/**/*.test.ts` with the Node.js test runner and `tsx`; each test has a 15-second timeout. |
+| `pnpm run check` | Run type checking followed by the test suite. |
+| `pnpm run build` | Emit ESM JavaScript, source maps, and declarations to `dist/`; exclude tests. |
+| `pnpm run format:check` | Check formatting with Biome without writing fixes. |
+| `pnpm run lint` | Run Biome checks **and write fixes**, including formatting and import organization. |
+| `pnpm run lint:check` | Run Biome checks without writing fixes. |
+| `pnpm pack --dry-run` | Rebuild and inspect the package file list without publishing. |
+
+Before opening a pull request, run the same checks as CI:
+
+```sh
+pnpm run check
+pnpm run build
+pnpm run format:check
+pnpm run lint:check
+```
+
+CI runs these after `pnpm install --frozen-lockfile` on both supported Node.js matrix versions and verifies the npm package contents. `pnpm run check` runs type checking and tests; build, formatting, and lint checks are separate. After both matrix jobs pass, qualifying commits on the canonical repository's default branch trigger the automated release. Pull requests and fork pushes only run checks. See the [release guide](docs/releases.md) for maintainer setup.
+
+For a focused test run:
+
+```sh
+node --import tsx --test --test-timeout=15000 src/providers/adapters/openai-provider.test.ts
+node --import tsx --test --test-timeout=15000 --test-name-pattern="cancellation" "src/**/*.test.ts"
+```
+
+`tsx` executes TypeScript but does not replace type checking. Run `pnpm run typecheck` after changing types or adding tests.
+
+## Find the code to change
+
+| Change | Starting point | Relevant tests |
+| --- | --- | --- |
+| CLI options, defaults, or validation | `src/cli/arguments.ts`, `src/config/schema.ts` | `src/cli/arguments.test.ts`, `src/config/schema.test.ts`, `src/cli/index.test.ts` |
+| Model discovery or endpoint selection | `src/providers/provider-registry.ts`, `src/agent/session.ts` | `src/providers/provider-registry.test.ts`, `src/agent/agent.test.ts` |
+| OpenAI-compatible streaming or Gemini metadata | `src/providers/adapters/openai-provider.ts` | `src/providers/adapters/openai-provider.test.ts` |
+| Anthropic Messages API | `src/providers/adapters/anthropic-provider.ts` | `src/providers/adapters/anthropic-provider.test.ts` |
+| Credentials, SDK setup, request deadlines | `src/providers/support/` | Tests beside those modules |
+| Session state, prompt processing, model/tool loop | `src/agent/` | `src/agent/agent.test.ts` |
+| Tool schemas, permissions, paths, terminals | `src/tools/` | `src/tools/runner.test.ts` |
+| Process lifecycle or ACP stdio transport | `src/acp/stdio.ts`, `src/cli/index.ts` | `src/acp/stdio.test.ts`, `src/cli/index.test.ts` |
+
+See [extending the implementation](docs/architecture.md#extending-the-implementation) for the files and behavior required when adding a provider, tool, or ACP capability.
+
+## Testing expectations
+
+Add regression coverage for behavior changes at the layer responsible for them. Existing tests demonstrate the conventions:
+
+- **Provider tests** run local HTTP servers that return model lists, streamed text, tool fragments, API failures, or stalled responses. Test outgoing request payloads and observable events, including incomplete streams and cancellation.
+- **Agent tests** connect an ACP client to the agent and inject a fake provider factory. Test protocol state, session isolation, model switching, history, tool loops, and stop reasons without invoking a real LLM.
+- **Tool tests** supply a fake ACP client and temporary workspace. Cover permission denial, invalid input, path traversal and symlinks, timeout handling, and terminal cleanup where relevant.
+- **CLI and stdio tests** spawn `src/cli/index.ts` using `node --import tsx`. The stdio tests exercise an HTTP-backed tool round trip through a simulated editor; they do not require a previous build.
+
+Keep fixtures and test credentials synthetic. Assert that credentials, endpoint configuration, and provider metadata stay within the intended endpoint. When changing tool handling, verify that interrupted or denied operations cannot later execute after a delayed editor response.
+
+Real editor and provider smoke tests are useful when changing compatibility. Record the editor, provider/server version, model, and what you exercised in the pull request. Automated mocks do not establish that every advertised model works in a real editor. Use your own disposable workspace for manual file and command tests.
+
+## Code conventions
+
+- Use TypeScript with the repository's strict settings and NodeNext ESM imports. Local imports in source files use the emitted `.js` extension.
+- Follow `.editorconfig` and Biome: two spaces, LF newlines, a final newline, and organized imports.
+- Keep vendor SDK types and wire formats inside provider adapters and support modules. The agent and tools exchange the types in `provider-contract.ts`.
+- Keep schemas strict. Validate configuration and tool input before use, and preserve cancellation and output limits.
+- Keep endpoint selection explicit. Do not add automatic fallback to another provider or ambient SDK credential discovery.
+- Preserve ACP stdout. Log human-readable diagnostics to stderr and avoid exposing SDK response bodies or request credentials.
+
+## Package verification
+
+The package delivers the `acp-port` executable at `dist/cli/index.js`; it has no public JavaScript import API. Its internal modules use ESM. TypeScript also emits `.d.ts` and `.js.map` files. Production builds exclude `*.test.ts`.
+
+Run `pnpm pack --dry-run` to inspect what a package consumer receives. The `prepack` hook cleans and rebuilds the output. The manifest includes `dist/`, `docs/`, `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md`, and `LICENSE`, so the user guides, including their inline editor configurations, ship with the executable. The source tree is not packaged; use a repository checkout for development. Review the actual file list after any packaging change. Build output is ignored by Git and should not be hand-edited.
+
+When running `pnpm run build` directly after deleting or renaming source modules, run `pnpm run clean` first: TypeScript does not remove output left by previous builds. Packaging already performs this cleanup through `prepack`.
+
+To exercise a real local tarball without publishing:
+
+```sh
+pnpm pack
+```
+
+Install the resulting `.tgz` into a temporary consumer project and run its `acp-port --help` and `acp-port --version` commands. This validates package layout and executable resolution without relying on an npm release. The release workflow publishes to npm after CI passes; a successful local build does not establish that a version is available on npm.
+
+## Pull requests and bug reports
+
+Use a [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) title for your pull request, for example `fix(cli): preserve an explicitly empty API key` or `feat(providers): support another model API`. The PR title check validates this format. Prefer squash merging and keep the PR title as the squash commit subject so semantic-release can determine the version from the default branch's history.
+
+- `fix:` and `perf:` produce patch releases.
+- `feat:` produces a minor release.
+- A `!` after the type/scope or a `BREAKING CHANGE:` footer produces a major release.
+- `docs:`, `test:`, `refactor:`, `build:`, `ci:`, `style:`, and `chore:` do not produce releases by themselves; a breaking change still does.
+
+Use the squash commit body for any `BREAKING CHANGE:` explanation. If a maintainer chooses another merge method, the commits that land on the default branch must carry the intended release information. Do not manually bump `package.json`, create release tags, or edit generated changelog entries. The [release guide](docs/releases.md) describes how those artifacts are created.
+
+Keep a pull request focused on a concrete behavior. Explain the problem, the resulting behavior, relevant tests, and any manual compatibility checks. Update the README and reference pages, including their editor configuration examples, when user-visible behavior changes. Do not include real API keys, private endpoint headers, generated build files, or unrelated formatting changes.
+
+For a bug report, include the ACP Port and Node.js versions, operating system, editor version, provider type, sanitized launch arguments, model ID, and a minimal reproduction. Distinguish a failed model-list request from a failed prompt or tool call. Redact secrets and private prompt/file content from logs.
+
+The project is licensed under the [MIT License](LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 acp-port contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+# acp-port
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Connect a model API to your editor through the Agent Client Protocol.**
+
+acp-port is a TypeScript CLI that runs as an ACP coding agent. It connects an ACP-capable editor to local model servers, LLM gateways, and cloud APIs. The editor provides the conversation UI, workspace context, permissions, and file/terminal access; acp-port handles model discovery, streaming responses, conversation history, and the model's tool loop.
+
+Use it with LM Studio, Ollama, LiteLLM, OpenRouter, OpenAI, Anthropic, or Google's OpenAI-compatible Gemini endpoint. Choose the endpoint and model you want to use, then register acp-port as a custom agent in your editor.
+
+## Documentation
+
+| I want to… | Start here |
+| --- | --- |
+| Run it for the first time | [Quick start](#quick-start) |
+| Connect Zed, JetBrains Air, JetBrains AI Assistant, or another ACP client | [Editor integration](docs/editor-integration.md) |
+| Configure a particular model server or cloud service | [Provider guide](docs/providers.md) |
+| Understand every CLI flag, environment variable, and default | [Configuration reference](docs/configuration.md) |
+| Understand tools, permissions, data flow, and limits | [Capabilities and limits](docs/capabilities.md) |
+| Diagnose startup, model, authentication, or tool errors | [Troubleshooting](docs/troubleshooting.md) |
+| Develop, test, or contribute to the project | [Contributing](CONTRIBUTING.md) |
+| Configure automatic versions, changelogs, tags, and npm publishing | [Release guide](docs/releases.md) |
+| Understand the implementation or add a provider/tool | [Architecture and extension guide](docs/architecture.md) |
+
+## How it works
+
+[ACP](https://agentclientprotocol.com/get-started/introduction) standardizes communication between editors and coding agents. acp-port implements the agent side and translates model API responses into ACP messages.
+
+```mermaid
+flowchart LR
+    Editor["ACP editor / IDE"] <-->|"ACP over stdin/stdout"| Agent["acp-port"]
+    Agent <-->|"HTTP: model discovery + streaming inference"| API["Local server or cloud API"]
+    Agent -->|"File, terminal, and permission requests"| Editor
+```
+
+A typical turn works like this:
+
+1. The editor launches acp-port and opens a session with a workspace directory.
+2. acp-port discovers the endpoint's models and returns a model selector to the editor.
+3. Your prompt and conversation history go to the selected model API.
+4. Text streams back to the editor. If the model requests a tool, acp-port validates the request and uses the editor's ACP file or terminal capability.
+5. Tool results go back to the model, which can continue working or finish the turn.
+
+The CLI starts a process that speaks ACP over stdio. It has no interactive terminal chat UI or HTTP listening port. Model servers still run separately. Model discovery lists available IDs; it does not download weights. acp-port does not launch other coding agents or run MCP servers.
+
+## Quick start
+
+### 1. Run with npx
+
+Requires **Node.js 22.12 or later**, with npm and npx available. Run the published CLI directly:
+
+```sh
+npx -y acp-port --version
+npx -y acp-port --help
+```
+
+No repository checkout, build step, or global installation is needed for the npm release. `npx` downloads the package when needed, and `-y` skips npm's installation confirmation so editor launches can proceed without an interactive prompt. See the [npm npx reference](https://docs.npmjs.com/cli/v11/commands/npx).
+
+**Release status:** `acp-port` is not yet available on the public npm registry. The `npx` examples describe usage after the first npm release. To try the unpublished source or contribute changes, follow [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### 2. Start your endpoint and check its models
+
+For LM Studio, download a suitable chat model in LM Studio and start its local API server. For the usual local port:
+
+```sh
+API_KEY='' npx -y acp-port models --base-url http://127.0.0.1:1234/v1
+```
+
+For a running Ollama server with a model already downloaded:
+
+```sh
+API_KEY='' npx -y acp-port models --base-url http://127.0.0.1:11434/v1
+```
+
+For an authenticated gateway, set `API_KEY` in the process environment:
+
+```sh
+API_KEY=YOUR_GATEWAY_KEY npx -y acp-port models \
+  --base-url https://gateway.example.com/v1 --json
+```
+
+The local examples clear any inherited key for an unauthenticated server; substitute its token if you enabled authentication. The inline environment syntax above is for POSIX shells. In PowerShell, use `$env:API_KEY = "YOUR_GATEWAY_KEY"` (or `""` for no key) before running the command. Editor examples use an `env` object instead.
+
+`models` prints a catalog and exits. A catalog entry such as `endpoint/vendor/model` contains an internal endpoint prefix; pass only the upstream ID, `vendor/model`, to `--default-model`.
+
+If your server cannot list models, provide a known model ID:
+
+```sh
+npx -y acp-port models \
+  --base-url http://127.0.0.1:1234/v1 \
+  --default-model YOUR_MODEL_ID --no-discovery
+```
+
+With discovery disabled, this command checks the configured catalog without contacting the endpoint. Your first editor prompt tests inference. See the [provider guide](docs/providers.md) for server preparation, authentication, and compatibility requirements.
+
+### 3. Add it to your editor
+
+For Zed, add a custom agent under `agent_servers` in your settings:
+
+```json
+{
+  "agent_servers": {
+    "LM Studio via acp-port": {
+      "type": "custom",
+      "command": "npx",
+      "args": [
+        "-y", "acp-port",
+        "--base-url", "http://127.0.0.1:1234/v1",
+        "--default-model", "YOUR_MODEL_ID"
+      ],
+      "env": { "API_KEY": "" }
+    }
+  }
+}
+```
+
+Replace `YOUR_MODEL_ID` with an upstream ID from discovery. Setting `API_KEY` to an empty string deliberately disables authentication for this local endpoint, even if the editor inherits a key from your shell. Set the endpoint's actual key when authentication is enabled. If the editor cannot find `npx`, see the [launch settings and PATH guidance](docs/editor-integration.md#understand-the-launch-settings).
+
+Open a project, select this agent, and start a conversation. An explicit `--default-model` chooses the initial model; other discovered models remain selectable. Without it, acp-port selects the first discovered model, which may not be the model you want for coding.
+
+The [editor integration guide](docs/editor-integration.md) includes copyable configurations for Zed and JetBrains, multiple endpoints, Windows paths, remote workspaces, and a first-session smoke test.
+
+## Choosing a provider
+
+`--provider` selects an API adapter. `--base-url` selects the actual server. For example, `--provider openai --base-url http://127.0.0.1:11434/v1` sends requests to Ollama using the OpenAI API format.
+
+| Service | Adapter | Base URL | Authentication |
+| --- | --- | --- | --- |
+| LM Studio | `openai` (default) | `http://127.0.0.1:1234/v1` | Optional, depending on server settings |
+| Ollama | `openai` | `http://127.0.0.1:11434/v1` | Usually omitted for a local server |
+| LiteLLM | `openai` | Your gateway's API base URL | Gateway key, when required |
+| OpenRouter | `openai` | `https://openrouter.ai/api/v1` | OpenRouter API key |
+| OpenAI | `openai` | `https://api.openai.com/v1` (default) | OpenAI API key |
+| Anthropic | `anthropic` | `https://api.anthropic.com` (default for this adapter) | Anthropic API key |
+| Gemini | `gemini` | `https://generativelanguage.googleapis.com/v1beta/openai` (default for this adapter) | Gemini API key |
+
+All CLI providers read **`API_KEY`**. Variables such as `OPENAI_API_KEY` do not configure this CLI. Anthropic and Gemini require a nonblank key; the OpenAI adapter allows unauthenticated local servers, but the hosted OpenAI service requires authentication. See [provider setup and official API references](docs/providers.md).
+
+OpenAI, Gemini, and compatible gateways use streaming **Chat Completions**. Anthropic uses the native **Messages API**. The endpoint must support the selected protocol; a model appearing in `/models` does not establish chat support, tool support, or account access to inference. The OpenAI Responses API is not implemented.
+
+Each CLI process connects to one endpoint. Create separate editor entries to use multiple servers or credentials. Requests do not automatically fall back to another provider.
+
+## Commands and settings
+
+```sh
+# Inspect the available options.
+npx -y acp-port --help
+
+# Discover models without starting an ACP session.
+npx -y acp-port models --base-url http://127.0.0.1:1234/v1 --json
+
+# Start the ACP agent; omitting "serve" has the same effect.
+npx -y acp-port serve --base-url http://127.0.0.1:1234/v1
+
+# Use a known model without a model-list request.
+npx -y acp-port --base-url http://127.0.0.1:1234/v1 \
+  --default-model YOUR_MODEL_ID --no-discovery
+```
+
+| Option | Purpose |
+| --- | --- |
+| `--provider openai\|anthropic\|gemini` | Choose the API format and default URL. Defaults to `openai`. |
+| `--base-url URL` | Override the API base URL. |
+| `--default-model MODEL_ID` | Select one initial upstream model ID and keep it available if discovery fails. |
+| `--name NAME` | Set the endpoint label used in model names. |
+| `--no-discovery` | Skip model discovery. Requires `--default-model`. |
+| `--no-tools` | Omit all tools for models that only support text chat. |
+| `--json` | Print structured catalog data with the `models` command. |
+| `--help`, `-h`, `--version` | Print usage or version and exit. |
+
+Connection options and `API_KEY` are supplied per launch. There is no acp-port configuration file, automatic `.env` loading, or interactive sign-in flow. Your editor's settings file configures how the editor launches the process.
+
+The [configuration reference](docs/configuration.md) documents validation, model IDs, environment handling, and fixed CLI limits. Settings without CLI flags, such as custom headers, timeouts, and the system prompt, require source changes.
+
+## Capabilities and limits
+
+- Streams text and accepts embedded text resources. Resource links supply metadata; their contents are not automatically fetched.
+- Exposes `read_file`, `write_file`, and `run_command` when the editor advertises the matching ACP capabilities and tools are enabled.
+- Requests editor permission before each write or command. File reads do not request a separate approval from acp-port.
+- Validates file paths and command working directories against the session workspace. Commands run with the editor's permissions; acp-port provides no operating-system sandbox.
+- Keeps sessions in memory. Restarting the agent loses their history; session reload and automatic history summarization are unavailable.
+- Defaults to 12 model requests per turn, 200,000 history characters, and 120-second provider/tool timeouts. A character budget is not a model token budget.
+- Supports text-based coding workflows. Images, audio, binary attachments, and MCP servers are unsupported; sessions that forward MCP servers are rejected.
+
+Prompts, attached text, conversation history, and tool results are sent to the selected model endpoint. Choose that endpoint with your workspace's data requirements in mind. See [capabilities and limits](docs/capabilities.md) for the exact tool behavior and data flow.
+
+Automated tests cover mocked provider APIs, ACP sessions, permission handling, and a stdio tool round trip. They do not establish compatibility with every model or replace a live test in your editor. For common failures, see [troubleshooting](docs/troubleshooting.md).
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run dev --help
+pnpm run dev models --base-url http://127.0.0.1:1234/v1
+pnpm run check
+pnpm run build
+pnpm run format:check
+pnpm run lint:check
+```
+
+Use **Node.js 24.21.0 and pnpm 12.8.1** for development; `mise install` installs these versions from `mise.toml`. Source development requires Node.js 22.14.0 or newer because of the release tooling, while the published CLI supports Node.js 22.12.0 or newer. The committed `pnpm-lock.yaml` makes local and CI installs repeatable.
+
+The project uses TypeScript, native ESM, the ACP SDK, Zod, and the OpenAI/Anthropic SDKs. Tests run directly from TypeScript with Node's test runner and `tsx`; a build is not required to run them. Editors using `dist/cli/index.js` require a new build and process restart to pick up source changes.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the local workflow, focused tests, package checks, and contribution guidance. GitHub Actions checks Node.js 22 and 24, then semantic-release publishes qualifying commits from the default branch with a changelog, Git tag, and GitHub Release. See the [release guide](docs/releases.md) for the one-time npm and GitHub setup. The [architecture guide](docs/architecture.md) maps the internal modules, explains the session/tool loop, and walks through adding providers and tools.
+
+## Migrating from older configuration
+
+File-based configuration and external-agent management are no longer supported. `acp-port.json` and `ACP_PORT_CONFIG` are ignored, and old configuration files are left on disk. Move connection settings into each editor entry's arguments and `env.API_KEY`. Replace old options with those in the [configuration reference](docs/configuration.md).
+
+The ACP agent registry distributes ready-made agents. It is separate from a model server's catalog. acp-port connects model APIs to ACP; it does not install or launch agents from that registry.
+
+## License
+
+[MIT](LICENSE).

package/dist/acp/stdio.d.ts

@@ -0,0 +1,3 @@
+import { type AgentOptions } from "../agent/agent.js";
+import type { Config } from "../config/schema.js";
+export declare function serve(config: Config, options: AgentOptions): Promise<void>;

package/dist/acp/stdio.js

@@ -0,0 +1,23 @@
+import stream from "node:stream";
+import { ndJsonStream } from "@agentclientprotocol/sdk";
+import { createAgent } from "../agent/agent.js";
+import { createProvider } from "../providers/create-provider.js";
+import { ProviderRegistry } from "../providers/provider-registry.js";
+export async function serve(config, options) {
+    const registry = new ProviderRegistry(config.providers, createProvider, (message) => process.stderr.write(`acp-port: ${message}\n`));
+    const transport = ndJsonStream(stream.Writable.toWeb(process.stdout), stream.Readable.toWeb(process.stdin));
+    const connection = createAgent(config, registry, options).connect(transport);
+    const close = () => {
+        void connection.close();
+    };
+    process.on("SIGINT", close);
+    process.on("SIGTERM", close);
+    try {
+        await connection.closed;
+    }
+    finally {
+        process.off("SIGINT", close);
+        process.off("SIGTERM", close);
+    }
+}
+//# sourceMappingURL=stdio.js.map

package/dist/acp/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/acp/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAqB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,MAAc,EACd,OAAqB;IAErB,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CACnC,MAAM,CAAC,SAAS,EAChB,cAAc,EACd,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,OAAO,IAAI,CAAC,CAC5D,CAAC;IACF,MAAM,SAAS,GAAG,YAAY,CAC5B,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACrC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CACrC,CAAC;IACF,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC5B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,MAAM,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/agent/agent.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from "../config/schema.js";
+import type { ProviderRegistry } from "../providers/provider-registry.js";
+import { type AgentOptions } from "./session.js";
+export type { AgentOptions } from "./session.js";
+export declare function createAgent(config: Config, registry: ProviderRegistry, options?: AgentOptions): import("@agentclientprotocol/sdk").AgentApp;

package/dist/agent/agent.js

@@ -0,0 +1,110 @@
+import { agent, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
+import { z } from "zod";
+import pkg from "../../package.json" with { type: "json" };
+import { createSession, getSessionConfigOptions, selectSessionModel, } from "./session.js";
+import { runSessionPrompt } from "./turn.js";
+export function createAgent(config, registry, options = {}) {
+    let initialized = false;
+    let capabilities = {};
+    const sessions = new Map();
+    const getSession = (id) => {
+        if (!initialized) {
+            throw RequestError.invalidRequest(undefined, "Initialize the connection first.");
+        }
+        const session = sessions.get(id);
+        if (!session) {
+            throw RequestError.invalidParams(undefined, "Unknown session.");
+        }
+        return session;
+    };
+    const updateSelectedModel = async (session, modelId, client) => {
+        selectSessionModel(session, modelId);
+        const configOptions = getSessionConfigOptions(session);
+        await client.notify("session/update", {
+            sessionId: session.id,
+            update: { sessionUpdate: "config_option_update", configOptions },
+        });
+        return configOptions;
+    };
+    return (agent({ name: "acp-port" })
+        .onConnect(({ signal }) => {
+        signal.addEventListener("abort", () => {
+            for (const session of sessions.values()) {
+                session.activeTurn?.abort();
+            }
+            sessions.clear();
+        }, { once: true });
+    })
+        .onRequest("initialize", ({ params }) => {
+        if (initialized) {
+            throw RequestError.invalidRequest(undefined, "This connection is already initialized.");
+        }
+        capabilities = params.clientCapabilities ?? {};
+        initialized = true;
+        return {
+            protocolVersion: PROTOCOL_VERSION,
+            agentInfo: {
+                name: "acp-port",
+                title: "ACP Port",
+                version: pkg.version,
+            },
+            agentCapabilities: {
+                loadSession: false,
+                promptCapabilities: {
+                    embeddedContext: true,
+                    image: false,
+                    audio: false,
+                },
+                mcpCapabilities: { http: false, sse: false },
+            },
+            authMethods: [],
+        };
+    })
+        .onRequest("authenticate", () => {
+        throw RequestError.invalidParams(undefined, "API credentials come from the configured environment variable. Interactive authentication is not supported.");
+    })
+        .onRequest("session/new", async ({ params, signal }) => {
+        if (!initialized) {
+            throw RequestError.invalidRequest(undefined, "Initialize the connection first.");
+        }
+        if (params.mcpServers.length) {
+            throw RequestError.invalidParams(undefined, "MCP servers are not supported by acp-port. Disable MCP forwarding for this agent in the editor.");
+        }
+        const session = await createSession(params.cwd, config, registry, options, signal);
+        sessions.set(session.id, session);
+        return {
+            sessionId: session.id,
+            configOptions: getSessionConfigOptions(session),
+        };
+    })
+        .onRequest("session/set_config_option", async ({ params, client }) => {
+        const session = getSession(params.sessionId);
+        if (params.configId !== "model" || typeof params.value !== "string") {
+            throw RequestError.invalidParams(undefined, "Only the model select option is supported.");
+        }
+        const configOptions = await updateSelectedModel(session, params.value, client);
+        return { configOptions };
+    })
+        // A small bridge for older editors; the current API is session/set_config_option.
+        .onRequest("session/set_model", z.object({ sessionId: z.string(), modelId: z.string() }), async ({ params, client }) => {
+        const session = getSession(params.sessionId);
+        await updateSelectedModel(session, params.modelId, client);
+        return {};
+    })
+        .onNotification("session/cancel", ({ params }) => {
+        sessions.get(params.sessionId)?.activeTurn?.abort();
+    })
+        .onRequest("session/prompt", async ({ params, client, signal }) => {
+        const session = getSession(params.sessionId);
+        return runSessionPrompt({
+            config,
+            registry,
+            session,
+            capabilities,
+            client,
+            signal,
+            prompt: params.prompt,
+        });
+    }));
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent/prompt-content.d.ts

@@ -0,0 +1,2 @@
+import { type ContentBlock } from "@agentclientprotocol/sdk";
+export declare function extractPromptText(blocks: ContentBlock[]): string;

package/dist/agent/prompt-content.js

@@ -0,0 +1,21 @@
+import { RequestError } from "@agentclientprotocol/sdk";
+export function extractPromptText(blocks) {
+    return blocks
+        .map((block) => {
+        switch (block.type) {
+            case "text":
+                return block.text;
+            case "resource":
+                if ("text" in block.resource) {
+                    return `Resource: ${block.resource.uri}\n${block.resource.text}`;
+                }
+                throw RequestError.invalidParams(undefined, "Binary resources are not supported. Attach text instead.");
+            case "resource_link":
+                return `Referenced resource: ${block.name}\nURI: ${block.uri}`;
+            default:
+                throw RequestError.invalidParams(undefined, `Unsupported prompt content: ${block.type}`);
+        }
+    })
+        .join("\n\n");
+}
+//# sourceMappingURL=prompt-content.js.map

package/dist/agent/prompt-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-content.js","sourceRoot":"","sources":["../../src/agent/prompt-content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE3E,MAAM,UAAU,iBAAiB,CAAC,MAAsB;IACtD,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,MAAM;gBACT,OAAO,KAAK,CAAC,IAAI,CAAC;YACpB,KAAK,UAAU;gBACb,IAAI,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;oBAC7B,OAAO,aAAa,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACnE,CAAC;gBACD,MAAM,YAAY,CAAC,aAAa,CAC9B,SAAS,EACT,0DAA0D,CAC3D,CAAC;YACJ,KAAK,eAAe;gBAClB,OAAO,wBAAwB,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,GAAG,EAAE,CAAC;YACjE;gBACE,MAAM,YAAY,CAAC,aAAa,CAC9B,SAAS,EACT,+BAA+B,KAAK,CAAC,IAAI,EAAE,CAC5C,CAAC;QACN,CAAC;IACH,CAAC,CAAC;SACD,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}

package/dist/agent/session.d.ts

@@ -0,0 +1,19 @@
+import { type SessionConfigOption } from "@agentclientprotocol/sdk";
+import type { Config } from "../config/schema.js";
+import type { Message } from "../providers/provider-contract.js";
+import type { ProviderRegistry, RegisteredModel } from "../providers/provider-registry.js";
+export interface AgentOptions {
+    provider?: string;
+    model?: string;
+}
+export interface AgentSession {
+    id: string;
+    workspaceDirectory: string;
+    modelCatalog: RegisteredModel[];
+    selectedModel: RegisteredModel;
+    history: Message[];
+    activeTurn?: AbortController;
+}
+export declare function createSession(workspaceDirectory: string, config: Config, registry: ProviderRegistry, options: AgentOptions, signal: AbortSignal): Promise<AgentSession>;
+export declare function getSessionConfigOptions(session: AgentSession): SessionConfigOption[];
+export declare function selectSessionModel(session: AgentSession, modelId: string): void;