diff --git a/.agents/README.md b/.agents/README.md index ae4d30f..786c1b9 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -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 @@ -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). diff --git a/.agents/evidence/verify/2026-11-10-canonical-cli-guidance.md b/.agents/evidence/verify/2026-11-10-canonical-cli-guidance.md new file mode 100644 index 0000000..b9ec7cc --- /dev/null +++ b/.agents/evidence/verify/2026-11-10-canonical-cli-guidance.md @@ -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. diff --git a/.agents/evidence/verify/2026-11-10-recent-change-index.md b/.agents/evidence/verify/2026-11-10-recent-change-index.md new file mode 100644 index 0000000..5e54462 --- /dev/null +++ b/.agents/evidence/verify/2026-11-10-recent-change-index.md @@ -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. diff --git a/.agents/evidence/verify/2026-11-10-simplification-main-merge.md b/.agents/evidence/verify/2026-11-10-simplification-main-merge.md new file mode 100644 index 0000000..35c71d7 --- /dev/null +++ b/.agents/evidence/verify/2026-11-10-simplification-main-merge.md @@ -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. diff --git a/.agents/notes/proposed/process/2026-11-10-canonical-cli-guidance.md b/.agents/notes/proposed/process/2026-11-10-canonical-cli-guidance.md new file mode 100644 index 0000000..c1b7a84 --- /dev/null +++ b/.agents/notes/proposed/process/2026-11-10-canonical-cli-guidance.md @@ -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. diff --git a/.agents/notes/proposed/process/2026-11-10-recent-change-index.md b/.agents/notes/proposed/process/2026-11-10-recent-change-index.md new file mode 100644 index 0000000..98665cf --- /dev/null +++ b/.agents/notes/proposed/process/2026-11-10-recent-change-index.md @@ -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). diff --git a/CHANGELOG.md b/CHANGELOG.md index d2e0cc6..feb6296 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 0c2fcb3..852c860 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/README.zh-CN.md b/README.zh-CN.md index afab15a..cc5ffe2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -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 的帮助为准。 + ## 支持的操作 | 方法 | 用途 |