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
9 changes: 9 additions & 0 deletions .agents/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Node SDK engineering records

## Recent changes — 2026-11-10

- [Owner change index](notes/proposed/process/2026-11-10-recent-change-index.md) · [records verification](evidence/verify/2026-11-10-recent-change-index.md).
- This is a dated source/delivery index; Draft implementation, prior releases and new validation remain separate.

- [Named deployment guidance](notes/proposed/process/2026-11-10-canonical-cli-guidance.md) · [verification](evidence/verify/2026-11-10-canonical-cli-guidance.md).

- [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
Expand Down Expand Up @@ -68,3 +75,5 @@ state. A local/runtime result is not cloud acceptance or package publication.
- [Preview release notice and community](notes/proposed/process/2026-11-10-preview-release-community.md) · [verification](evidence/verify/2026-11-10-preview-release-community.md).

- [Community QR replacement](notes/proposed/process/2026-11-10-refresh-community-qr.md) · [verification](evidence/verify/2026-11-10-refresh-community-qr.md).

- [Canonical CLI documentation mainline merge](evidence/verify/2026-11-10-simplification-main-merge.md).
29 changes: 29 additions & 0 deletions .agents/evidence/verify/2026-11-10-canonical-cli-guidance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Canonical CLI guidance verification — 2026-11-10

Result: PARTIAL — scoped documentation checks complete; coordinated CLI merge and
latest-head remote CI are separate gates.

Scope: The HTTP client already had no obsolete CLI aliases. Both READMEs now explain how current deploy/status/delete commands provide the endpoint for explicit ServerClient construction. Local deployment names are not URLs or Sandbox IDs; no cloud lifecycle API was added.

## Checks

- Read owning repository contributor, engineering-record and workflow instructions.
- Compared command examples with current CLI source command registration and deployment
handlers: deploy/list/status/logs/delete/recover, template authoring, sandbox command
invocation and provider operations remain separate.
- Changed-Markdown local link check compares missing links with HEAD; no introduced
missing local targets. Historical records and archive examples are not rewritten.
- No runtime code, dependency or examples were changed; runtime tests are not required for this documentation-only scope under the repository instructions.

## Limits and cleanup

No release, backend operation, cloud credential use or cloud resource creation was
performed. No implementation or maturity claim follows from these documentation
checks. This repository's PR must link the CLI coordination change and wait for its
actual final command contract. Temporary local test logs remain outside the repository.

## Final documentation check

- Changed Markdown local-link audit: 6 files checked, no introduced missing file links. URL anchors and remote pages were not fetched.
- Current CLI examples use named deploy/status/delete, sandbox operations and Provider run with JSON input. Historical archived documents remain historical.
- CHANGELOG updated; no version bump or package publication.
67 changes: 67 additions & 0 deletions .agents/evidence/verify/2026-11-10-recent-change-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Verification: recent nodejs-sdk change records

- Date: 2026-11-10
- Result: PASS (records-only checks; implementation gates remain separate)
- Scope: `.agents/README.md`, the recent-change process note and this evidence.
- Source revision inspected: `7676f3d9682bf9486bbdb7ed0fbc8b0e8b637ab9`.
- Mainline revision inspected: `a9ed1962dc627aaddbc729394c4b41c616216966`.
- Remote query timestamp: `2026-11-10T14:48:35.682193+00:00`.
- Environment: Linux, Git, Python 3; source and remote metadata inspection only.

## Commands and observations

- `git fetch origin --prune`: exit 0 in the owning source repository.
- `git status --short --branch`: the selected worktree was clean before this edit.
- `git log origin/main --first-parent --since=2026-11-05 -8`: inspected source history.
- `git rev-parse HEAD` and `git rev-parse origin/main`: revisions listed above.
- GitHub REST GET repository PR and Actions runs: remote metadata queried separately
from any claim of executing tests locally. Authenticated REST supplied a consistent metadata snapshot.

## Prior source CI snapshot

[nodejs-sdk PR #27](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/27) was open, Draft and unmerged.

| Workflow | State | Result |
| --- | --- | --- |
| [Node SDK CI](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/actions/runs/42807096538) | completed | success |

These results belong to the source revision above, before this records commit.
New commits require their own CI; a queued workflow is not a pass.

## Local records validation

- Scoped inline Markdown check below: exit 0; staged relative links resolved.
- One-off ADR/scope/privacy validation: PASS; seven ordered required sections,
proposed lifecycle, 3 intended files, tracked index membership,
no machine paths or credential-pattern matches. All 49
relative links in the scoped documents resolved, including the existing README index.
- `git diff --cached --check -- .agents`: exit 0.
- Reviewed the staged `.agents` diff; no runtime/configuration/public article changes.

Reproducible scoped link check, run from this repository after staging:

```bash
python3 - <<'PY'
from pathlib import Path
import re, subprocess
files = subprocess.check_output(
["git", "diff", "--cached", "--name-only"], text=True).splitlines()
for name in files:
assert name.startswith(".agents/") and name.endswith(".md")
path = Path(name)
text = path.read_text()
for target in re.findall(r"\[[^\]]*\]\(([^\s)]+)\)", text):
if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:", target) or target.startswith("#"):
continue
assert (path.parent / target.split("#", 1)[0]).exists(), (name, target)
print("Scoped staged Markdown links: PASS")
PY
```


## Not verified and cleanup

No runtime, Docker, cloud, model, performance or new package-publication check was
run for this records-only change. Earlier acceptance retains its original scope.
No cloud resources were created, changed or deleted. Required implementation gates
remain with their existing PRs; this task does not declare those PRs complete.
15 changes: 15 additions & 0 deletions .agents/evidence/verify/2026-11-10-simplification-main-merge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Canonical CLI documentation mainline merge — 2026-11-10

Scope: https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/27 .

Merge fixed main `a9ed1962dc627aaddbc729394c4b41c616216966` into the published simplification branch without rebase or force-push. Main added only the preview/community announcement and QR replacement. A read-only merge-tree review found no conflicts, and parent review approved preserving both mainline community content and the current CLI guidance. Node package code, dependencies and HTTP client exports are unchanged.

## Verification

- Both README announcement/community lines match fixed upstream.
- QR image and four upstream engineering records match upstream bytes.
- Seven merged Markdown files checked for local file links; no missing targets. Remote URLs and anchor fragments were not checked.
- Git diff whitespace check passed. The canonical CLI note, CHANGELOG entry and existing guidance remain retained.
- No new Node runtime or cloud test was run for this documentation-only merge. The prior PR checks remain historical; remote CI must rerun on this merge commit.

No package version, release state, credential policy or provider qualification changed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Named deployment guidance

Status: Proposed; local documentation update, coordinated merge pending.
Request: https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/issues/244

## Problem

The CLI's unified source command surface requires consumers to distinguish source
preparation, named deployment lifecycle and runtime client calls.

## Decision

The HTTP client already had no obsolete CLI aliases. Both READMEs now explain how current deploy/status/delete commands provide the endpoint for explicit ServerClient construction. Local deployment names are not URLs or Sandbox IDs; no cloud lifecycle API was added.

## API Design

No public API or dependency changes. Current-source commands are documented separately
from fixed historical releases. Existing credential audiences and runtime limitations
remain in place.

## Alternatives considered

Adding compatibility aliases in each consumer would duplicate CLI ownership. Treating
the Node HTTP client as a cloud lifecycle client or changing Provider features for a
documentation update would expand scope without evidence.

## Dependencies

The corresponding CLI change must land before users rely on current-source command
examples. Source merge does not imply a newly published CLI or SDK package.

## Test Strategy

Inspect actual registered CLI commands, verify changed Markdown links, review the
bilingual task paths and run any owning repository checks applicable to this scope.

## Acceptance criteria

Current examples resolve to existing CLI commands and accurately retain the runtime
package's responsibility. Historical evidence is unchanged; no new backend acceptance
or maturity claim is introduced.

See [verification](../../../evidence/verify/2026-11-10-canonical-cli-guidance.md).

## Mainline reconciliation

Merge fixed main `a9ed1962dc627aaddbc729394c4b41c616216966` to retain the independently merged preview/community announcement and QR replacement. Both lines of documentation coexist without conflicts. No implementation or compatibility change is added; verification is recorded in the separate mainline-merge evidence.
78 changes: 78 additions & 0 deletions .agents/notes/proposed/process/2026-11-10-recent-change-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Decision: Index recent changes to node application http client
Status: proposed

## Problem

Recent implementation, user-experience changes and delivery status are spread across
owner records, pull requests and workspace reports. The user requested that recent
changes be retained under each owning repository's `.agents/` and pushed.

## Decision

Keep this dated index in nodejs-sdk; link existing canonical decisions and immutable
verification instead of copying their reports or rewriting historical acceptance.
This index adds no product behavior and does not change any older ADR's lifecycle.

### Owner changes and canonical records

The candidate adds bilingual named deploy/status/delete guidance for obtaining the endpoint passed to ServerClient. It changes no runtime code, dependency or public export. The SDK remains an application HTTP client; it does not become a cloud lifecycle, template-build, PTY or interpreter SDK.

- [Current-source CLI guidance](../../../notes/proposed/process/2026-11-10-canonical-cli-guidance.md).
- [Documentation verification](../../../evidence/verify/2026-11-10-canonical-cli-guidance.md).
- [Application command invocation](../../../notes/implemented/feature/2026-11-05-application-command-invocation.md).

### Mainline and candidate boundary

- Mainline observed: `a9ed1962dc627aaddbc729394c4b41c616216966`.
- Candidate/source observed before this records commit: `7676f3d9682bf9486bbdb7ed0fbc8b0e8b637ab9`.
- [nodejs-sdk PR #27](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/pull/27), OPEN and Draft at the recorded query; not merged.
- The unified source CLI is different from published CLI 0.5.10. This task does
not issue npm/PyPI releases, deploy sites or certify changed templates.

Recent mainline changes, inspected from the refreshed Git history:

| Date | Commit | Change |
| --- | --- | --- |
| 2026-11-10 | [a9ed1962dc62](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/commit/a9ed1962dc627aaddbc729394c4b41c616216966) | docs: replace community QR image and join link (#26) |
| 2026-11-10 | [c953cd9d919f](https://github.com/Alibaba-Agent-Sandbox/nodejs-sdk/commit/c953cd9d919f964ff11fa7df0a80476d9ca98c27) | docs: announce preview release schedule and developer community (#25) |

### Remaining delivery limits

Guidance depends on delivery of the unified CLI. Keep the coordinated PR Draft; source documentation does not establish npm publication or a new backend acceptance matrix.

## API Design

N/A — this decision does not involve API changes. Existing runtime, credential,
source identity and resource ownership contracts remain with their original owners.

## Alternatives considered

- A workspace-only summary cannot travel with an independent checkout.
- Copying all cross-repository reports duplicates authority and may expose private logs.
- Marking all proposed records implemented would confuse source work with accepted delivery.
- Combining unrelated local changes or permission-only differences in this commit
would conceal the actual records scope.

## Dependencies

Existing owner records and GitHub PR/commit state. Coordinated implementation is
tracked in [CLI Issue #244](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/issues/244).
Each repository retains its own branch, record, verification and push.

## Test Strategy

Check the new record structure, relative links, pinned Git source revisions and
scoped diff; run the owner's applicable documentation/health checks. Query PR/CI
state separately from local checks. Do not run cloud tests solely to validate prose.

## Acceptance criteria

- Recent owner work is reachable from `.agents/README.md` with dated source references.
- Merged, Draft, failed, unrun and planned work remain distinguishable.
- Existing historical evidence and unrelated work remain intact.
- Documentation checks and remaining gates are recorded; scoped commits are pushed
to task branches and remote branch hashes are independently compared.

## Evidence

- [Records verification](../../../evidence/verify/2026-11-10-recent-change-index.md).
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@

### Documentation

- Document the named CLI deployment workflow and keep the Node SDK focused on explicit application HTTP endpoints. / 文档对齐具名部署命令,Node SDK 继续使用明确的应用 HTTP 地址。

- Select the verified public Python a4 runtime and matching configuration-source tag; preserve prior a3 verification as history. / 本地示例与配置对照统一公开 Python a4,保留原 a3 验证记录。

- Select verified public Python server 0.4.0a3 in the local example and CI, with its matching configuration-schema release tag.
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ try {

`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.

For a source template, the current CLI uses `abx deploy SOURCE --name APP`, `abx status APP` and `abx delete APP --yes`. Read the returned service endpoint and configure `ServerClient` explicitly; a local CLI application name is not a URL or a Sandbox ID. See the [CLI deployment guide](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/authoring-templates.md). Check your installed CLI’s help when using an older release.

## Supported operations

| Method | Purpose |
Expand Down
2 changes: 2 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ try {

`ABX_SERVER_TOKEN` 是该服务配置的应用认证令牌。连接提供方网关时,应使用完整服务地址及提供方的 `gatewayHeaders`,详见[认证与网关连接](docs/server-client.zh-CN.md)。应用令牌与提供方 API Key 分开使用。

源码模板使用当前 CLI 的 `abx deploy SOURCE --name APP` 部署,通过 `abx status APP` 查看,通过 `abx delete APP --yes` 删除。使用返回的服务端点显式配置 `ServerClient`;CLI 本机应用名称不等于 URL 或沙箱 ID。详见 [CLI 部署指南](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/zh/guide/authoring-templates.md)。使用旧发行版时,以已安装 CLI 的帮助为准。

## 支持的操作

| 方法 | 用途 |
Expand Down
Loading