Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,5 @@ state. A local/runtime result is not cloud acceptance or package publication.
- [Coordinated public runtime a6](notes/proposed/process/2026-10-25-public-runtime-a6.md) · [verification](evidence/verify/2026-10-25-public-runtime-a6.md).

- [Shared application authentication tests](notes/proposed/feature/2026-10-26-shared-application-auth-tests.md) · [verification](evidence/verify/2026-10-26-shared-application-auth-tests.md).

- [README audience review](notes/proposed/process/2026-10-28-readme-audience-review.md) · [verification](evidence/verify/2026-10-28-readme-audience-review.md).
41 changes: 41 additions & 0 deletions .agents/evidence/verify/2026-10-28-readme-audience-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Verification: nodejs-sdk README audience review

- Date: 2026-10-28
- Result: PASS — scoped local documentation verification. Remote checks and merge are reported separately on the PR.
- Base revision: `129e3d6e0629637f95abafaff1f146d741ba4d46`.
- Scope: `README.md`, `README.zh-CN.md`, `docs/configuration.md`, `docs/configuration.zh-CN.md`, `docs/server-client.md`, `docs/server-client.zh-CN.md`; repository-owned note and this evidence.
- Environment: Linux, Node.js 22.22.2, system Python 3.13.13; SDK/server and checker environment Python 3.11.15.

## What was reviewed

The opening called the SDK a first slice, repeated exclusions and described transport requests before a useful example. A full configuration table and long gateway-validation narrative dominated the README; dated publication checks appeared as installation prose.

Describe the HTTP client scope and actual source installation. Provide one complete service example and an operation table. Keep application-versus-gateway authentication and sandbox cleanup visible. Move complete HTTP/authentication and configuration tables into bilingual docs/server-client and docs/configuration references without changing their contract.

## Validation

`python "$README_AUDIT"` passed for 9 changed Markdown files, with zero failures. This temporary audit used the existing template repository's Markdown-target/heading parser at its checked-out base revision and a task wrapper (SHA-256 `fe8c34fd4ef2474ca7dfcfcc94d2a055e9ead01a92fe2695446cfe08341df7e6`). It checks changed local targets/fragments, incoming active README heading links, one H1 and reciprocal language links in each root README, balanced fences and Python snippet syntax. `README_AUDIT` denotes that temporary wrapper; no machine-local path is part of the repository. It does not validate cloud runtime behavior.

`git -c core.filemode=false diff --check HEAD` passed. The filesystem exposes executable bits on unchanged checkout files; ignoring those bits for task-local Git commands avoided including unrelated mode changes. The staged change was reviewed for prose-only scope, translation equivalence, current command/API names and preserved license links. Package registry checks on 2026-10-28 found CLI 0.5.8 and Python client 0.4.0a6; the Node SDK public npm metadata endpoint returned HTTP 404. No new package publication is claimed.

## Limits and cleanup

Documentation changes only. No provider API calls, sandboxes, templates, cloud keys, model calls, deployments or package releases were created by local verification. Existing historical receipts remain unchanged. CI and existing main-branch publication workflows retain their own scope.

## Repository checks

- `npm ci`: PASS.
- `npm run typecheck`: PASS.
- `npm test`: FAIL initially: the selected system Python did not have agent-sandbox-server installed; two agent-loop tests failed with ModuleNotFoundError, 27 passed.
- `npm test (PATH selects the fresh SDK/server Python environment)`: PASS: 29 tests, 0 failures.

## Reviewed public-file identity

| File | SHA-256 |
| --- | --- |
| `README.md` | `c5304f6b61386eccf92a80c7c22d230b35703af0fa2835e46fade0628edf7789` |
| `README.zh-CN.md` | `c9171a4acfecb3a9f5396c4d3337cc2466906764ba8a0720d7cdcdf525f41c76` |
| `docs/configuration.md` | `07641c746f73d1e76847241bb60937047436d7c0cb1c01e7a9333316fd43c7f0` |
| `docs/configuration.zh-CN.md` | `afedef81ae470fdef04dc92f3edb04ab129561dd15a1b50b54c8cb5dae270a4b` |
| `docs/server-client.md` | `ce82809b5490106ae3109f109d5fe59d278357e27660de90ede280c44e30258d` |
| `docs/server-client.zh-CN.md` | `fbcba6e84b66947238986f887a5d9b962b9a452035172061b1e60d7464d2f772` |
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Decision: Make the nodejs-sdk README a reader entry point

