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
@@ -1,5 +1,7 @@
# Node SDK engineering records

- [Application command invocation](notes/implemented/feature/2026-11-05-application-command-invocation.md) · [verification](evidence/verify/2026-11-05-application-command-invocation.md).

## Current delivery — 2026-10-25

- Source package version: **0.1.0**. [Source installation](../README.md#install) builds and packs the SDK. The recorded delivery is source merge, not npm publication.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Verification: Application command invocation

- Date: 2026-11-05
- Change: application-command-invocation; owner Issue https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/issues/23
- Result: PASS for application HTTP scope; latest-head delivery checks remain required
- Baseline: 1505b61a10a819c299c25f31ba508af2d8cb4ba6
- Environment: Node 22.22.2, Python 3.11.15, matching local Python client/server source. No cloud credentials are required or passed to these tests.

## What was verified

Registered application commands preserve typed JSON arguments and separate request timeouts. Requests retain the bound proxy prefix, signed query and distinct application/traffic headers. The actual local Python runtime discovers and executes a registered function with business fields named timeout, name, arguments, server_port and requestTimeout, and returns expected validation/not-found errors.

## Commands run

`npm run build && node --test --test-name-pattern='named application commands' test/server-client.test.mjs` first failed all three new behavior tests because the API was absent. After implementation all three passed.

`npm ci --ignore-scripts --no-audit --no-fund`, `npm run typecheck`, `node examples/agent-loop.mjs` and `npm pack --dry-run` passed. `npm test`, with the matched Python environment on the child process PATH, passed all 36 tests, including the real registered-command service and both existing agent-loop tests. An intermediate configuration test failed because its old expected key count was 21; the synchronized schema adds security_token as key 22, and the complete canonical-name and secret-key checks now pass.

A further observable regression first failed when a response sent headers but delayed its JSON body: timeout escaped as DOMException instead of ConnectionError, and controllers were released too early to support client-close cancellation during body reads. The request lifetime now includes body consumption. Timeout, close, server errors and no-replay checks pass in the full run.

## Independent review

A separate SDK reviewer inspected the complete diff and reran all 36 tests successfully. The reviewer found fractional request seconds could reach AbortSignal.timeout as a non-integer and throw RangeError before cleanup. Timeout conversion now rounds up to whole milliseconds, rejects unsupported timer ranges before I/O, and constructs cancellation signals inside the controller lifetime. A fractional 0.0105-second regression and an oversized-value rejection pass in the complete 36-test run. No remaining blocking issue was found in metadata, URL/query binding, argument separation or authentication.

## Cleanup

The registered-command Python process exited on SIGTERM; its temporary source/data directory was removed. Existing agent-loop fixtures also cleaned up. No cloud resource was created.

## Not verified

The initial implementation head 0b0367e34b03fffdc672e20adb5125bab757e3e6 passed the complete Node20/22 matrix in [run 41992843654](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/actions/runs/41992843654). CI now pins the companion reviewed product commit 653404d4eb1e61c490816e1c8f7b688664b146e1, which includes the shared configuration export; that contract must land before this consumer merges. Independent review is complete. The final follow-up head must pass its own remote checks. This does not certify cloud lifecycle or npm publication.

## Real private application acceptance

The candidate was also exercised against an owned Express sandbox hosting a registered function on an exclusive port. Node command discovery and invocation passed with separate public-gateway and application credentials; conflicting business argument names were preserved. The independent Python/direct-HTTP controls passed and anonymous public traffic returned HTTP403. Deletion was confirmed independently with GET404 and zero owned resources remaining.

An earlier Node controller failed TLS trust with UNABLE_TO_VERIFY_LEAF_SIGNATURE because its minimal child environment dropped already-configured NODE_EXTRA_CA_CERTS/SSL_CERT_FILE. Raw fetch reproduced the same failure. Preserving only the existing trust configuration fixed the controller; certificate verification was never disabled. A separate early object-order comparison was replaced with deep value equality. These controller failures remain distinct from product behavior.
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Decision: Invoke registered application commands with separate arguments

Status: implemented

## Problem

The application HTTP client supports shell and file operations but omits the server's registered function API. Mixing function arguments with request options would reserve normal business names such as timeout. The current shared configuration export also lacks the STS session-token key being added by its Python owner.

## Decision

Add ServerCommandsApi to ServerClient with explicit list and invoke methods. Reuse the existing bound HTTP transport, separate gateway/application authentication, redirect refusal and non-replayed mutation behavior. Preserve the package's application HTTP scope. Import the updated configuration export without aliases or an independent configuration registry.

## API Design

`commands.list(): Promise<ServerCommand[]>` reads GET /commands. `commands.invoke<T>(name, arguments, { requestTimeout }): Promise<T>` sends the argument object to POST /commands/{name}; HTTP timeout is in seconds and is never added to the business object. Metadata types and ServerCommandsApi are public exports. Runtime protocol validation checks metadata and the result envelope, while callers validate their own business result type.

## Alternatives considered

- Merge transport fields into business arguments: rejected because names collide.
- Add a Node cloud lifecycle SDK: rejected because it exceeds this package's existing scope and duplicates provider mappings.
- Call arbitrary paths or follow redirects: rejected because it breaks the authenticated endpoint binding.

## Dependencies

The existing Python server command protocol and its Python-owned configuration schema. Companion contract: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/152 . Owner issue: https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/issues/23 .

## Test Strategy

Regression-first HTTP tests cover typed arguments, gateway binding, status preservation, no mutation replay and malformed responses. A real local Python server registers a function with conflicting business names and verifies discovery, invocation and rejected calls. Run typecheck, the complete Node suite, the example and package checks; compare the whole configuration schema against the exact companion source commit in CI.

## Acceptance criteria

- Conflicting business argument names are preserved unchanged.
- Existing authentication and bound endpoint protections remain effective.
- Real registered function invocation and the existing local example pass.
- Full required local/remote checks and independent review pass before merge.
- English/Chinese usage, public exports, shared configuration and evidence are consistent.

## Evidence

- [Verification](../../../evidence/verify/2026-11-05-application-command-invocation.md).
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
- uses: actions/checkout@v4
with:
repository: Alibaba-Agent-Sandbox/python-sdk
ref: 98642ae6712a5017e187cae7952a2b3c819c1ece
ref: 653404d4eb1e61c490816e1c8f7b688664b146e1
path: vendor/python-sdk
persist-credentials: false
- name: Verify shared application authentication vectors
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@

### Fixed

- Keep request timeout and client-close cancellation active while reading an application response body. / 读取应用响应体期间继续执行超时和客户端关闭取消。

- Reject control characters before URL normalization and recursively encoded namespace escapes/query-key collisions before an authenticated request can reach another sandbox.

- Preserve sandbox proxy prefixes and signed query bytes; reject redirects, URL userinfo, escaping paths and credential/header collisions. Separate gateway headers from the application token and omit signed query credentials from diagnostics.
Expand All @@ -35,5 +37,8 @@

### Added

- Discover and invoke registered application commands with separate business arguments and HTTP request options. / 支持发现和调用已注册应用命令,业务参数与 HTTP 请求选项分开。
- Export the shared `security_token` configuration name (`ALIBABA_CLOUD_SECURITY_TOKEN`) for STS credentials. / 导出 STS 凭据的共享配置名 `security_token`。

- A PR CI matrix for Node.js 20/22, including the existing real local server loop
against a pinned Python server source. No publication workflow is added.
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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

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.
Call sandbox application services from JavaScript or TypeScript. `@agent-sandbox/sdk` provides an HTTP `ServerClient` for running shell commands, invoking registered application functions and transferring files, plus shared configuration-name helpers.

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.

Expand Down Expand Up @@ -56,11 +56,15 @@ try {
| --- | --- |
| `health()` | Check the application service |
| `process.shell(command, options)` | Execute a process and read its result |
| `commands.list()` | Discover registered application commands |
| `commands.invoke(name, arguments, options)` | Invoke an application command with JSON arguments |
| `files.upload(path, data)` | Upload bytes |
| `files.download(path)` / `files.readText(path)` | Download bytes or text |
| `close()` | Release the client |

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.
Shell commands are tokenized by the server; use `sh -c` when shell expansion or pipes are needed. Registered application commands require a service that has loaded those functions. Their JSON arguments stay separate from request options, so a business field named `timeout` is preserved: `server.commands.invoke("job", { timeout: 5 }, { requestTimeout: 30 })`. See the [HTTP client reference](docs/server-client.md).

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.

## Configuration helpers

Expand Down
8 changes: 6 additions & 2 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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

在 JavaScript 或 TypeScript 中调用沙箱应用服务。`@agent-sandbox/sdk` 提供用于执行命令和传输文件的 HTTP `ServerClient`,以及共享配置名查询工具。
在 JavaScript 或 TypeScript 中调用沙箱应用服务。`@agent-sandbox/sdk` 提供用于执行 Shell 命令、调用已注册应用函数和传输文件的 HTTP `ServerClient`,以及共享配置名查询工具。

需要 Node.js 20+,仅支持 ESM。先用 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) 或 [Python SDK](https://github.com/Alibaba-Agent-Sandbox/python-sdk)创建沙箱并启动服务,再通过本包连接。

Expand Down Expand Up @@ -56,11 +56,15 @@ try {
| --- | --- |
| `health()` | 检查应用服务 |
| `process.shell(command, options)` | 执行进程并读取结果 |
| `commands.list()` | 查询已注册应用命令 |
| `commands.invoke(name, arguments, options)` | 以 JSON 参数调用应用命令 |
| `files.upload(path, data)` | 上传字节 |
| `files.download(path)` / `files.readText(path)` | 下载字节或文本 |
| `close()` | 释放客户端 |

服务端会拆分命令参数,需要变量展开或管道时使用 `sh -c`。当前包不提供云端生命周期、解释器、PTY 或浏览器客户端。关闭 HTTP 客户端后沙箱仍在运行,应通过创建沙箱的工具将其删除。
服务端会拆分 Shell 命令参数,需要变量展开或管道时使用 `sh -c`。调用应用命令前,服务必须已加载对应函数。业务 JSON 参数与请求选项分开,因此名为 `timeout` 的业务字段也能完整传递:`server.commands.invoke("job", { timeout: 5 }, { requestTimeout: 30 })`。详见 [HTTP 客户端参考](docs/server-client.zh-CN.md)。

当前包不提供云端生命周期、解释器、PTY 或浏览器客户端。关闭 HTTP 客户端后沙箱仍在运行,应通过创建沙箱的工具将其删除。

## 配置工具

Expand Down
5 changes: 3 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ The table exports configuration names. `readEnv` only reads a value; it does not
`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):
[Python registry](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/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`.
Where the vendor already publishes a name, that name is the environment variable: `ALICLOUD_ACCESS_KEY_ID`, `ALICLOUD_ACCESS_KEY_SECRET`, `ALIBABA_CLOUD_SECURITY_TOKEN`, `ALIBABA_CLOUD_REGION_ID`, and `GITHUB_TOKEN`.

```js
import { envName, readEnv } from "@agent-sandbox/sdk";
Expand Down Expand Up @@ -50,3 +50,4 @@ readEnv("sandbox_api_key", process.env);
| `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 |
| `security_token` | alicloud-express | `ALIBABA_CLOUD_SECURITY_TOKEN` | STS session token used with temporary AccessKey credentials |
5 changes: 3 additions & 2 deletions docs/configuration.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@
`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):
[Python 注册表](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/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`。
厂商已经公布名字时,环境变量就用那个名字:`ALICLOUD_ACCESS_KEY_ID`、`ALICLOUD_ACCESS_KEY_SECRET`、`ALIBABA_CLOUD_SECURITY_TOKEN`、`ALIBABA_CLOUD_REGION_ID`,以及 `GITHUB_TOKEN`。

```js
import { envName, readEnv } from "@agent-sandbox/sdk";
Expand Down Expand Up @@ -50,3 +50,4 @@ readEnv("sandbox_api_key", process.env);
| `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 |
| `security_token` | alicloud-express | `ALIBABA_CLOUD_SECURITY_TOKEN` | 与临时 AccessKey 配套使用的 STS 会话令牌 |
Loading
Loading