From bb37b11ec0ecbb646f5c6ba22d7acf684f214989 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sat, 24 Oct 2026 19:54:24 +0000 Subject: [PATCH] docs: synchronize current usage and engineering records --- .agents/README.md | 19 ++++++-- .../2026-10-24-current-docs-and-records.md | 24 ++++++++++ .../2026-10-23-bound-http-client.md | 6 ++- ...2026-10-18-config-provider-reservations.md | 6 ++- ...2026-10-18-portable-source-installation.md | 6 ++- .../2026-10-24-current-docs-and-records.md | 26 ++++++++++ README.md | 48 +++++++++---------- README.zh-CN.md | 32 ++++++------- examples/README.md | 4 +- 9 files changed, 123 insertions(+), 48 deletions(-) create mode 100644 .agents/evidence/verify/2026-10-24-current-docs-and-records.md rename .agents/notes/{proposed => implemented}/architecture/2026-10-23-bound-http-client.md (86%) rename .agents/notes/{proposed => implemented}/process/2026-10-18-config-provider-reservations.md (86%) rename .agents/notes/{proposed => implemented}/process/2026-10-18-portable-source-installation.md (83%) create mode 100644 .agents/notes/implemented/process/2026-10-24-current-docs-and-records.md diff --git a/.agents/README.md b/.agents/README.md index 110b212..6965b59 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -1,5 +1,18 @@ # Node SDK engineering records +## Current delivery — 2026-10-24 + +- 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. +- Scope: application HTTP `ServerClient` and configuration-name exports. No cloud lifecycle, template build, provider engine, PTY or interpreter client is exported. +- [Bound HTTP endpoint acceptance](evidence/verify/2026-10-23-bound-http-control-review.md) and [proxy-token acceptance](evidence/verify/2026-10-24-proxy-application-token.md) cover copied headers, preserved gateway URL/query, redirect refusal and no automatic credential retry. +- The proxy record includes the actual OpenSandbox python-hello Node calls. The 92-case template matrix used CLI/Python/HTTP and does **not** establish a 92-case Node SDK test. +- The [local runtime example](../examples/README.md) now installs the public Python server 0.3.1a5; its local health/process/file checks do not establish cloud lifecycle support. + +[Documentation synchronization decision](notes/implemented/process/2026-10-24-current-docs-and-records.md) · [verification and acceptance reconciliation](evidence/verify/2026-10-24-current-docs-and-records.md). + +Earlier entries below are a decision history. A remaining proposal is not a current product guarantee; read the linked acceptance scope before treating its full criteria as complete. + + This repository owns decisions and verification for its HTTP client, public configuration schema, ESM/TypeScript exports and examples. New records use English; source contracts in other repositories are linked through absolute GitHub URLs. @@ -19,16 +32,16 @@ Include scoped records in the owning PR. Run applicable tests/build, inspect exa latest-head required CI and independent review, and verify actual remote merge state. A local/runtime result is not cloud acceptance or package publication. -- [Configuration reservations and installation](notes/proposed/process/2026-10-18-config-provider-reservations.md) +- [Configuration reservations and installation](notes/implemented/process/2026-10-18-config-provider-reservations.md) - [Verification](evidence/verify/2026-10-18-config-provider-reservations.md) -- [Portable source installation](notes/proposed/process/2026-10-18-portable-source-installation.md) · [verification](evidence/verify/2026-10-18-portable-source-installation.md) +- [Portable source installation](notes/implemented/process/2026-10-18-portable-source-installation.md) · [verification](evidence/verify/2026-10-18-portable-source-installation.md) - [Current configuration contract](notes/implemented/architecture/2026-10-22-remove-legacy-compatibility.md) · [verification](evidence/verify/2026-10-22-remove-legacy-compatibility.md) - [Compatibility cleanup remote acceptance](evidence/verify/2026-10-22-remove-legacy-acceptance.md) -- [Bound HTTP client](notes/proposed/architecture/2026-10-23-bound-http-client.md) · [verification](evidence/verify/2026-10-23-bound-http-client.md) +- [Bound HTTP client](notes/implemented/architecture/2026-10-23-bound-http-client.md) · [verification](evidence/verify/2026-10-23-bound-http-client.md) - [HTTP binding control-character review](evidence/verify/2026-10-23-bound-http-control-review.md) diff --git a/.agents/evidence/verify/2026-10-24-current-docs-and-records.md b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md new file mode 100644 index 0000000..81fd83e --- /dev/null +++ b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md @@ -0,0 +1,24 @@ +# Verification: current documentation and engineering records + +- Date: 2026-10-24 +- Result: PASS for local documentation checks; latest-head remote CI and review remain merge gates. +- Baseline: `67eccfbc8afe3d3f2e0f30e05677a71b18877e4e`. +- Scope: current Markdown documentation, lifecycle moves and owner index; no runtime or package change. + +## Accepted note reconciliation + +The GitHub API returned an actual merged timestamp and merge SHA for each linked PR: +- `2026-10-23-bound-http-client`: [merged PR #10](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/10). +- `2026-10-18-portable-source-installation`: [merged PR #5](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/5). +- `2026-10-18-config-provider-reservations`: [merged PR #3](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/3). + +This updates the notes' lifecycle, not the historical observations in their evidence. Subsequent source preparation, release and runtime acceptance is linked from the current `.agents/README.md` entry. Older proposals outside this scope retain their original state where their full acceptance criteria have not been re-established. + +## Validation + +- PASS: `npm ci`, `npm run typecheck`, final `npm test` (24 passed, zero failures/skips), `node examples/agent-loop.mjs`, `npm pack --dry-run`, and `git diff --check`. +- Initial `npm test`: 22 passed, two failed because a previous session's virtualenv pointed to a removed interpreter and the shell fell back to Python without the server. No assertion changed. A fresh environment installed public client/server 0.3.1a5 and websockets; the final run passed and the documented local example returned shell result 4, the expected file bytes and SIGTERM cleanup. +- PASS: all 33 relative links in changed/new Markdown resolved locally. +- This is local runtime/source-package validation. No npm publication, cloud lifecycle support or 92-case Node matrix is claimed. + +No new cloud resources or task credentials were created. Existing real-component receipts are references, not reruns under this documentation revision. The normal remote CI matrix remains mandatory; no runtime or publication workflow is weakened for this documentation change. diff --git a/.agents/notes/proposed/architecture/2026-10-23-bound-http-client.md b/.agents/notes/implemented/architecture/2026-10-23-bound-http-client.md similarity index 86% rename from .agents/notes/proposed/architecture/2026-10-23-bound-http-client.md rename to .agents/notes/implemented/architecture/2026-10-23-bound-http-client.md index f2e429d..7f99e37 100644 --- a/.agents/notes/proposed/architecture/2026-10-23-bound-http-client.md +++ b/.agents/notes/implemented/architecture/2026-10-23-bound-http-client.md @@ -1,6 +1,6 @@ # Decision: Bind HTTP requests to one application endpoint -Status: proposed +Status: implemented ## Problem Resolving relative operations against a signed gateway URL discarded its query and could misplace the proxy prefix. Default fetch redirects could send application credentials to a different sandbox. Diagnostics and object inspection exposed URL query credentials. @@ -24,3 +24,7 @@ Use real loopback HTTP servers to check wire paths/query bytes, credential separ ## Acceptance criteria All configured Node tests and type checks pass. Proxy paths and signature bytes survive each operation. Redirects and authority overrides cannot move credentials. No cloud or interpreter API is introduced; verification distinguishes local runtime behavior from cloud acceptance. + +## Implementation + +Delivered in [PR #10](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/10); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations. diff --git a/.agents/notes/proposed/process/2026-10-18-config-provider-reservations.md b/.agents/notes/implemented/process/2026-10-18-config-provider-reservations.md similarity index 86% rename from .agents/notes/proposed/process/2026-10-18-config-provider-reservations.md rename to .agents/notes/implemented/process/2026-10-18-config-provider-reservations.md index 5b1868f..1a8e8b9 100644 --- a/.agents/notes/proposed/process/2026-10-18-config-provider-reservations.md +++ b/.agents/notes/implemented/process/2026-10-18-config-provider-reservations.md @@ -1,6 +1,6 @@ # Decision: Synchronize the public configuration contract -Status: proposed +Status: implemented ## Problem @@ -57,3 +57,7 @@ review before any authorized merge; no cloud or release is involved. ## Evidence - [Verification](../../../evidence/verify/2026-10-18-config-provider-reservations.md) + +## Implementation + +Delivered in [PR #3](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/3); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations. diff --git a/.agents/notes/proposed/process/2026-10-18-portable-source-installation.md b/.agents/notes/implemented/process/2026-10-18-portable-source-installation.md similarity index 83% rename from .agents/notes/proposed/process/2026-10-18-portable-source-installation.md rename to .agents/notes/implemented/process/2026-10-18-portable-source-installation.md index 59c506c..c47d9fa 100644 --- a/.agents/notes/proposed/process/2026-10-18-portable-source-installation.md +++ b/.agents/notes/implemented/process/2026-10-18-portable-source-installation.md @@ -1,5 +1,5 @@ # Decision: Provide a usable Node source package and portable runtime example -Status: proposed +Status: implemented ## Problem @@ -48,3 +48,7 @@ Hosted Node20/22 must pass; a local runtime test is not cloud provider proof. - Explicit Python source configuration remains intact; actual example passes. - Both CI versions run against the pinned real runtime without cloud secrets. - Bilingual docs and accurate owner evidence accompany the change. + +## Implementation + +Delivered in [PR #5](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/5); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations. diff --git a/.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md b/.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md new file mode 100644 index 0000000..58ea7ad --- /dev/null +++ b/.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md @@ -0,0 +1,26 @@ +# Decision: Synchronize current documentation and accepted records +Status: implemented + +## Problem +Current user guides and engineering entry points still contain stale installation, usage or pending-status descriptions after recent delivery. + +## Decision +Update only this owner's current guides and index the actual release, implementation and verification boundaries. Reconcile dated notes with verified merged PRs. Preserve merged evidence verbatim and keep source/provider/consumer versions explicit. + +## API Design +N/A — documentation only; no runtime API, package version or publication changes. + +## Alternatives considered +Do not copy a whole cross-repository report or rewrite historical failures into passes. Do not infer broad platform support from an unrelated passing test. + +## Dependencies +The already-merged owner PRs and dated receipts linked in this repository's engineering index. Related repositories own their own documentation and records. + +## Test Strategy +Run document/record/link checks and the normal remote CI gates. Check examples against the current public API and existing real-component evidence. No cloud rerun is needed for this documentation-only synchronization. + +## Acceptance criteria +Current English/Chinese instructions agree with implemented entry points; accepted notes match their state directory; local links resolve; old evidence is unchanged; required latest-head CI and independent review pass before merge. + +## Evidence +[Verification](../../../evidence/verify/2026-10-24-current-docs-and-records.md). diff --git a/README.md b/README.md index 5c06b5b..d1ea673 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ It is **not** a port of `Sandbox.create`, cloud providers, or the server SDK. Cr ## Install -On2026-10-18 the public npm metadata endpoint for `@agent-sandbox/sdk` returned404. +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: ```bash @@ -24,7 +24,7 @@ npm run build npm pack ``` -This checkout's version0.1.0 produces `agent-sandbox-sdk-0.1.0.tgz` with built +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: ```bash @@ -64,6 +64,28 @@ 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. + ## 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. @@ -121,25 +143,3 @@ readEnv("sandbox_api_key", process.env); ## License Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). - -Configuration storage uses one `storage` descriptor. / 配置存储统一使用 `storage` 字段。 - -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/README.zh-CN.md b/README.zh-CN.md index 48db84b..ed49f60 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -63,6 +63,22 @@ 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 的服务端代理。 + ## 配置名 此表导出配置名称；`readEnv` 只读取值，不会把这些字段自动应用到 `ServerClient`。已移除不生效的旧重试配置名称。 @@ -120,19 +136,3 @@ readEnv("sandbox_api_key", process.env); ## 许可 Apache-2.0。见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 - -Configuration storage uses one `storage` descriptor. / 配置存储统一使用 `storage` 字段。 - -通过提供方端口网关访问时，应传入包含完整代理前缀、沙箱和端口标识及查询参数 -的 URL。客户端保留原查询参数的字节，仅追加操作参数，禁止覆盖网关参数。 -所有重定向均会拒绝，包括同一域名下跳转到另一沙箱；URL 用户信息及越出绑定 -前缀的操作路径也会拒绝。URL 归一化之前即检查原始或多层编码的控制字符、 -路径分隔符与点路径；基址和操作都不能引入重复或多层编码后等价的网关查询键。 - -`token` 用于应用服务令牌，`gatewayHeaders` 用于平台网关请求头，`headers` -用于其他应用请求头。各组请求头名称不能重叠；已有 `Authorization` 请求头时 -不能再传入 `token`。不能覆盖 Host 等寻址及传输请求头。公开 `baseUrl` 和连接 -错误省略查询凭据。不要把平台控制面 API Key 作为应用令牌传入。本客户端使用 -绑定代理前缀的 HTTP URL；按操作签名的路径绑定需要使用提供方适配器的逐操作传输接口，不能传入本前缀客户端。 - -显式应用 `token` 还会通过 `X-Access-Token` 发送，前提是调用方提供的请求头未占用该名称（不区分大小写）。Bearer 仍然保留以兼容现有服务。每次请求复制调用方与网关请求头，不会覆盖它们；未提供 token 时不会添加应用凭据。该行为使用服务端已有认证请求头，兼容剥离 Authorization 的服务端代理。 diff --git a/examples/README.md b/examples/README.md index a1ccd8b..38ed9fb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -39,13 +39,13 @@ The current example uses an installed Python runtime and preserves caller `PYTHONPATH`; it adds no fixed repository paths. Install the server before running: ```bash -python3 -m pip install 'agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/e86cb0be24e0083a27396b260298e7cf27b660d6.tar.gz#subdirectory=server-sdk' +python3 -m pip install 'agent-sandbox-server==0.3.1a5' npm ci npm test node examples/agent-loop.mjs ``` 当前示例使用已安装的 Python 服务端，并原样保留调用方 `PYTHONPATH`，不再添加固定仓库路径。 -先按上面的固定源码安装运行时。开发中的服务端也可通过调用方 `PYTHONPATH` 提供； +先按上面的公开 alpha 版本安装运行时。开发中的服务端也可通过调用方 `PYTHONPATH` 提供； 上方历史输出的环境路径仅记录原来的运行环境。该示例验证本地 HTTP、命令、文件与进程清理， 不代表云端 `Sandbox.create`。