Status: proposed

## Problem

The opening called the SDK a first slice, repeated exclusions and described transport requests before a useful example. A full configuration table and long gateway-validation narrative dominated the README; dated publication checks appeared as installation prose.

## Decision

Describe the HTTP client scope and actual source installation. Provide one complete service example and an operation table. Keep application-versus-gateway authentication and sandbox cleanup visible. Move complete HTTP/authentication and configuration tables into bilingual docs/server-client and docs/configuration references without changing their contract.

A README answers what this repository provides, who it serves, how to start, where to continue, how to contribute and what license applies where established. Detailed migration is a secondary guide, not the project introduction. Public usage stays separate from engineering acceptance and delivery history.

Scoped public files: `README.md`, `README.zh-CN.md`, `docs/configuration.md`, `docs/configuration.zh-CN.md`, `docs/server-client.md`, `docs/server-client.zh-CN.md`.

## API Design

N/A — this decision does not involve API changes. All executable behavior and public exports remain unchanged.

## Alternatives considered

- Only remove the migration heading: leaves each repository's audience and navigation problems unresolved.
- Use one identical README template everywhere: obscures the different needs of library users, catalog users, site contributors and article authors.
- Delete detailed material: useful reference and maintainer instructions should remain available through their owning guides and historical records.

## Dependencies

Existing guides, actual package/source metadata and the owning repositories linked with absolute GitHub URLs. No new runtime dependencies, release, build contract or cloud permissions.

## Test Strategy

Check changed Markdown links and anchors, incoming active links to root README headings, reciprocal language links, fenced Python syntax and the final scoped diff. Run repository documentation/record checks and applicable CI. Review examples against current source and package availability. No cloud mutation or real-model run is needed to validate this prose-only change; document checks do not establish runtime acceptance.

## Acceptance criteria

- The first screen identifies this repository's purpose and primary next action.
- Installation and examples match actual package scope and current source behavior.
- English and Chinese READMEs provide equivalent tasks and links.
- Migration, internal implementation and dated acceptance reports do not dominate the introduction.
- Detailed reference and maintainer material remains reachable.
- Local documentation checks and current-head required CI/review results are recorded honestly.

## Evidence

[Verification](../../../evidence/verify/2026-10-28-readme-audience-review.md).
140 changes: 37 additions & 103 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,14 @@
# @agent-sandbox/sdk
# Agent Sandbox Node.js SDK

**English** | [中文](README.zh-CN.md)

