diff --git a/.agents/README.md b/.agents/README.md index 90639ae..3621ec8 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -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). diff --git a/.agents/evidence/verify/2026-10-28-readme-audience-review.md b/.agents/evidence/verify/2026-10-28-readme-audience-review.md new file mode 100644 index 0000000..c69ce6e --- /dev/null +++ b/.agents/evidence/verify/2026-10-28-readme-audience-review.md @@ -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` | diff --git a/.agents/notes/proposed/process/2026-10-28-readme-audience-review.md b/.agents/notes/proposed/process/2026-10-28-readme-audience-review.md new file mode 100644 index 0000000..1a6d951 --- /dev/null +++ b/.agents/notes/proposed/process/2026-10-28-readme-audience-review.md @@ -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). diff --git a/README.md b/README.md index 5e42b18..051c971 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. diff --git a/README.zh-CN.md b/README.zh-CN.md index 071c297..ef66862 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,20 +1,14 @@ -# @agent-sandbox/sdk +# Agent Sandbox Node.js SDK **中文** | [English](README.md) -[Agent Sandbox](https://github.com/alibaba-agent-sandbox/python-sdk) 的 Node.js 客户端。需要 Node.js 20 或更高版本,仅提供 ESM。 +在 JavaScript 或 TypeScript 中调用沙箱应用服务。`@agent-sandbox/sdk` 提供用于执行命令和传输文件的 HTTP `ServerClient`,以及共享配置名查询工具。 -本包是 Node.js SDK 的**第一片**。它包含: - -- **配置名表**(每个 key 对应一个环境变量) -- `ServerClient`:面向 `agent-sandbox-server`(`agent_sandbox.server`)的**沙箱内 HTTP 客户端** - -它**不是** `Sandbox.create`、云 provider 或 server SDK 的移植。创建云沙箱仍属于 Python SDK 和 `abx` CLI。 +需要 Node.js 20+,仅支持 ESM。先用 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) 或 [Python SDK](https://github.com/Alibaba-Agent-Sandbox/python-sdk)创建沙箱并启动服务,再通过本包连接。 ## 安装 -2026-10-18 查询公开 npm 的 `@agent-sandbox/sdk` 元数据返回404。 -配置的包索引具备对应版本前,请从源码构建安装包: +从源码构建安装包: ```bash git clone https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk.git @@ -24,118 +18,65 @@ npm run build npm pack ``` -当前源码版本0.1.0 生成 `agent-sandbox-sdk-0.1.0.tgz`,包含构建后的 `dist/` 导出。 -在应用项目中安装生成的归档: +在应用项目中安装生成的 `agent-sandbox-sdk-0.1.0.tgz`,按实际位置调整路径: ```bash -npm install /absolute/path/to/agent-sandbox-sdk-0.1.0.tgz +npm install ../nodejs-sdk/agent-sandbox-sdk-0.1.0.tgz ``` -配置的包索引具备对应发布后,可以使用 `npm install @agent-sandbox/sdk`,导入接口一致。 -本说明不代表包已经发布。开发时 `npm test` 会构建并运行 `node:test`;真实本地示例 -需要按[示例说明](examples/README.md)先安装 Python 服务端。 - -## ServerClient +SDK 目前通过源码分发,公开 npm 包尚不可用。 -`ServerClient` 通过 HTTP 访问 `python3 -m agent_sandbox.server serve` 启动的进程(默认端口 9000)。本地 agent 循环用到的是下面四个调用,它们默认开启: - -| 方法 | 请求 | -| --- | --- | -| `health()` | `GET /health` | -| `process.shell(command)` | `POST /shell`,JSON `{ "command": "..." }` | -| `files.upload(path, data)` | `POST /files/upload-stream`,JSON `{ "path", "content_base64" }` | -| `files.download(path)` / `files.readText(path)` | `GET /files/download-stream?path=` | +## 快速开始 -只有在你设置了 `cwd`、`env`、`timeout` 时,它们才会出现在 shell 请求体里。服务端对 `command` 做分词,不会交给 shell。构造时传入的 bearer token 会以 `Authorization: Bearer` 发送(与 `ABX_SERVER_TOKEN` 是同一个密钥)。 - -可选能力组(`dev_tools`、`browser`、`agents`)默认关闭,只有 `ABX_SERVER_ENABLED_GROUPS` 列出它们时才打开。这是唯一的分组开关。Agents 路由的响应带 `X-Agent-Sandbox-*` 头(例如 `X-Agent-Sandbox-Local`)。本客户端不调用那些路由。 +准备一个已运行的 `agent-sandbox-server` 端点,启动方法见[本地示例](examples/README.md)。 ```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` 会启动这个本地服务,并执行与 Python 场景 `examples/scenarios/agent_loop_local.py` 相同的四步:健康检查、`python3 -c 'print(2 + 2)'`、写入并读回 `result.txt`、然后 `SIGTERM`。记录见 [examples/README.md](examples/README.md)。 - -## 网关与应用认证 - -通过提供方端口网关访问时,应传入包含完整代理前缀、沙箱和端口标识及查询参数 -的 URL。客户端保留原查询参数的字节,仅追加操作参数,禁止覆盖网关参数。 -所有重定向均会拒绝,包括同一域名下跳转到另一沙箱;URL 用户信息及越出绑定 -前缀的操作路径也会拒绝。URL 归一化之前即检查原始或多层编码的控制字符、 -路径分隔符与点路径;基址和操作都不能引入重复或多层编码后等价的网关查询键。 - -`token` 用于应用服务令牌,`gatewayHeaders` 用于平台网关请求头,`headers` -用于其他应用请求头。各组请求头名称不能重叠;已有 `Authorization` 请求头时 -不能再传入 `token`。不能覆盖 Host 等寻址及传输请求头。公开 `baseUrl` 和连接 -错误省略查询凭据。不要把平台控制面 API Key 作为应用令牌传入。本客户端使用 -绑定代理前缀的 HTTP URL;按操作签名的路径绑定需要使用提供方适配器的逐操作传输接口,不能传入本前缀客户端。 +`ABX_SERVER_TOKEN` 是该服务配置的应用认证令牌。连接提供方网关时,应使用完整服务地址及提供方的 `gatewayHeaders`,详见[认证与网关连接](docs/server-client.zh-CN.md)。应用令牌与提供方 API Key 分开使用。 -显式应用 `token` 还会通过 `X-Access-Token` 发送,前提是调用方提供的请求头未占用该名称(不区分大小写)。Bearer 仍然保留以兼容现有服务。每次请求复制调用方与网关请求头,不会覆盖它们;未提供 token 时不会添加应用凭据。该行为使用服务端已有认证请求头,兼容剥离 Authorization 的服务端代理。 +## 支持的操作 -## 配置名 - -此表导出配置名称;`readEnv` 只读取值,不会把这些字段自动应用到 `ServerClient`。已移除不生效的旧重试配置名称。 - -`src/config-keys.json` 是规范列表,来自 `python -m agent_sandbox.utils.config_keys --json`。每个 key 只有一个环境变量,没有别名。`readEnv` 只读这个名字。 - -`configSchema.reserved_provider_ids` 遵循 -[Python 注册表](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/145341d462df2f4753c03a62365114f1872acd1a/client-sdk/src/agent_sandbox/utils/config_keys.py): -内置及核心标识仍保留,可安装的目录提供方标识 `e2b` 不再保留。 -提供方执行由 Python SDK 和 `abx` 负责。 +| 方法 | 用途 | +| --- | --- | +| `health()` | 检查应用服务 | +| `process.shell(command, options)` | 执行进程并读取结果 | +| `files.upload(path, data)` | 上传字节 | +| `files.download(path)` / `files.readText(path)` | 下载字节或文本 | +| `close()` | 释放客户端 | -产品 key 使用 `ABX_` 前缀:`ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL`、`ABX_SANDBOX_DOMAIN`、`ABX_PROVIDER`。 +服务端会拆分命令参数,需要变量展开或管道时使用 `sh -c`。当前包不提供云端生命周期、解释器、PTY 或浏览器客户端。关闭 HTTP 客户端后沙箱仍在运行,应通过创建沙箱的工具将其删除。 -厂商已经公布名字时,环境变量就用那个名字:`ALICLOUD_ACCESS_KEY_ID`、`ALICLOUD_ACCESS_KEY_SECRET`、`ALIBABA_CLOUD_REGION_ID`,以及 `GITHUB_TOKEN`。 +## 配置工具 ```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 | 范围 | 环境变量 | 说明 | -| --- | --- | --- | --- | -| `provider` | core | `ABX_PROVIDER` | 默认 provider 标识(见 'abx provider list') | -| `sandbox_api_key` | core | `ABX_SANDBOX_API_KEY` | 当前 provider 的 Agent Sandbox API Key | -| `sandbox_base_url` | core | `ABX_SANDBOX_BASE_URL` | 当前 provider 的 Agent Sandbox API 端点 | -| `sandbox_domain` | core | `ABX_SANDBOX_DOMAIN` | envd 数据面域名 | -| `http_timeout` | core | `ABX_HTTP_TIMEOUT` | HTTP 请求超时(秒) | -| `http2` | core | `ABX_HTTP2` | 启用 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` | 日志级别 | -| `default_template` | core | `ABX_DEFAULT_TEMPLATE` | 未指定模板时使用的模板 | -| `github_token` | core | `GITHUB_TOKEN` | 用于模板索引的 GitHub Token | -| `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` | 地域(用于推导 API 地址和域名) | -| `access_key_id` | alicloud-express | `ALICLOUD_ACCESS_KEY_ID` | 阿里云 AccessKey ID | -| `access_key_secret` | alicloud-express | `ALICLOUD_ACCESS_KEY_SECRET` | 阿里云 AccessKey Secret | - -## 本包不做的事 - -- `Sandbox.create`、模板,或任何云控制面 -- provider 驱动(阿里云极速版只出现在环境变量名表里) -- 沙箱内的服务端本身(`agent-sandbox-server` 仍是 Python) -- PTY、浏览器、devtools,以及 Python `ServerClient` 的其余接口 - -## 许可 - -Apache-2.0。见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 - - -应用认证回归数据与 Python 客户端、CLI 共用同一份 Python SDK 契约来源。本库通过构造参数接收凭证,没有交互式配置命令。 +这些工具只查询配置名和读取值,不会配置 `ServerClient` 或执行提供方操作。完整表格见[配置参考](docs/configuration.zh-CN.md)。 + +## 开发 + +运行 `npm ci`、`npm run typecheck` 和 `npm test`,测试会先构建 SDK。本地 Agent 循环及其 Python 运行时前提见[示例](examples/README.md)。问题请提交到 [Issues](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/issues)。 + +## 许可证 + +[Apache-2.0](LICENSE),署名信息见 [NOTICE](NOTICE)。 diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..a1d6bc4 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,52 @@ +# Configuration name reference + +[中文](configuration.zh-CN.md) + +Back to the [README](../README.md). + +## 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`. + +Product keys use the `ABX_` prefix: `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL`, `ABX_SANDBOX_DOMAIN`, `ABX_PROVIDER`. + +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`. + +```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 | diff --git a/docs/configuration.zh-CN.md b/docs/configuration.zh-CN.md new file mode 100644 index 0000000..3b0e7e8 --- /dev/null +++ b/docs/configuration.zh-CN.md @@ -0,0 +1,52 @@ +# 配置名参考 + +[English](configuration.md) + +返回 [README](../README.zh-CN.md)。 + +## 配置名 + +此表导出配置名称;`readEnv` 只读取值,不会把这些字段自动应用到 `ServerClient`。已移除不生效的旧重试配置名称。 + +`src/config-keys.json` 是规范列表,来自 `python -m agent_sandbox.utils.config_keys --json`。每个 key 只有一个环境变量,没有别名。`readEnv` 只读这个名字。 + +`configSchema.reserved_provider_ids` 遵循 +[Python 注册表](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/145341d462df2f4753c03a62365114f1872acd1a/client-sdk/src/agent_sandbox/utils/config_keys.py): +内置及核心标识仍保留,可安装的目录提供方标识 `e2b` 不再保留。 +提供方执行由 Python SDK 和 `abx` 负责。 + +产品 key 使用 `ABX_` 前缀:`ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL`、`ABX_SANDBOX_DOMAIN`、`ABX_PROVIDER`。 + +厂商已经公布名字时,环境变量就用那个名字:`ALICLOUD_ACCESS_KEY_ID`、`ALICLOUD_ACCESS_KEY_SECRET`、`ALIBABA_CLOUD_REGION_ID`,以及 `GITHUB_TOKEN`。 + +```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 | 范围 | 环境变量 | 说明 | +| --- | --- | --- | --- | +| `provider` | core | `ABX_PROVIDER` | 默认 provider 标识(见 'abx provider list') | +| `sandbox_api_key` | core | `ABX_SANDBOX_API_KEY` | 当前 provider 的 Agent Sandbox API Key | +| `sandbox_base_url` | core | `ABX_SANDBOX_BASE_URL` | 当前 provider 的 Agent Sandbox API 端点 | +| `sandbox_domain` | core | `ABX_SANDBOX_DOMAIN` | envd 数据面域名 | +| `http_timeout` | core | `ABX_HTTP_TIMEOUT` | HTTP 请求超时(秒) | +| `http2` | core | `ABX_HTTP2` | 启用 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` | 日志级别 | +| `default_template` | core | `ABX_DEFAULT_TEMPLATE` | 未指定模板时使用的模板 | +| `github_token` | core | `GITHUB_TOKEN` | 用于模板索引的 GitHub Token | +| `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` | 地域(用于推导 API 地址和域名) | +| `access_key_id` | alicloud-express | `ALICLOUD_ACCESS_KEY_ID` | 阿里云 AccessKey ID | +| `access_key_secret` | alicloud-express | `ALICLOUD_ACCESS_KEY_SECRET` | 阿里云 AccessKey Secret | diff --git a/docs/server-client.md b/docs/server-client.md new file mode 100644 index 0000000..7c07096 --- /dev/null +++ b/docs/server-client.md @@ -0,0 +1,55 @@ +# HTTP client reference + +[中文](server-client.zh-CN.md) + +Back to the [README](../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: + +| 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`). + +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. + +```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" +} +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. + +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. + +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. diff --git a/docs/server-client.zh-CN.md b/docs/server-client.zh-CN.md new file mode 100644 index 0000000..9b6c292 --- /dev/null +++ b/docs/server-client.zh-CN.md @@ -0,0 +1,49 @@ +# HTTP 客户端参考 + +[English](server-client.md) + +返回 [README](../README.zh-CN.md)。 + +## ServerClient + +`ServerClient` 通过 HTTP 访问 `python3 -m agent_sandbox.server serve` 启动的进程(默认端口 9000)。本地 agent 循环用到的是下面四个调用,它们默认开启: + +| 方法 | 请求 | +| --- | --- | +| `health()` | `GET /health` | +| `process.shell(command)` | `POST /shell`,JSON `{ "command": "..." }` | +| `files.upload(path, data)` | `POST /files/upload-stream`,JSON `{ "path", "content_base64" }` | +| `files.download(path)` / `files.readText(path)` | `GET /files/download-stream?path=` | + +只有在你设置了 `cwd`、`env`、`timeout` 时,它们才会出现在 shell 请求体里。服务端对 `command` 做分词,不会交给 shell。构造时传入的 bearer token 会以 `Authorization: Bearer` 发送(与 `ABX_SERVER_TOKEN` 是同一个密钥)。 + +可选能力组(`dev_tools`、`browser`、`agents`)默认关闭,只有 `ABX_SERVER_ENABLED_GROUPS` 列出它们时才打开。这是唯一的分组开关。Agents 路由的响应带 `X-Agent-Sandbox-*` 头(例如 `X-Agent-Sandbox-Local`)。本客户端不调用那些路由。 + +```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" +} +await server.close(); +``` + +`examples/agent-loop.mjs` 会启动这个本地服务,并执行与 Python 场景 `examples/scenarios/agent_loop_local.py` 相同的四步:健康检查、`python3 -c 'print(2 + 2)'`、写入并读回 `result.txt`、然后 `SIGTERM`。记录见 [examples/README.md](../examples/README.md)。 + +## 网关与应用认证 + +通过提供方端口网关访问时,应传入包含完整代理前缀、沙箱和端口标识及查询参数 +的 URL。客户端保留原查询参数的字节,仅追加操作参数,禁止覆盖网关参数。 +所有重定向均会拒绝,包括同一域名下跳转到另一沙箱;URL 用户信息及越出绑定 +前缀的操作路径也会拒绝。URL 归一化之前即检查原始或多层编码的控制字符、 +路径分隔符与点路径;基址和操作都不能引入重复或多层编码后等价的网关查询键。 + +`token` 用于应用服务令牌,`gatewayHeaders` 用于平台网关请求头,`headers` +用于其他应用请求头。各组请求头名称不能重叠;已有 `Authorization` 请求头时 +不能再传入 `token`。不能覆盖 Host 等寻址及传输请求头。公开 `baseUrl` 和连接 +错误省略查询凭据。不要把平台控制面 API Key 作为应用令牌传入。本客户端使用 +绑定代理前缀的 HTTP URL;按操作签名的路径绑定需要使用提供方适配器的逐操作传输接口,不能传入本前缀客户端。 + +显式应用 `token` 还会通过 `X-Access-Token` 发送,前提是调用方提供的请求头未占用该名称(不区分大小写)。Bearer 仍然保留以兼容现有服务。每次请求复制调用方与网关请求头,不会覆盖它们;未提供 token 时不会添加应用凭据。该行为使用服务端已有认证请求头,兼容剥离 Authorization 的服务端代理。