Node.js client for [Agent Sandbox](https://github.com/alibaba-agent-sandbox/python-sdk). Node.js 20 or newer. ESM only.
Call sandbox application services from JavaScript or TypeScript. `@agent-sandbox/sdk` provides an HTTP `ServerClient` for running shell commands and transferring files, plus shared configuration-name helpers.

This package is the **first slice** of the Node.js SDK. It contains:

- the **configuration-name table** (one environment variable per key)
- `ServerClient`, an **in-sandbox HTTP client** for `agent-sandbox-server` (`agent_sandbox.server`)

It is **not** a port of `Sandbox.create`, cloud providers, or the server SDK. Creating a cloud sandbox still belongs to the Python SDK and the `abx` CLI.
Requires Node.js 20+ and ESM. Create the sandbox and start its service with the [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) or [Python SDK](https://github.com/Alibaba-Agent-Sandbox/python-sdk); this package connects to that running service.

## Install

On 2026-10-18 the public npm metadata endpoint for `@agent-sandbox/sdk` returned 404.
Build the source package until the matching release is available on your registry:
Build the package from source:

```bash
git clone https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk.git
Expand All @@ -24,125 +18,65 @@ npm run build
npm pack
```

This checkout's version 0.1.0 produces `agent-sandbox-sdk-0.1.0.tgz` with built
`dist/` exports. In your application, install that generated archive:
In your application, install the generated `agent-sandbox-sdk-0.1.0.tgz` archive, using its actual path:

```bash
npm install /absolute/path/to/agent-sandbox-sdk-0.1.0.tgz
npm install ../nodejs-sdk/agent-sandbox-sdk-0.1.0.tgz
```

When the release exists on your configured registry, `npm install @agent-sandbox/sdk`
uses the same import surface. No publication is implied by this source recipe.
For local development, `npm test` builds and runs `node:test`; the real local
example needs the Python server installed as described in [examples](examples/README.md).

## ServerClient

`ServerClient` speaks HTTP to a server started with `python3 -m agent_sandbox.server serve` (default port 9000). These four calls are the ones the local agent loop uses. They are enabled by default:
The SDK is currently distributed from source; the public npm package is not available.

| Method | Request |
| --- | --- |
| `health()` | `GET /health` |
| `process.shell(command)` | `POST /shell` with JSON `{ "command": "..." }` |
| `files.upload(path, data)` | `POST /files/upload-stream` with JSON `{ "path", "content_base64" }` |
| `files.download(path)` / `files.readText(path)` | `GET /files/download-stream?path=` |

`cwd`, `env`, and `timeout` are added to the shell body only when you set them. The server tokenises `command`; it does not run a shell. A bearer token, when passed to the constructor, is sent as `Authorization: Bearer` (the same secret as `ABX_SERVER_TOKEN`).
## Quick start

Opt-in capability groups (`dev_tools`, `browser`, `agents`) stay off unless `ABX_SERVER_ENABLED_GROUPS` lists them. That variable is the only group switch. Agents routes answer with `X-Agent-Sandbox-*` headers (for example `X-Agent-Sandbox-Local`). This client does not call those routes.
Use a running `agent-sandbox-server` endpoint. The [local example](examples/README.md) explains how to start one.

```js
import { ServerClient } from "@agent-sandbox/sdk";

const server = new ServerClient("http://127.0.0.1:9000");
if (await server.health()) {
const ran = await server.process.shell("python3 -c 'print(2 + 2)'");
console.log(ran.stdout); // "4\n"
const server = new ServerClient("http://127.0.0.1:9000", {
token: process.env.ABX_SERVER_TOKEN,
});
try {
if (await server.health()) {
const result = await server.process.shell("python3 -c 'print(2 + 2)'");
console.log(result.stdout);
await server.files.upload("/tmp/result.txt", Buffer.from(result.stdout));
console.log(await server.files.readText("/tmp/result.txt"));
}
} finally {
await server.close();
}
await server.close();
```

`examples/agent-loop.mjs` starts that local server and runs the same four steps as the Python scenario `examples/scenarios/agent_loop_local.py`: health, `python3 -c 'print(2 + 2)'`, write and read `result.txt`, then `SIGTERM`. The recorded run is in [examples/README.md](examples/README.md).

## Gateway and application authentication

For a provider port gateway, pass the exact sandbox/port URL including its proxy
prefix and query. The client preserves existing query bytes and appends operation
parameters without replacing gateway parameters. All redirects are rejected,
including redirects to another sandbox on the same origin. URL userinfo and
request paths that escape the bound prefix are rejected. Raw or recursively
encoded control characters, path separators and dot traversal are validated
before URL normalization. Duplicate or recursively equivalent gateway query
keys cannot be introduced by the base URL or an operation.
`ABX_SERVER_TOKEN` is the application token configured for that service. For provider gateways, pass the exact service URL and the provider's `gatewayHeaders`; see [authentication and gateway connections](docs/server-client.md). Keep the application token separate from the provider API key.

Use `token` for the application service token and `gatewayHeaders` for the
provider gateway's headers. `headers` contains other application headers. Header
names must not overlap between groups; an existing `Authorization` header cannot
be combined with `token`. Authority and transport headers cannot be overridden.
The public `baseUrl` and connection errors omit query credentials. Never pass a
provider control-plane API key as the application token. This client accepts
prefix-bound HTTP URLs; operation-specific signed path bindings must use the provider
adapter's operation transport. This prefix client does not accept those bindings.
## Supported operations

The explicit application `token` is also sent as `X-Access-Token` when no supplied header already occupies that name, case-insensitively. Bearer is retained for existing services. Caller and gateway headers are copied for each request and never overwritten; requests without a token gain no application credentials. This supports server proxies that strip Authorization using the server's existing authentication header.

## Configuration names

The table exports configuration names. `readEnv` only reads a value; it does not apply these fields to `ServerClient`. Retired retry settings are not exported.

`src/config-keys.json` is the canonical list, exported from `python -m agent_sandbox.utils.config_keys --json`. Each key has exactly one environment variable. There are no aliases. `readEnv` reads only that name.

`configSchema.reserved_provider_ids` follows the
[Python registry](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/145341d462df2f4753c03a62365114f1872acd1a/client-sdk/src/agent_sandbox/utils/config_keys.py):
built-in/core identifiers stay reserved, while the installable catalog id `e2b`
is available. Provider execution belongs to the Python SDK and `abx`.
| Method | Purpose |
| --- | --- |
| `health()` | Check the application service |
| `process.shell(command, options)` | Execute a process and read its result |
| `files.upload(path, data)` | Upload bytes |
| `files.download(path)` / `files.readText(path)` | Download bytes or text |
| `close()` | Release the client |

Product keys use the `ABX_` prefix: `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL`, `ABX_SANDBOX_DOMAIN`, `ABX_PROVIDER`.
Commands are tokenized by the server; use `sh -c` when shell expansion or pipes are needed. Cloud lifecycle, interpreter, PTY and browser clients are outside this package's current scope. Closing the HTTP client leaves the sandbox running; delete the sandbox through the tool that created it.

Where the vendor already publishes a name, that name is the environment variable: `ALICLOUD_ACCESS_KEY_ID`, `ALICLOUD_ACCESS_KEY_SECRET`, `ALIBABA_CLOUD_REGION_ID`, and `GITHUB_TOKEN`.
## Configuration helpers

```js
import { envName, readEnv } from "@agent-sandbox/sdk";

envName("sandbox_api_key"); // ABX_SANDBOX_API_KEY
envName("access_key_id", "alicloud-express"); // ALICLOUD_ACCESS_KEY_ID
readEnv("sandbox_api_key", process.env);
```

| Key | Scope | Environment variable | Description |
| --- | --- | --- | --- |
| `provider` | core | `ABX_PROVIDER` | Default provider id (see 'abx provider list') |
| `sandbox_api_key` | core | `ABX_SANDBOX_API_KEY` | Agent Sandbox API key of the active provider |
| `sandbox_base_url` | core | `ABX_SANDBOX_BASE_URL` | Agent Sandbox API endpoint of the active provider |
| `sandbox_domain` | core | `ABX_SANDBOX_DOMAIN` | Envd data-plane domain |
| `http_timeout` | core | `ABX_HTTP_TIMEOUT` | HTTP request timeout in seconds |
| `http2` | core | `ABX_HTTP2` | Use HTTP/2 |
| `max_connections` | core | `ABX_MAX_CONNECTIONS` | |
| `max_keepalive_connections` | core | `ABX_MAX_KEEPALIVE_CONNECTIONS` | |
| `keepalive_expiry` | core | `ABX_KEEPALIVE_EXPIRY` | |
| `ws_ping_interval` | core | `ABX_WS_PING_INTERVAL` | |
| `log_level` | core | `ABX_LOG_LEVEL` | Log level |
| `default_template` | core | `ABX_DEFAULT_TEMPLATE` | Template used when none is given |
| `github_token` | core | `GITHUB_TOKEN` | GitHub token for the template index |
| `template_index_url` | core | `ABX_TEMPLATE_INDEX_URL` | |
| `template_dir` | core | `ABX_TEMPLATE_DIR` | |
| `mcp_auth_token` | core | `ABX_MCP_AUTH_TOKEN` | |
| `mcp_allowed_origins` | core | `ABX_MCP_ALLOWED_ORIGINS` | |
| `mcp_runtime_dir` | core | `ABX_MCP_RUNTIME_DIR` | |
| `region` | alicloud-express | `ALIBABA_CLOUD_REGION_ID` | Region id (derives the API URL and domain) |
| `access_key_id` | alicloud-express | `ALICLOUD_ACCESS_KEY_ID` | Alibaba Cloud AccessKey ID |
| `access_key_secret` | alicloud-express | `ALICLOUD_ACCESS_KEY_SECRET` | Alibaba Cloud AccessKey secret |

## What this package does not do

- `Sandbox.create`, templates, or any cloud control plane
- provider drivers (including Alibaba Cloud Express beyond the env-name table)
- the in-sandbox server itself (`agent-sandbox-server` remains Python)
- PTY, browser, devtools, or the rest of the Python `ServerClient` surface
These helpers look up names and values; they do not configure `ServerClient` or execute provider operations. See the [configuration reference](docs/configuration.md) for the complete table.

## License
## Development

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
Run `npm ci`, `npm run typecheck` and `npm test`. The tests build the SDK first. See [examples](examples/README.md) for the local agent loop and its Python runtime prerequisite. Report problems in [Issues](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/issues).

## License

The application authentication regression cases are shared with the Python client and CLI from the Python SDK contract source. This library takes credentials through constructor options; it has no interactive setup command.
[Apache-2.0](LICENSE). See [NOTICE](NOTICE) for attribution.
Loading
Loading