diff --git a/.agents/README.md b/.agents/README.md index 0cb9c091..4e87c9d6 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -1,5 +1,7 @@ # `.agents/` — engineering record of the python-sdk repository +- [Managed native harness adapters](notes/proposed/feature/2026-11-17-managed-harness-adapters.md) · [verification](evidence/verify/2026-11-17-managed-harness-adapters.md). + - [Agents API delivery operations](notes/proposed/process/2026-11-12-agents-api-delivery-operations.md) · [record-placement verification](evidence/verify/2026-11-12-agents-api-delivery-operations.md). - [Standalone server policy documentation](notes/proposed/feature/2026-11-12-standalone-policy-docs.md) · [verification](evidence/verify/2026-11-12-standalone-policy-docs.md). @@ -12,6 +14,10 @@ - [Managed Agent input and saved-configuration contract](notes/proposed/feature/2026-11-12-managed-agent-input-contract.md) · [verification](evidence/verify/2026-11-12-managed-agent-input-contract.md). +- [Managed Turn identities and lifecycle event shapes](notes/proposed/feature/2026-11-17-managed-turn-wire.md) · [verification](evidence/verify/2026-11-17-managed-turn-wire.md). + +- [Current SDK template consumer boundary](notes/proposed/process/2026-11-17-current-template-consumer-boundary.md) · [verification](evidence/verify/2026-11-17-current-template-consumer-boundary.md). + ## 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). @@ -289,3 +295,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ - [SDK simplification mainline reconciliation](evidence/verify/2026-11-10-simplification-main-merge.md). - [Python documentation consumers of the unified CLI](notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md) · [verification](evidence/verify/2026-11-12-ecosystem-guidance-sync.md). + +- [Agents API independent review round 2: protocol](evidence/verify/2026-11-17-agents-api-reviews/post-round2-protocol.md) · [runtime](evidence/verify/2026-11-17-agents-api-reviews/post-round2-runtime.md). Initial protocol/Harness/runtime analyses and failure controls remain in the same dated evidence directory; review approval is limited to stated local scope. diff --git a/.agents/evidence/verify/2026-11-17-agents-api-reviews/harness-round1.md b/.agents/evidence/verify/2026-11-17-agents-api-reviews/harness-round1.md new file mode 100644 index 00000000..645085df --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-agents-api-reviews/harness-round1.md @@ -0,0 +1,68 @@ +# Harness adaptation review — round 1 + +Date: 2026-11-17. Scope: read-only source and official documentation investigation, not cloud/model acceptance. + +## Decision + +Proceed with one shared Managed Agents API contract and six explicitly named deployment templates. Keep Gateway, durable submissions, files/artifacts, Worker, reconciliation and owned cleanup shared. Implement each native harness adapter behind the existing AgentRuntime invocation/parser boundary. A copied Dockerfile and renamed catalog entry alone do not deliver an adapter. + +Do not advertise universal OpenAI equivalence. Preserve the same API request/resource/event envelopes; report unsupported capabilities and streaming granularity honestly. Native session restoration and actual process termination must be verified separately for every harness. + +## Baseline and concrete gaps + +Reviewed Python main `a9a572d81847fe99216bf1bb454b91810dacc676` and templates PR311 `ee59a726bb04e9b67a79b1bcbbb0a528ced11ef1` in the task's isolated checkouts. Old workspace roots are stale and were not treated as the new implementation. + +1. `server-sdk/src/agent_sandbox/server/managed.py:111` allows only `codex` and `qwen-code`, and creates a ProviderSpec from OPENAI environment variables. Its capabilities endpoint repeats the same two-binary list. +2. `client-sdk/src/agent_sandbox/managed_agents/models.py:148` restricts model bindings to those two adapters; line 183 allows only three OPENAI variable names. +3. `client-sdk/src/agent_sandbox/providers/alicloud_express/managed.py` requires an exact four-field model object and those two adapter names, requires exactly the OPENAI allowlist, and injects those names into the guest. Qoder's native PAT cannot use this shape truthfully. +4. `server-sdk/src/agent_sandbox/server/agents/adapters/__init__.py` registers Codex, Claude Code, Cursor, Qwen Code and generic Command adapters. Qoder, OpenCode and official DeepSeek Harness are absent. Claude Code exists in the core runtime but is unavailable in the managed bridge. +5. `agents-api/server/bootstrap.py:25` repeats the two-adapter restriction and requires OPENAI key/HTTPS endpoint for every Worker. `agents-api/Dockerfile` installs only Codex 0.162.1 and Qwen Code 0.23.0. +6. The existing `deepseek-harness` template is explicitly a repository-owned Python Chat Completions tool loop. It is not the official DeepSeek Harness and cannot satisfy a request for that native harness under a new label. + +## Native interfaces and authentication + +| Harness | Existing/new runtime | Native headless interface | Native continuation | Authentication/configuration | +| --- | --- | --- | --- | --- | +| Codex | existing `codex` adapter | `codex exec --json`, prompt via stdin | `codex exec resume ID` | OPENAI_API_KEY plus explicit Responses endpoint/model | +| Qwen Code | existing `qwen-code` adapter | positional prompt, `--output-format stream-json --include-partial-messages` | `--resume ID` | OPENAI_API_KEY/BASE_URL/MODEL for the existing compatible-service path | +| Claude Code | existing `claude-code`, extend managed integration | `claude -p --output-format stream-json --verbose --include-partial-messages` | `--resume ID` | ANTHROPIC_API_KEY or native bearer/OAuth credentials; Messages API endpoint | +| Qoder | new `qoder` adapter | `qoder --print --output-format stream-json` | `--resume ID` | QODER_PERSONAL_ACCESS_TOKEN for native service; model selection uses Qoder model IDs | +| OpenCode | new `opencode` adapter | version-specific `opencode run --format json` | `--session ID` | explicit provider/model config; do not assume arbitrary OPENAI env alone configures a provider | +| DeepSeek Harness | new `deepseek-harness` adapter | `dsh --profile headless --json -` | `--session-id ID` with same DSH_HOME and cwd | DEEPSEEK_API_KEY, explicit route config; official package `@deepseek-ai/dsh` | + +Official Codex documentation demonstrates automation through `codex exec --json` and observable command events. The existing pinned adapter still needs actual two-turn testing after managed template migration. [OpenAI official documentation](https://developers.openai.com/blog/eval-skills). + +Qwen's headless JSON mode returns structured session, assistant, and terminal result messages; optional partial events provide finer streaming. A terminal result can precede process exit because managed memory work may still be running. Keep the supervisor's exit check. [Official headless guide](https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/). + +Claude's programmatic CLI supports structured streaming and explicit resume. SIGTERM leaves the active turn unfinished; SIGINT or SDK interrupt can end it first. Background commands/MCP work have separate lifecycle behavior, so CLI success alone does not establish all work stopped. [Official headless guide](https://code.claude.com/docs/en/headless). + +Qoder documents headless JSON, stream-json, session IDs and exact resume. Its PAT is obtained from account integrations and passed as QODER_PERSONAL_ACCESS_TOKEN. BYOK is account/plan/catalog dependent, configured through its wizard; the documentation explicitly rejects inventing manual settings.json BYOK configuration. The first managed adapter should use native PAT/model selection. [CLI reference](https://docs.qoder.com/cli/cli-reference), [authentication](https://docs.qoder.com/cli/authentication), [custom models](https://docs.qoder.com/cli/custom-models). + +OpenCode currently has two published npm lines: existing templates pin `opencode-ai@1.19.0`, while current docs show `@opencode/cli` v2 and new flags such as standalone. Pick one fixed line and verify its help/events; do not infer v1 behavior from v2 examples. Both document headless tasks, JSON output, model choice and exact session continuation. [Official current command guide](https://opencode.ai/docs/cli/commands), [model config](https://opencode.ai/docs/models/). + +Official DeepSeek Harness is real, developed by DeepSeek AI, and in developer preview. Pinned tag `dsh-v0.2.2-rc.1`, commit `66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db`, documents the native headless path. Its JSON text events come from committed steps, not token deltas. Preserve the terminal final reason: completed requires both exit 0 and `final.reason.kind == completed`; a tool_result alone is insufficient. Resume requires the same home/cwd and persisted identity. [Official project](https://github.com/deepseek-ai/deepseek-harness), [pinned headless interface](https://github.com/deepseek-ai/deepseek-harness/blob/66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db/packages/bundle/headless/README.md). + +Registry metadata observed: Codex latest 0.169.0, Claude Code 2.1.326, Qwen Code 0.27.4, Qoder CLI 1.1.90, DSH 0.2.2-rc.1, OpenCode v1 1.19.5/v2 2.3.0. These are discovery results, not recommendations to upgrade working pins. DSH requires Node >=24.9; the template's Node 24.16 meets that requirement. All runtime installations must remain exact-version pinned and checked in the final image. + +## Minimal implementation boundary + +- Keep existing model-to-adapter binding and deploy independent `agents-api-{harness}` applications. The same model may be used by different harness deployments without overloading model identity. +- Add three real adapters and register their canonical IDs/aliases. Reuse parser helpers only when captured native event schemas match. Test malformed/truncated events, errors and resume IDs as well as success. +- Put managed adapter-to-native environment mapping in one stdlib-only shared module; validate exact credentials/configuration per adapter, preserve explicit endpoints and prevent arbitrary environment forwarding. Qoder does not need a fake OPENAI endpoint. +- Preserve serialized turns, durable native receipt/epoch handling, output bounds, cancellation, process-domain quiescence and owned Sandbox destruction. Do not let adapter changes bypass uncertainty handling. +- Default to one headless subprocess per turn. Avoid unrelated native daemon/server management until needed by a verified harness path. +- Use one shared template bridge/release implementation and reviewed harness-specific pins/configuration. Separate template IDs may share maintained source code without copying Gateway state machines six times. + +## Acceptance and release gates + +Local parser/invocation fixtures prove adapter mappings only. Each harness requires an installed native CLI smoke, two real model turns on one native session, file input, generated source/report download and independent execution, cancellation while a tool runs, bounded failure output, process absence or owned Sandbox deletion, and close/delete semantics. One shared real FC/PostgreSQL application plus controlled per-harness guest sessions can establish core hosting behavior without creating six databases. Keep revised-template deployment/update/old-session continuation as their own gate. + +Do not rename unverified evidence into passes. An unavailable account or model route is a concrete BLOCKED harness acceptance, even if installation succeeds. Preserve Beta/experimental until the applicable full acceptance policy is met. + +## Cross-examination + +- Runtime reviewer agrees with short-lived headless invocation and preserving receipt/epoch/no-replay rules. A final JSON message cannot replace actual exit/stop confirmation. Revised FC/PostgreSQL recipe and old-session upgrade remain unverified release gates. +- Protocol reviewer agrees that create/input/files/turns/items/events/cancel/close/delete and genuine resume form the shared baseline. Steering, functions, MCP and subagents require honest capability boundaries. Committed-step streaming is valid when reported as such, but must not be represented as token streaming. +- No evidence supports requiring a separate public protocol for each harness. Native capabilities differ; HTTP resource identity and ownership rules should stay shared. + +No product file, credential or cloud resource was changed during this review. Follow-on implementation was separately assigned after this report's findings were shared. diff --git a/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round1-runtime.md b/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round1-runtime.md new file mode 100644 index 00000000..f0d0839c --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round1-runtime.md @@ -0,0 +1,24 @@ +# Managed Agent API — independent post-implementation runtime review, round 1 + +Date: 2026-11-17. Result: PARTIAL / acceptance remains blocked. + +## Reviewed scope + +Read the candidate six template configurations, standalone bootstrap, release initialization and credential forwarding; SDK public Turn projection/Worker event changes; native Qoder, OpenCode and official DeepSeek Harness adapters; shared credential descriptors and ProcessDomain. Scope is the current task diff against the existing PR heads, not a released a8 artifact. + +## Findings and disposition + +1. **Actual consumer defect, unresolved:** SDK public `api.capability.parse_template_data` rejects the new `agents-api-codex/template.yaml` at schema root. Independently reproduced using the candidate installed SDK and actual YAML. The SDK packages the old ef695 contract and still consumes singular `sandbox.template/instance/start/ready`; current producer is named-resource `vars/sandbox/serving`. Managed backend and run.py explicit create/start paths do not parse this YAML, so this does not invalidate those paths. Replacing schema bytes alone would break the internal managed-instance compiler. Root/protocol reviewer were asked to preserve a precise open consumer gap and prevent a8 from claiming finished YAML migration. +2. **Adapter capability gap:** OpenCodeParser originally emitted tool_start plus tool_end for every tool_use record. Actual OpenCode v1 CLI emits completed-tool records, so the original guard cannot enforce maxToolSeconds from the actual native tool start. Root/Harness reviewer confirmed the source/probe boundary. They are correcting native outcome mapping/capability statements and adding user-facing limits to the template, both topics and guide. Overall Turn deadline/cancellation/process cleanup remain applicable. Do not fabricate real-time starts to imply full per-tool timing. +3. **Descriptor mismatch, non-blocking:** template diagnostic binary qodercli differed from adapter qoder. Independent Harness reviewer installed the exact npm package and confirmed both bin names; it is not a missing binary defect. Root accepted one canonical qoder spelling and corrected the official help URL. +4. **Publication/E2E blockers remain:** a8 is unpublished; both images now correctly require it instead of installing a7 without the new contract. Docker, final PostgreSQL-backed FC publication, stable alias/timer, retained old Session upgrade, six vendor/model native tasks and owned cloud cleanup have not been completed for this candidate. Source/config tests cannot close those gates. + +## Independent checks + +- `python -m unittest discover -s scripts -p test_agents_api_family.py -v`: PASS, 2 tests including six subcases. Each downloaded standalone project removes registry.yaml, compiles its bootstrap, creates a real local SQLite-backed ManagedService Session and passes that real frozen Session to ManagedExpressBackend.create up to the mocked native-infrastructure boundary. This tests the actual allowlist/settings chain, not a fabricated Session dict; it is not native cloud I/O. +- Project-independent stdlib raw HTTP control: raw GET501/header-only POST timeout, same listener http.client/urllib-no-proxy GET200. Actual source and typed results are retained in the SDK engineering record. This reproduces eight existing raw-test symptoms outside project code; the interception root cause is unproven and those tests remain failures. +- Read Turn projection and same-name events. Stable frozen Session agent identity, nullable historical start and reconstructed host in_progress.turn are reasonable. Saved Agent identity is never re-looked-up during projection; no subagent capability is introduced. + +## Review decision + +The minimal source approach is reasonable after the above corrections. Keep the shared receipt/epoch/process-domain and no-blind-replay design. Uniform public protocol does not imply identical native authentication, token streaming or tool-start observation. A second post-change review is required after these findings; no final completion or release approval is given in this round. diff --git a/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round2-protocol.md b/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round2-protocol.md new file mode 100644 index 00000000..a15753ff --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round2-protocol.md @@ -0,0 +1,136 @@ +# Agents API — post-implementation protocol review, round 2 + +Date: 2026-11-17. Reviewer: protocol_audit. + +Result: the reviewed candidate design is reasonable after the concrete corrections below; +**the user's complete delivered/released outcome is still NOT COMPLETE**. Image, cloud, +real six-Harness acceptance, runtime publication and SDK source-consumer migration are +separate unmet gates. This review does not approve treating local passes as those gates. + +## Scope and independence + +Reviewed root's corrected six-template generation/bootstrap/release/docs, the other +agent's native Harness adapters and authentication mapping, Registry/website topics, +new bilingual source article and the CLI's bilingual managed guide. My own Turn-wire +patch is not independently approved by this report: runtime_audit independently reviewed +it and the configured capability/identity tests. Changes remain candidate source at this +review; no package, remote merge or website deployment is inferred from local files. + +## First-round findings rechecked + +| Finding | Corrected behavior | Verification | +| --- | --- | --- | +| Missing modelEnvAllowlist | Bootstrap compiles the selected native names into the frozen runtime settings | Real bootstrap/config/Session/backend admission now reaches the intercepted infrastructure boundary for all six profiles | +| Literal plus markers in Docker RUN | Generator and all Guest install instructions are clean | Strict argv stand-ins execute exact shell; each injected old plus-marker control fails | +| All Harnesses described as Responses | Generated configuration text now uses each native protocol, Qoder native PAT/service and actual qoder binary | Source review of generator, profiles and generated bilingual instructions | +| Private/obsolete generator files | Closed shared-source list avoids ignored local overrides; check mode reports unexpected generated source | Generator implementation reviewed; --check passes | +| Same-name Turn/event fields | Stable frozen Agent identity, integer/null timestamps and host Turn in lifecycle event | Five local wire/capability tests pass, including official SDK local HTTP retrieval and SSE consumption | +| OpenCode completion records presented as live starts | Completion-only event kind emits terminal tool items, no synthetic running tool; per_tool_timeout=false | Parser/runtime/capability implementation and regressions reviewed | +| OpenCode workspace_write silently allowed full access | Adapter now rejects unsupported workspace_write and documents read_only/full_access; managed remains full_access inside Sandbox | Validate/build paths and bilingual Harness guide reviewed | +| Configured adapter reported installed | Runtime inventory reports configured=true and installed=null until a Guest can actually be inspected | Public API capability regression passes | + +Independent executed commands in this round: + +- `python scripts/sync_agents_api_templates.py --check`: PASS. +- `python scripts/test_agents_api_family.py`: three tests PASS, including six-profile + native-admission flow and strict shell failure controls; no image/cloud claim. +- `pytest client-sdk/tests/test_managed_wire.py -q`: five PASS (1.48 seconds), including + configured-runtime truthfulness and OpenAI3.52 typed/local-HTTP consumption. +- Scoped Ruff passed; final diff whitespace check passed. Owning repository full checks + remain separately recorded by the coordinating agent. + +## Protocol and native Harness conclusions + +One project protocol for Sessions, submissions, turns/items, durable events, immutable +input/output files and cleanup is a reasonable common core. Native authentication is +selected explicitly; the host/standalone-server environment-name tables have parity +coverage. Credentials are not transported in command arguments or generated native +configuration files. Qoder does not receive an invented OpenAI endpoint. DSH's persistent +home and all three adapters' exact native-session flags preserve the intended continuation +mapping. This is a verified mapping/design, not six independent real-model resume passes. + +Parser final outcomes are required. Empty zero exits cannot create successful Qoder, +OpenCode or DSH turns. OpenCode tool-call steps do not end a turn; explicit native errors +fail it. DSH committed text is not represented as token deltas. The runtime's process +observation and existing managed epoch/receipt uncertainty handling remain in place. +Local typed parsing of supported Turns/events does not establish full Session/Agent/error +schema parity with every OpenAI SDK. Functions, MCP result/approval flows, subagents, +mid-turn steering and automatic review remain absent from the public managed profile. + +## Ingress review + +The selected native FC custom-container topology is appropriate for the product's single +HTTP endpoint. The [official FC Web-function documentation](https://help.aliyun.com/en/functioncompute/web-functions) +distinguishes HTTP passthrough from API invocation, which becomes POST /invoke with an +application/octet-stream body and loses HTTP status/header information. The managed private +listener explicitly supports that media type and validates its signed role envelope; it +does not treat an API invocation status200 alone as business success. + +The [official FC SSE documentation](https://help.aliyun.com/en/functioncompute/does-function-compute-support-sse-streaming-response) +requires a Web-function response carrying Transfer-Encoding:chunked. The Gateway emits +that header and chunk framing. No extra invented responseMode field is required by these +sources. Actual deployed URL routing, alias switching and live delivery must still be +observed on the provider; local chunk delivery and static props do not establish them. + +## Topic and documentation review + +Registry uses explicit six-Harness membership and ingested catalog availability. It does +not invent a successful runtime from source metadata. The old agents-api route redirects +to the topic. Registry links to the blog topic and template/API source; website links back +to the collection. The article starts with these usable entry links and uses real HTTP +clients; it does not invent a dedicated Gateway SDK. + +The bilingual topic/article copy correctly separates the shared HTTP interface from +native capabilities and OpenAI's hosted architecture. It labels the six new templates as +under development, states the unsupported public workflows and the OpenCode per-tool +limit, and distinguishes old DeepSeek compatible-loop evidence from official DSH. The +old CSV article retains its fixed historical recipe and clearly bounds its Qwen result. +The English route can intentionally display that Chinese article via the website's actual +language-fallback implementation; this is not a broken invented English source article. + +Visually inspected the captured Registry Chinese desktop light screenshot and website +English mobile dark screenshot. Both show the intended shared container and clear topic +entry, readable stacked mobile content, consistent article rows and explicit language +badges for fallback posts. These two manual checks are not a claim that every screenshot +or interaction was manually reviewed. The recorded browser matrix separately reports +routes/layout/errors and does not represent model or cloud acceptance. + +CLI guidance points to the source-owned family and preserves application-owned database, +credential, publication and drain responsibilities. Its candidate-version warning avoids +claiming released older packages support the new YAML/adapters. No new CLI command tree +or unrelated package release was introduced for these documentation links. + +## SDK YAML consumer boundary + +Actual call tracing established a remaining earlier-task gap: the packaged Python YAML +normalizer/discovery and launch_template still consume the older single-Sandbox draft, +while current templates and CLI use named resources. The current template run.py uses +ProviderSandbox.create/start_server directly; managed ExpressBackend and the JavaScript +CLI do not call that older Python source parser. It therefore does not block the corrected +managed-template runtime path. + +The owner-approved scoped response corrects AGENTS.md and eight bilingual documentation +pairs, preserves useful independent runtime APIs and records the unmigrated source +consumer honestly. It does not pretend schema-byte sync alone is a migration, silently +remove SDK APIs or grow another deployment engine. The overall YAML owner Issue309 must +stay open until its actual remaining consumer criteria are delivered or explicitly +resolved by the owner. + +## Remaining delivery gates + +- Matching client/server0.4.0a8 is still an unpublished candidate at this review. The + template's pinned image installs are blocked until real paired artifacts exist. +- All six changed images need exact-source build and native installation evidence. +- FC Gateway/Worker/Dispatcher with actual PostgreSQL, native model tasks, per-Session + continuation, retained-session upgrade, cancellation and independently confirmed owned + cleanup must be completed within the stated scope. Local fixtures and prior recipe + results cannot stand in for this candidate. +- Existing raw-socket regression failures remain failures. The stdlib-only control + reproduced the raw501/timeout distinction outside project imports while normal HTTP + clients passed. It does not justify weakening tests or claiming an unrun remote matrix. +- Latest-head CI, required reviews, actual PR merges, package publication/readback and + public site deploy verification must be checked independently before claiming release. + +There is no remaining observed blocker in the reviewed corrected local template/core +contract mapping, but this is **conditional readiness for the next delivery gates**, not +completion of the user's end-to-end request or approval to close the cross-repository Issue. diff --git a/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round2-runtime.md b/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round2-runtime.md new file mode 100644 index 00000000..686fdeec --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-agents-api-reviews/post-round2-runtime.md @@ -0,0 +1,36 @@ +# Managed Agent API — independent post-implementation runtime review, round 2 + +Date:2026-11-17. Scope: corrected six-Harness template/SDK source, not released artifacts. +Result: **PARTIAL. Source changes are reasonable within declared limits; the complete user delivery is not finished and release acceptance is not approved.** + +## Re-examined after round-1 corrections + +- Read all three new native adapters (`qoder.py`, `opencode.py`, `deepseek_harness.py`), existing Claude adapter, credential descriptors, actual invocation/resume arguments, parsers and `AgentRuntime` terminal handling; checked their interaction with guest ProcessDomain and receipt handling. +- Read six template profiles, Docker/package pins, per-role bootstrap/credential forwarding, generated standalone project checks and release constraints. Qoder's canonical executable now matches `qoder`; the exact upstream npm package supports both qoder/qodercli. +- Read final Turn projections and worker-created/in-progress/terminal events. Saved Agent snapshots retain original IDs and instructions after definition changes/deletion. Inline snapshot identities are stable per Session; legacy unknown starts are null and no private state is silently rewritten. +- Read actual native OpenCode/official DSH deterministic loopback capture results: two subprocess turns each exit0, retain the same native Session ID and send prior marker history on continuation. These are native CLI/protocol/resume evidence using synthetic model responses, not vendor/model business tasks. + +## Closed or correctly bounded findings + +1. **Bootstrap allowlist chain:** the real Session settings now carry the selected native env names. Independently reran `python -m unittest discover -s scripts -p test_agents_api_family.py -v`:2 tests pass with six adapter subcases, including standalone downloaded project/no registry.yaml, actual ManagedService Session creation and entry to the mocked native infrastructure boundary. Gateway/Dispatcher contain no selected model credential in their generated configuration. +2. **OpenCode completed-only tools:** parser now emits `tool_complete` for actual completed/error records; `_TurnBuilder` creates an already-terminal item and the tool watchdog admits only genuinely in-progress items. No instantaneous fake start is emitted to claim real-time per-tool measurement. Adapter metadata declares completed-only observations and project capability metadata/user documentation distinguish per-tool timing from whole-Turn deadline/cancel/process cleanup. The independent server regression asserts the builder emits terminal statuses and no active-tool start clock. +3. **Native terminal results:** Qoder requires a terminal native result; OpenCode requires a terminal stop/end_turn/length or an explicit error; DSH requires final.reason.kind=completed. The shared runtime still checks process exit status and fatal errors after parser.finish; a successful record cannot turn nonzero process exit into success. ProcessDomain remains the source of cooperative residual-process confirmation, and provider destruction remains the fallback when stop is uncertain. +4. **Native authentication and endpoint routing:** Qoder uses its PAT without an invented model endpoint; OpenCode receives explicit env-referenced provider JSON; official DSH uses its native profile overlay and DEEPSEEK variables. Root/Harness reviewer verified DSH's endpoint against an actual loopback Messages listener. Only the selected native credential map enters the Sandbox. +5. **Wire projections:** independently reran client wire/harness tests:17 pass. Official OpenAI3.52 typed Turn/event parsing and actual authenticated local SDK/SSE consumption are present in the focused regressions, while legacy/saved snapshot cases keep a stable host identity. No broad SDK-equivalence claim is made. +6. **Independent server suite:** `pytest tests/test_server/test_harness_adapters.py -q`:20 pass in0.37s. This includes native-capture parser cases and completed-only builder semantics. It does not execute real vendor/model tasks. + +## Remaining gates: completion is not established + +- Paired runtime a8 is still unpublished. Six Guest/Server recipes deliberately require that version and say builds/deployment must wait; installing a7 is not a valid substitute. +- The exact candidate Guest/Server images have not been built here. There is no final PostgreSQL-backed FC release, candidate-to-stable alias proof, timer delivery, retained old-Session upgrade, six authenticated real-model/tool/file tasks or independent owned-cloud cleanup for these changes. Prior version/local Qwen results and deterministic native loopback responses do not replace those gates. +- SDK public YAML/discovery still packages the earlier singular contract. Independently reproduced current named-template rejection through `parse_template_data` in round1; the new owner boundary record now states this accurately. Managed explicit create/start does not consume this YAML. This remains a real SDK consumer gap; source contract byte replacement alone would damage private managed-instance validation and is not an approved shortcut. +- Eight existing raw socket regressions remain failed. A stdlib-only listener reproduces raw GET501/header-only POST timeout while http.client/urllib-no-proxy return200; this isolates a project-independent environment distinction without proving its underlying mechanism or waiving checks. +- Independent topic/website publication still needs the normal reviewed source/CI/deployment path. Local article/layout checks establish no Agent runtime acceptance. + +## Additional truthfulness check sent for cross-review + +The managed `/v1/agents/runtimes` response historically reports `installed:true` from configured model mappings, while only guest `/capabilities` checks actual binaries. A Gateway has no installed-binary observation before Sandbox creation. Cross-review accepted a focused correction: configured=true, installed=null until actual guest observation, with matching documentation and a regression. Independently reran the focused capabilities regression:1 pass. Gateway capability metadata retains explicit OpenCode timing limits. Configuration is no longer presented as an actual installed-binary observation. + +## Verdict + +The architecture, focused wire correction and per-Harness adaptation are coherent and avoid generic run-command HTTP wrapping. The same public protocol can expose honestly different native capabilities. Required missing real-component/publication evidence and the public Python YAML consumer gap prevent calling the full requested outcome complete. Keep relevant source PRs Draft until their actual gates are satisfied; do not publish a claimed fully validated six-Harness release from these local results. diff --git a/.agents/evidence/verify/2026-11-17-agents-api-reviews/protocol-round1.md b/.agents/evidence/verify/2026-11-17-agents-api-reviews/protocol-round1.md new file mode 100644 index 00000000..fbc9eeea --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-agents-api-reviews/protocol-round1.md @@ -0,0 +1,79 @@ +# Agents API protocol review — round 1 + +Date: 2026-11-17. Reviewer: protocol_audit. Result: PARTIAL; useful implementation, unresolved wire-shape defects and incomplete six-Harness/cloud acceptance. + +## Scope and evidence + +Reviewed template PR [311](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/pull/311), head `ee59a726bb04e9b67a79b1bcbbb0a528ced11ef1`, and its pinned runtime `b988d2a76057b6202d836ec329cc0bd90a572b26`. The root workspace checkouts are older and must not be substituted for these sources. PR 311 remains Draft/open and explicitly records missing PostgreSQL-backed cloud publication, retained-Session upgrade and model-turn acceptance. No cloud resources, model calls or OpenAI API requests were made by this review. + +The current official OpenAI API includes a real managed Agents API. Its [architecture](https://developers.openai.com/api/docs/guides/agents-api/architecture) runs the Codex harness at OpenAI; `self_hosted` describes the connected executor/environment. This project's entire Harness/model/tool loop runs in each Session Sandbox. The shared path spelling does not make the execution topology equivalent. + +## Conclusion + +Preserve one project protocol, `agent-sandbox-managed-agents/v1`, and make each template select its Harness. A common lifecycle, input, durable receipt, output, artifact and error contract is reasonable. Identical advertised capabilities across Harnesses are neither necessary nor truthful. Keep unavailable features explicitly rejected and described in capabilities. Do not market this as a full OpenAI implementation or universal OpenAI SDK endpoint. + +This is the newer managed implementation, not the earlier guest-only in-memory API. Its PostgreSQL control plane, durable submissions, native receipt/epoch checks, owner scoping and explicit uncertain/reconciliation outcomes address the most serious earlier reliability objections. They still need the actual cloud acceptance already required by the owner records. + +## Alignment matrix + +| Area | Official OpenAI contract | Current managed implementation | Assessment | +| --- | --- | --- | --- | +| Agent/session resources | Saved Agent configuration plus per-session overrides | Agent CRUD, saved configuration and per-session override; metadata-only session updates | Shared basic model; narrower settings | +| Creation/input | Create can include initial input or streaming; later input is asynchronous | 201 creation, 202 empty input acceptance with project receipt header; initial stream supported | Core HTTP behavior aligned; receipt is an explicit extension | +| Busy-session input | [Run/continue](https://developers.openai.com/api/docs/guides/agents-api/sessions) describes mid-turn steering | `active_turn_not_steerable` 409, separate explicit queue endpoint | Honest feature gap, not equivalent steering | +| Request formats | [Create reference](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/sessions/methods/create) includes environments, image inputs, tools/settings and more | String or user `input_text`; 256 KiB text; fixed self-hosted workspace, no none/openai_hosted branch | Deliberate subset; document limits and reject unsupported values | +| Input events | [Events create](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/sessions/subresources/events/methods/create) supports message/cancel/tool and approval results | Exactly one text-message or cancel event; no function result/approval workflow | Basic event envelope aligned; unsupported workflows remain explicit | +| Turns/items | [Turn reference](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/sessions/subresources/turns/methods/retrieve) has public identity, timestamps, status, error, agent/subagent and usage | Durable turns/items and specific-turn retrieval, but missing some existing same-name fields | Repair wire projection; see findings | +| Streams | [Event schema](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/sessions/subresources/events/methods/stream) includes typed events and embedded turns; [recovery](https://developers.openai.com/api/docs/guides/agents-api/sessions/events) uses saved state/items | Durable SSE with replay cursor, 20-second connections, explicit native/output gaps | Useful project extension; no claim SDK stream helpers transparently reconnect | +| Files/artifacts | [Files guide](https://developers.openai.com/api/docs/guides/agents-api/environments/files) distinguishes self-hosted provider files from OpenAI-hosted published artifacts | Multipart Gateway files, immutable input references, captured per-turn artifacts from project's own Sandbox | Useful managed feature; it is not native OpenAI self-hosted publication | +| Delete/close | [Delete reference](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/sessions/methods/delete) removes public Session, requires execution to stop first; physical cleanup may continue | 200 public deletion, busy 409, separate project close Operation retains results | Good semantic separation | +| Tools/settings/platform features | [Configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration) and [management](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage) expose tools, settings and required actions | capabilities explicitly set steering/functions/MCP/subagents/session_settings false; empty required_actions/vault_ids | No silent emulation; not full feature completeness | +| Harnesses | OpenAI-managed Codex | Config and guest bridge currently whitelist only codex/qwen-code | Six-Harness requested delivery not implemented yet | + +## Findings and minimal changes + +### P1 — Same-name Turn and in-progress event shapes are incomplete + +At the pinned SDK, `client-sdk/src/agent_sandbox/managed_agents/worker.py` lines 439–451 creates a public Turn without `agent_id`, `started_at` or `subagent_id`. `service.public()` converts timestamps only for Sessions, so Turn timestamps are floats. The OpenAI Turn schema exposes integer-second timestamps, Agent identity and nullable subagent identity. Its documented helpers use `event.turn.subagent_id` to distinguish root from subagent outcomes. + +More directly, `_ingest()` lines 479–486 strips the guest `turn` object from all forwarded events and does not replace it for `agent.session.turn.in_progress`; that same-name event's official schema requires a Turn object. This is avoidable even when arbitrary OpenAI SDK interoperability is out of scope. + +Minimal repair: record stable Agent identity and observed start time on new Turns; project nullable subagent identity; convert public Turn timestamps to integer seconds without changing internal precision; attach the host's public Turn to forwarded in-progress events. Never expose native guest Session/Turn identities. Add regressions for HTTP Turn retrieval and SSE Turn events, including saved Agent and inline Agent Sessions. Preserve old-record behavior explicitly rather than inventing a new identity on every read. + +Initial local reproduction attempt was blocked at import by missing Pydantic in system Python. A dedicated dependency environment is being prepared; this report is static evidence until that probe runs. + +### P2 — Capabilities should distinguish common contract from selected Harness + +`service.capabilities()` has global feature booleans, and `/v1/agents/runtimes` reports installed=true from configuration alone. That does not prove a binary exists in the target Guest or that a native mode supports continuation/stream detail. As the Harness set grows, publish concrete selected adapter features and stream granularity. Do not conflate “runtime configured”, “binary present” and “real task accepted”. + +The existing model-to-adapter binding is one-to-one. Independent `agents-api-{harness}` deployments naturally support the same model through different Harnesses without introducing ambiguous runtime routing into the public API. Keep model identity separate from template/Harness identity. + +### P1 — “Complete and usable” remains an acceptance result, not a route count + +Configuration currently admits only Codex/Qwen. The requested Qoder, Claude Code, OpenCode and DeepSeek Harness adapters need native version-pinned command mappings, same-session continuation, actual tool-produced artifacts, bounded streaming/output, process cancellation and own-resource cleanup. Existing CLI templates or `run command` access are not managed adapters. A deterministic fake CLI proves the envelope and control logic only. + +## Adversarial position + +Rejected alternative: forcing all six Harnesses to emulate every OpenAI feature would manufacture steering or approval semantics and expand this task into a different hosted platform. Rejected alternative: calling protocol equality sufficient while emitted same-name Turn/events omit required fields; these are low-cost concrete correctness fixes. Accepted boundary: one stable project protocol with a tested shared core and explicit per-Harness capabilities, plus documented OpenAI alignment/differences. + +Cross-review request sent to runtime_audit and harness_audit. This first report is not either of the user's required final two post-implementation review rounds. + +## Follow-up: concrete reproduction and approved repair + +The isolated dependency environment later ran the original source probe successfully: +Turn keys lacked `agent_id`/`started_at`/`subagent_id`, `created_at` was a float, +and the in-progress event keys lacked `turn`. All four added regressions failed +before the repair, including actual official OpenAI typed validation. + +Runtime review challenged inline snapshot identity, old-record migration and observed +start-time precision. The revised patch freezes an inline snapshot identity, preserves +saved identity without definition lookups, supplies old-record values only through +projection, and leaves unknown historical start times null. The runtime reviewer +accepted this scope and required the saved-definition update/delete counterexample. + +The resulting four regressions passed, including OpenAI 3.52.0 typed parsing and its +real local HTTP Turn retrieval/event-stream consumption. Existing managed tests had +91 passes and eight raw-socket failures; those failures are recorded separately and +are not converted into cloud/model or full-SDK interoperability passes. Owner records: +`python-sdk/.agents/notes/proposed/feature/2026-11-17-managed-turn-wire.md` and its +verification file. The user's two final review rounds are still pending. diff --git a/.agents/evidence/verify/2026-11-17-agents-api-reviews/runtime-round1.md b/.agents/evidence/verify/2026-11-17-agents-api-reviews/runtime-round1.md new file mode 100644 index 00000000..d64fe9c0 --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-agents-api-reviews/runtime-round1.md @@ -0,0 +1,55 @@ +# Managed Agents API runtime adversarial review — round 1 + +Date: 2026-11-17. Result: **PARTIAL; release remains blocked by required acceptance**. +Scope: read-only source/evidence review. No cloud resources, credentials, containers, package installations or model calls were created by this reviewer. + +## Fixed inputs + +- Template PR: https://github.com/Alibaba-Agent-Sandbox/awesome-templates/pull/311 ; observed open/Draft, head `ee59a726bb04e9b67a79b1bcbbb0a528ced11ef1`, base `52f7653bda0b6c6406207e28095ee09a87cb5018`. +- That template pins its Server to Python SDK `b988d2a76057b6202d836ec329cc0bd90a572b26`, archive SHA256 `abefcb1f16d7c87089d9d560d4f8ebd5787a140351553b84f970a171fdd18f68`; its Guest still installs published Server `0.4.0a7`. +- CLI current task source inspected from PR249 checkout, especially `src/providers/alicloud_express/resource_executor.ts`. +- Existing root checkouts and restored November 13 worktrees are older than PR311. They must not be used to assert what that PR does. Git dubious-ownership was handled per read command without changing global trust configuration. + +## Decision + +The current managed topology is reasonable for a supported subset: a stable Gateway, PostgreSQL public state/outbox, revision-pinned Workers, per-Session Sandbox, and a private receipt bridge. The fixed code has meaningful failure fences that should survive the Harness expansion. This review did not reproduce a new runtime correctness defect in those mechanisms; absence of a reproduced defect does not complete the cloud acceptance gate. + +Do not replace this bridge with a generic HTTP wrapper around a CLI command. Do not count each existing sandbox CLI template as an already supported hosted Agent API implementation. Keep one public protocol and per-adapter capability declarations, while validating every native process independently. + +## Evidence and findings + +| Priority | Finding | Evidence | Required action | +| --- | --- | --- | --- | +| Release blocker | New native-resource application has not passed final hosted PostgreSQL deployment, upgrade/retained-Session routing and real-model business acceptance. | PR311 Remaining acceptance explicitly says BLOCKED. `.agents/evidence/verify/2026-11-13-agents-api-native-resources.md` explicitly excludes fresh changed Server Docker build, FC candidate model task, stable alias/timer, historical Session continuation and full cloud cleanup. | Run a bounded real application deployment plus update of the same application, retaining one existing Session across update, and independently confirm owned cleanup. Keep Draft/unreleased until required gates pass. | +| Scope blocker for six Harnesses | The current stack admits only Codex and Qwen Code, with one compatible model credential shape. | `agents-api/server/bootstrap.py:28`; SDK `managed_agents/models.py`, `providers/alicloud_express/managed.py:34`, guest `server/managed.py:112`; each contains the two-adapter whitelist. | Add adapter-specific native invocation, event/error parsing, auth/protocol mapping and resume behavior through the shared bridge. Do not silently fall back to a different Harness. | +| Evidence boundary | November 12 real Qwen file tasks prove the previous local Guest, not the changed November 13 native-resource release recipe. | `.agents/evidence/verify/2026-11-12-agents-api-final-local-validation.md` explicitly calls its scope local Docker/real model and excludes joint FC E2E; November 13 record calls its changed checks local. | Retain these as history. Record new checks against the exact changed code/image. | +| Product gap, declared | Active steering, external functions/MCP/subagents and session settings are unavailable in the managed profile. | SDK `managed_agents/service.py:102` publishes `features` with these values false; `_enqueue` rejects a default input while a turn is active instead of silently queuing it. | Preserve honest subset declarations and documented errors. Same route names must not be described as complete OpenAI equivalence. Protocol reviewer is checking same-name wire structures separately. | +| Operational limitation, documented | Uncertain publication has no automatic rollback/resume. | `agents-api/scripts/release.py:296-365` records publishing phases and `main` changes uncertain publication to `requires_reconcile`; README explicitly documents retaining resources and inspecting status. | Retain fail-closed behavior. Validate failure recovery before stronger lifecycle claims; do not add broad retry semantics merely to make deployment green. | + +## Mechanisms reviewed and worth preserving + +1. **No blind execution replay.** Worker `_sent` is persisted before submission. After a failed POST it queries the original receipt, rather than submitting into a fresh runtime (`managed_agents/worker.py:310-371`). Guest epoch changes cause an explicit uncertain/frozen state. The receipt journal is committed before staging/launch (`server/managed.py:269`). +2. **Observation lease differs from execution stop.** A lost creating/submitting claim freezes for reconciliation. Host cancellation/timeout cannot itself claim a remote process stopped. `_close` requires backend destruction confirmation; guest `ProcessDomain` treats unknown/unreadable same-UID processes conservatively (`managed_agents/worker.py:91-180,611-662`; `server/managed_process.py`). +3. **Durable public history with honest native gaps.** Public events are committed before SSE delivery; oversized/native lost events become gap events. SSE cursors are Session-bound, auth is rechecked, and PostgreSQL Session gates order deletion against frame admission (`store.py:185,370`; `http.py:235-340`; `service.py:710`). This is not a claim that all native token/tool events survive guest restart. +4. **Admission/state identity fences.** PostgreSQL transaction advisory locks coordinate application mutation; every transaction checks the pinned database identity; global/revision drain fences new admission (`store.py:235-437`; `service.py:128-143`). This favors correctness at this scale; it is not a performance benchmark. +5. **Upgrade ownership and routing.** Recipe reserve/observed checks stable function identities; publication pins database identity, enables a new Dispatcher with the old/new Worker map, verifies a candidate before switching the stable Gateway alias. Old immutable Workers remain for their Sessions (`release.py:145-174,269-365`). CLI records replaced immutable templates and changed native function names as previous resources so deletion can remove them (`resource_executor.ts:233-234,291,339-367`). +6. **Credential placement.** Gateway sees business-token digest and state/internal control config; Worker sees selected model and sandbox credentials; guest forwarding is explicit. Business/internal keys are distinct, generated private values are reused, explicit process overrides are not copied to their local key store (`bootstrap.py`; `release.py:145-172`; provider `managed.py`). + +## Cross-review challenge + +The Harness reviewer proposed short-lived headless turns, preserving the same bridge/receipt/process-domain. This reviewer agrees, subject to actual native resume evidence and residual-process cleanup per Harness. OpenCode or another CLI that implicitly launches a daemon needs explicit owned-process lifecycle proof; choosing a daemon mode without it is not acceptable. DeepSeek Harness final `completed` must be combined with process exit status and stop confirmation, and cannot fabricate streamed token deltas. + +Protocol reviewer independently found potential same-name Turn/event wire gaps and is reporting those with exact source evidence. A documented feature subset is acceptable; an existing supported event missing fields required by its claimed shape is a separate issue and should be corrected with focused regressions. + +## Minimal real acceptance after implementation + +Use one controlled application/database and preserve ownership. Do not create a new database for every variant or review. + +- Build the exact changed Guest and Server images; verify immutable source/package provenance and non-root startup. +- Exercise public health/auth, create with initial input, explicit queue, active-input unsupported error, idempotent repeat/mismatch, real tool/file result, independent download/content assertion, event reconnect/cursor and cancel-stop confirmation. +- For each of six native Harnesses, verify two actual turns in the same native Session/workspace, original test repair plus artifact download, actual error mapping and process cleanup. A version command or simple model text response is insufficient. Native-login prerequisites are recorded as prerequisites, never replaced by another adapter. +- Update the same deployed application; continue a retained old Session through its pinned old Worker, create a new Session on the new Worker, verify stable URL, observe timer delivery, and check a failing candidate does not switch the stable alias. +- Close/delete Sessions and drain before removing owned FC roles/templates/images selected by task ownership; independently verify no owned live compute remains. Preserve the borrowed database/role/network and report ownership. +- Repeat the independent multi-agent final review twice after code changes; any changed fix gets its own recheck. Only then merge/release components that changed and satisfy their required gates. + +No tests were executed by this reviewer. Source/evidence inspection is not a runtime pass, and no new performance, security-isolation or SLA claim is made. diff --git a/.agents/evidence/verify/2026-11-17-current-template-consumer-boundary.md b/.agents/evidence/verify/2026-11-17-current-template-consumer-boundary.md new file mode 100644 index 00000000..b848c47c --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-current-template-consumer-boundary.md @@ -0,0 +1,44 @@ +# Verification: SDK template consumer boundary + +- Date: 2026-11-17 +- Result: PARTIAL +- Change: AGENTS.md, eight English/Chinese documentation pairs and the contributor-boundary + decision; no YAML runtime behavior changed. + +## Evidence + +Read the packaged source.json, schema and normalizer; the SDK still admits root +`sandbox/deployment/application` and consumes `sandbox.template/instance/start/ready`. +The current template owner instead admits `vars/sandbox/serving` with named resources. +`api/template.py` imports that older normalizer. `models/template.py` uses it for +discovery, and `models/managed_instance.py` constructs an older private snapshot. +Therefore synchronizing schema bytes alone would break additional consumers. + +Current template run.py files use ProviderSandbox.create and start_server directly. +The managed Express backend creates instances from explicit frozen settings and does +not pass a template.yaml to launch_template. The CLI named-resource engine uses its +own JavaScript consumer, without calling this Python parser. The mismatch is a real +SDK YAML/discovery migration gap; it does not block those explicit managed paths. + +## Commands and results + +- `rg` traced launch_template/template_contract callers in SDK, templates and CLI. +- Python inspected both schema root/property sets directly; mismatch confirmed. +- `bash scripts/check-repo-health.sh --quiet`: 106 PASS, one existing recommended + release-runbook warning, no failures. `make hygiene` and `git diff --check` passed. +- Updated workflow, field reference, architecture, build/deploy, authoring, SDK usage, + API reference and managed instance descriptions in both languages. +- Owner Issue309 remains open: https://github.com/Alibaba-Agent-Sandbox/awesome-templates/issues/309. + +## Not verified + +No code migration, new public YAML support, cloud resource operation, model execution +or package publication was performed by this documentation-only correction. The +underlying consumer gap remains open and must not be described as completed. + +## Scoped secret review + +The coordinator compared exact configured secret/endpoint values against six repository +working trees and the added diff. No new matching value was introduced. Existing +configured-domain baseline matches in the two sdk-usage language files predate this +change and remain unchanged; no endpoint value is recorded here or replaced globally. diff --git a/.agents/evidence/verify/2026-11-17-managed-harness-adapters.md b/.agents/evidence/verify/2026-11-17-managed-harness-adapters.md new file mode 100644 index 00000000..7aa4fc43 --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-managed-harness-adapters.md @@ -0,0 +1,91 @@ +# Verification: managed harness adapters + +- Date: 2026-11-17 +- Change: managed-harness-adapters proposal; client/server a8 candidate source. +- Result: PARTIAL +- Environment: Linux, CPython 3.12.13; initial native probes used Node 22.22.2. + +## What was verified + +Native invocation/session IDs, terminal outcome parsing and exact per-harness credential +names, plus standalone-server/client descriptor parity. The official DSH package is used. + +## Commands run + +- Server: `pytest -q tests/test_server/test_harness_adapters.py`: 15 passed. +- Client: `pytest -q tests/test_managed_harness.py`: 13 passed. +- Server: `mypy src/agent_sandbox/server --follow-imports=silent`: 61 files passed. +- Scoped `ruff check` and `ruff format`: passed after correcting import order and explicit zip behavior. +- Installed `@qoder-ai/qodercli@1.1.90`, `opencode-ai@1.19.5`, `@deepseek-ai/dsh@0.2.2-rc.1` + into an isolated npm prefix. Optional package install scripts were not required for initial probes. +- Real `qoder --version`, `opencode --version`, `dsh --version`: exact versions matched. +- Real Qoder/OpenCode/DSH headless help: passed; Qoder lacks max-turns and plan permission + flags in this exact version, so the implementation follows actual help. +- Real Qoder headless without credentials: exit 1, authentication required. No model called. +- Reinstalled both editable distributions without dependency changes after lockstep a8 metadata update. + +## Results + +| Scope | Result | Limit | +| --- | --- | --- | +| Native parser/invocation/credential unit cases | PASS | Fixtures are logic evidence, not model execution | +| Three native package versions/help | PASS | DSH full runtime requires supported Node >=24.9 | +| Qoder missing-authentication failure | PASS | Native PAT execution not verified | +| Full owner checks and post-change reviews | Pending | Recorded separately after execution | +| Real six-harness model/FC/PostgreSQL/upgrade acceptance | BLOCKED | Not established by these local probes | + +An initial combined-root pytest invocation failed with package conftest name collision; +the suites were rerun from their owning package directories. An initial direct-file mypy +invocation found the package under two module names; the owning-package command passed. + +## Cleanup + +No cloud resources created by these checks. Native probes use isolated temporary homes; +their outputs contain no credentials. Installation packages are local verification tools. + +## Not verified + +No claim of all providers/models, native account permission, successful model task, hosted +upgrade or released a8 is made. Required real-component gates remain explicit. + +## Final local validation checkpoint + +The first full `make test` server run finished with 887 passed, 1 skipped and 7 failed. +Four failures were expected runtime-directory snapshots still listing five adapters; +the new three entries require explicit eight-entry expectations while the independent +local API's supported-runtime restrictions stay unchanged. One failure was an incomplete +verification environment: uv's venv had no pip, so the package-listing endpoint returned +no pytest package. Installing pip in the verification venv resolved that prerequisite. +Two failures were malformed raw HTTP probes receiving 501/502 instead of the required 400. + +Executed full `make ci` after those corrections. Its server checkpoint finished with +**892 passed, 1 skipped, 3 failed** and exit 2. Two failures remained the raw HTTP cases +above. The third was one additional old five-entry default-adapter expectation, corrected +after that full run had imported its test module. The final source was then checked with +`pytest -q tests/test_server/test_harness_adapters.py +tests/test_server/test_routes_agents.py::TestRoutesAgents::test_aliases_unknown_adapter_and_default`: +**22 passed** (including the new permissions and completion-only-tool regressions). +This targeted result does not turn the earlier full-suite checkpoint into a full pass +on the final tree. A previous five-case runtime-directory/pip check separately passed +the other corrected expectations; the broader server run no longer failed them. + +The independently executed full client suite finished with **2657 passed, 27 skipped, +8 failed**, exit 1. Failures were four private FC-role octet-stream requests timing out, +one partial-body timeout and three raw HTTP SSE probes receiving 501. The owner retains +the failed assertions and a [project-independent stdlib HTTP control](2026-11-17-raw-http-environment.md) +showing the same raw 501/header-only timeout behavior without importing this project. +These environmental observations do not constitute passing product assertions. + +Remaining local gates were executed separately because `make ci` stops at its first failure: + +- Final `make lint`, `make format-check`, `make typecheck`: both packages PASS; + server 99 formatted files/61 typechecked files, client 267 formatted files/118 typechecked files. +- `make build`: PASS for both a8 wheels and sdists. +- `make dist-check`: PASS, including four twine checks, typed markers, fresh client-only + import/real HTTP, optional-server command registration, combined wheel installation and pip check. +- `bash scripts/check-repo-health.sh`: 106 PASS, 1 existing recommended-release-guide warning, + 0 FAIL. `make hygiene`: PASS. New evidence helper also passes scoped Ruff checks/formatting. +- [Installed OpenCode/DSH two-turn continuation and the failed real-model preflight](2026-11-17-native-harness-components.md) + are recorded independently from these suites. + +No full local CI pass, cloud/model acceptance, PyPI release or image publication is claimed. diff --git a/.agents/evidence/verify/2026-11-17-managed-turn-wire.md b/.agents/evidence/verify/2026-11-17-managed-turn-wire.md new file mode 100644 index 00000000..be39cce0 --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-managed-turn-wire.md @@ -0,0 +1,75 @@ +# Verification: Managed Turn wire projection + +- Date: 2026-11-17 +- Change: [proposed decision](../../notes/proposed/feature/2026-11-17-managed-turn-wire.md) +- Result: PARTIAL +- Package under test: initial editable client/server 0.4.0a7 development source; + final capability regression uses the coordinated 0.4.0a8 candidate source. Neither + source run is a published package validation. +- Environment: Linux, CPython 3.12.13; OpenAI 3.52.0; SQLite and local PostgreSQL. + No cloud credentials or model credentials were used by this verification. + +## What was verified + +Managed Turn identities, timestamps and lifecycle event payloads now agree across +retrieval, list and durable events. Inline snapshots keep a Session-scoped identity; +saved Agent update/deletion cannot change a frozen Session. Unknown historical start +times remain null and public projection does not rewrite precise private state. + +## Commands run + +Commands ran from this repository using its dedicated environment: + +- `pytest client-sdk/tests/test_managed_wire.py -q`: before fix, four failures; + after fix and the added real-HTTP exercise, four passes (1.69 seconds). The final + five-test run including configured-Harness capability timing passed (1.38 seconds). +- `pytest client-sdk/tests/test_managed_agents.py client-sdk/tests/test_managed_entrypoint.py client-sdk/tests/test_managed_wire.py -q`: + 91 passed, eight failed (54.45 seconds). The failures are listed below, not omitted. +- A focused `pytest client-sdk/tests/test_managed_agents.py -q -x --tb=short` independently + reproduced the first raw-socket oversized-header timeout (32 passed, one failed). +- Final `ruff check` on the three changed Python files passed; `ruff format` applied + only to those files. Targeted `mypy` checked both changed source files successfully. +- `bash scripts/check-repo-health.sh`: 106 pass, one existing recommended release-runbook + warning, zero failures. `make hygiene` and `git diff --check` passed. + +## Results + +| Scenario | Result | Evidence scope | +| --- | --- | --- | +| Missing Turn identity and incomplete in-progress event reproduced | PASS | Four new regressions fail on original implementation | +| Fixed projection, saved-definition mutation, retained old records | PASS | New regression suite | +| Official OpenAI Turn and in-progress/completed event typed parsing | PASS | Local installed OpenAI 3.52.0, no OpenAI network calls | +| Official SDK Turn retrieval and durable SSE terminal consumption | PASS | Actual local authenticated HTTP listener and SDK client | +| Existing managed regressions | PARTIAL | 91 pass; eight raw-socket failures | +| New six-Harness and real cloud publication/upgrade/model acceptance | Not run here | Coordinated delivery gate remains open | + +## Problems found + +The existing raw-socket tests failed independently of the changed projection: + +- Four private-invocation oversized-body header-only probes timed out waiting for 413 + (Dispatcher/Worker, SQLite/PostgreSQL). +- The partial-body/read-timeout probe timed out waiting for connection closure. +- The raw-socket SSE chunk probe and two post-header-failure probes received HTTP 501. + +Ordinary local HTTP/SDK requests and real local database scenarios passed. This run +was followed by a [project-independent stdlib control](2026-11-17-raw-http-environment.md), +which reproduced raw GET501 and header-only POST timeout while http.client and urllib +returned200/ok against the same server. This establishes an environment distinction, +without identifying its interception implementation. All eight failures remain FAIL. No assertion was weakened and no product HTTP code was changed +to mask them. Two preliminary commands used an incorrect extra/path; corrected +commands installed `managed-agents` and ran against the intended source paths. + +## Cleanup + +Temporary databases and listeners were owned by the tests and closed by their cleanup +blocks. No cloud resource, model job or OpenAI-hosted Session was created. + +## Not verified + +The new recipe's PostgreSQL-backed FC publication, retained Session upgrade, actual +Harness/model behavior and cloud deletion remain separate mandatory delivery gates. +Passing these local resource/event projections does not establish arbitrary OpenAI +SDK compatibility, hosted OpenAI Harness behavior or complete Agents API feature parity. + +Commit-time secret hook initially rejected a synthetic loopback test token assignment. The fixture was explicitly named with the documented placeholder marker; no real credential was present. The hook remains enabled and the wire regression was rerun. diff --git a/.agents/evidence/verify/2026-11-17-native-harness-components.md b/.agents/evidence/verify/2026-11-17-native-harness-components.md new file mode 100644 index 00000000..36b52702 --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-native-harness-components.md @@ -0,0 +1,73 @@ +# Verification: installed native Harness components + +- Date: 2026-11-17 +- Result: PARTIAL +- Source: client/server a8 candidate; official OpenCode 1.19.5 and DeepSeek Harness + 0.2.2-rc.1 packages; Qoder CLI 1.1.90. +- Environment: Linux, Python 3.12.13; official Node 24.16.0 archive verified independently + against the checksum used by the template image. + +## Native CLI and continuation + +Installed the actual npm packages in an isolated local prefix. Exact version probes passed +for `qoder`, `opencode` and `dsh`; the installed package's headless help was inspected. +The actual Qoder version lacks a max-turns flag and plan permission mode, so the adapter +uses supported arguments rather than copying an incompatible documentation example. +Qoder without credentials rejected with exit 1 and a native authentication error. No PAT +was supplied or native Qoder model task claimed. + +Executed both OpenCode and official DSH through their new SDK adapters against one bounded +loopback HTTP server with deterministic model responses. Each CLI completed two invocations +using the exact same native session ID. The second actual model HTTP request contained +the first turn's marker and the follow-up prompt. Both processes exited zero, and parsers +observed successful native terminal results. The DSH test used its Messages transport and +explicit DEEPSEEK_BASE_URL; it did not substitute the older repository-owned DeepSeek loop. + +Reproduction, using caller-supplied installed binary directories: + +```bash +python .agents/evidence/verify/2026-11-17-native-harness-components/loopback.py \ + --native-bin "$NATIVE_BIN" --node-bin "$NODE_BIN" +``` + +- [Sanitized result](2026-11-17-native-harness-components/loopback-result.jsonl) +- [Reproduction](2026-11-17-native-harness-components/loopback.py) +- Native event envelope fixtures under `server-sdk/tests/fixtures/native-harnesses/` + normalize IDs, paths and timestamps and are covered by parser regression tests. + +This proves native command construction, protocol transport and persisted continuation +against a controlled model fixture. It does not prove model quality, provider account +permissions, generated business artifacts, cloud Sandbox execution or FC hosting. + +## Attempted real-model acceptance + +The owner authorized one existing-endpoint discovery followed by one two-turn OpenCode +file task, without creating cloud resources or trying a model matrix. The credentials +were loaded only in the child process from the existing gitignored configuration, with +neither credential nor base URL printed or saved. The single `GET /models` attempt failed +with `ConnectError`. No model was selected and no task was submitted. Generated-file and +independent-computation checks therefore remain unrun. No process belonging to the attempt +remained after cleanup. + +[Sanitized failed preflight](2026-11-17-native-harness-components/real-model-result.json) +retains the failure and its unrun downstream checks. + +## Review findings addressed + +OpenCode's actual JSON interface reports tool use at completion. Its parser now emits an +atomic completion record; the runtime publishes terminal item status immediately and +does not fabricate a live tool start or a per-tool timer. Native duration is retained +when present. Public adapter capabilities report completion-only tool events and no live +per-tool timeout for this interface. Overall run deadlines and owned-process cleanup remain. + +Independent review also found that mapping `workspace_write` to a blanket OpenCode allow +policy would widen explicit permission intent. The adapter now rejects that unsupported +mode rather than treating it as full access; read-only and full-access are distinct. + +## Cleanup and limits + +Only local CLI processes and temporary workspaces were used. The reproduction closes its +loopback listener and removes its owned temporary homes after normal completion. No cloud +resources were created. Six native real-account/model paths, generated artifacts, active +tool cancellation, current FC/PostgreSQL deployment/upgrade and published image/package +verification remain separate required acceptance work. diff --git a/.agents/evidence/verify/2026-11-17-native-harness-components/loopback-result.jsonl b/.agents/evidence/verify/2026-11-17-native-harness-components/loopback-result.jsonl new file mode 100644 index 00000000..afc60dbb --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-native-harness-components/loopback-result.jsonl @@ -0,0 +1,6 @@ +{"adapter": "opencode", "turn": 0, "exit": 0, "native_session_present": true, "same_native_session": true, "event_kinds": ["session", "message", "usage", "result"], "terminal_ok": true} +{"adapter": "opencode", "turn": 1, "exit": 0, "native_session_present": true, "same_native_session": true, "event_kinds": ["session", "message", "usage", "result"], "terminal_ok": true} +{"adapter": "opencode", "request_count": 3, "resume_history_contains_marker": true} +{"adapter": "deepseek-harness", "turn": 0, "exit": 0, "native_session_present": true, "same_native_session": true, "event_kinds": ["session", "message", "usage", "result"], "terminal_ok": true} +{"adapter": "deepseek-harness", "turn": 1, "exit": 0, "native_session_present": true, "same_native_session": true, "event_kinds": ["session", "message", "usage", "result"], "terminal_ok": true} +{"adapter": "deepseek-harness", "request_count": 3, "resume_history_contains_marker": true} diff --git a/.agents/evidence/verify/2026-11-17-native-harness-components/loopback.py b/.agents/evidence/verify/2026-11-17-native-harness-components/loopback.py new file mode 100644 index 00000000..20ed923d --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-native-harness-components/loopback.py @@ -0,0 +1,206 @@ +# Real installed native binaries; placeholder credentials are sent only to loopback. +import argparse +import json +import os +import shutil +import subprocess +import tempfile +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path + +from agent_sandbox.server.agents.adapters import AdapterRegistry, TurnContext +from agent_sandbox.server.agents.config import AgentSpec, ProviderSpec + +arguments = argparse.ArgumentParser( + description=( + "Real native CLI transport and resume against a deterministic local model; " + "not real-model acceptance." + ) +) +arguments.add_argument("--native-bin", required=True) +arguments.add_argument("--node-bin", required=True) +options = arguments.parse_args() +requests = [] + + +class Handler(BaseHTTPRequestHandler): + def log_message(self, *args): + pass + + def do_GET(self): + body = json.dumps( + { + "object": "list", + "data": [{"id": "test-model", "object": "model", "owned_by": "test"}], + } + ).encode() + self.send_response(200) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def do_POST(self): + body = json.loads(self.rfile.read(int(self.headers["Content-Length"]))) + requests.append(body) + self.send_response(200) + self.send_header("Content-Type", "text/event-stream") + self.end_headers() + if "messages" in self.path and "chat/completions" not in self.path: + events = [ + ( + "message_start", + { + "type": "message_start", + "message": { + "id": "msg_probe", + "type": "message", + "role": "assistant", + "model": "test-model", + "content": [], + "stop_reason": None, + "usage": {"input_tokens": 5, "output_tokens": 0}, + }, + }, + ), + ( + "content_block_start", + { + "type": "content_block_start", + "index": 0, + "content_block": {"type": "text", "text": ""}, + }, + ), + ( + "content_block_delta", + { + "type": "content_block_delta", + "index": 0, + "delta": {"type": "text_delta", "text": "Native probe answer"}, + }, + ), + ("content_block_stop", {"type": "content_block_stop", "index": 0}), + ( + "message_delta", + { + "type": "message_delta", + "delta": {"stop_reason": "end_turn", "stop_sequence": None}, + "usage": {"output_tokens": 3}, + }, + ), + ("message_stop", {"type": "message_stop"}), + ] + self.wfile.write( + "".join( + "event: " + kind + "\ndata: " + json.dumps(event) + "\n\n" + for kind, event in events + ).encode() + ) + else: + for delta, finish in [ + ({"role": "assistant", "content": "Native probe answer"}, None), + ({}, "stop"), + ]: + self.wfile.write( + ( + "data: " + + json.dumps( + { + "id": "chat_probe", + "object": "chat.completion.chunk", + "created": 1, + "model": "test-model", + "choices": [{"index": 0, "delta": delta, "finish_reason": finish}], + } + ) + + "\n\n" + ).encode() + ) + self.wfile.write(b"data: [DONE]\n\n") + + +server = ThreadingHTTPServer(("127.0.0.1", 0), Handler) +threading.Thread(target=server.serve_forever, daemon=True).start() +for name in ["opencode", "deepseek-harness"]: + adapter = AdapterRegistry().get(name) + root = Path(tempfile.mkdtemp(prefix="native-harness-loopback-")) + (root / "turn").mkdir() + spec = AgentSpec( + name="probe", + runtime=name, + model="test-model", + provider=ProviderSpec( + base_url="http://127.0.0.1:" + str(server.server_port) + "/v1", + api_key="placeholder-loopback-only", + ), + permissions="full_access", + ) + sid = None + for turn in range(2): + ctx = TurnContext( + spec=spec, + prompt="Remember native-resume-marker" if turn == 0 else "Recall the previous marker", + workdir=str(root), + turn_dir=str(root / "turn"), + native_session_id=sid, + ) + inv = adapter.build_invocation(ctx) + for f in inv.files: + Path(f.path).write_bytes(f.content) + env = { + "PATH": options.node_bin + + os.pathsep + + options.native_bin + + os.pathsep + + "/usr/local/bin:/usr/bin:/bin", + "HOME": str(root / "home"), + "CI": "1", + "LANG": "C.UTF-8", + **inv.env, + } + try: + r = subprocess.run( + inv.argv, input=inv.stdin, cwd=root, env=env, capture_output=True, timeout=25 + ) + except subprocess.TimeoutExpired: + print( + json.dumps({"adapter": name, "turn": turn, "timeout": True, "exit_confirmed": True}) + ) + break + parser = adapter.new_parser(ctx) + events = [e for line in r.stdout.decode().splitlines() for e in parser.feed(line)] + events += parser.finish(r.returncode) + previous = sid + sid = next((e.text for e in events if e.kind == "session"), sid) + print( + json.dumps( + { + "adapter": name, + "turn": turn, + "exit": r.returncode, + "native_session_present": bool(sid), + "same_native_session": previous is None or sid == previous, + "event_kinds": [e.kind for e in events], + "terminal_ok": any(e.kind == "result" and e.data.get("ok") for e in events), + } + ) + ) + if r.returncode or not sid: + break + print( + json.dumps( + { + "adapter": name, + "request_count": len(requests), + "resume_history_contains_marker": any( + "Recall the previous marker" in json.dumps(r) + and "native-resume-marker" in json.dumps(r) + for r in requests + ), + } + ) + ) + requests.clear() + shutil.rmtree(root) +server.shutdown() +server.server_close() diff --git a/.agents/evidence/verify/2026-11-17-native-harness-components/real-model-result.json b/.agents/evidence/verify/2026-11-17-native-harness-components/real-model-result.json new file mode 100644 index 00000000..692d813e --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-native-harness-components/real-model-result.json @@ -0,0 +1,13 @@ +{ + "harness": "opencode", + "native_version": "1.19.5", + "model_source": "existing authorized endpoint", + "scope": "local native CLI with real model, no cloud sandbox or hosted FC", + "models_discovery": false, + "turns": [], + "independent_checks": [], + "failure_class": "ConnectError", + "owned_processes_after_exit": 0, + "owned_processes_after_cleanup": 0, + "pass": false +} \ No newline at end of file diff --git a/.agents/evidence/verify/2026-11-17-raw-http-environment.md b/.agents/evidence/verify/2026-11-17-raw-http-environment.md new file mode 100644 index 00000000..7501f392 --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-raw-http-environment.md @@ -0,0 +1,11 @@ +# Verification: project-independent raw HTTP control + +Date: 2026-11-17. Result: PARTIAL — independent environment distinction reproduced; this does not mark the failed managed HTTP tests as passed. + +## Scope and execution + +The [stdlib-only control](2026-11-17-raw-http-environment/control.py) imports no project modules and starts one temporary loopback ThreadingHTTPServer. Its GET handler returns 200/ok; its POST handler immediately returns413 without reading the request body. Python3.13.13 executed `python control.py` with exit0 in2.60 seconds. It shuts down and closes its server in finally. No cloud resources, model calls or secrets were used. + +Actual [result](2026-11-17-raw-http-environment/result.json): raw socket GET received HTTP/1.1 501 Not Implemented, while the same server through stdlib http.client and urllib with ProxyHandler({}) returned200/ok. A raw header-only POST with oversized Content-Length timed out after2 seconds instead of delivering the handler413. These reproduce the relevant raw managed-test symptoms outside the project. + +This supports treating raw-transport failures separately from the changed managed Turn projection. It does not identify the network/interception implementation or prove all raw HTTP product behavior correct. The eight failing tests remain FAIL in the managed wire verification; do not weaken assertions or claim a complete suite pass. diff --git a/.agents/evidence/verify/2026-11-17-raw-http-environment/control.py b/.agents/evidence/verify/2026-11-17-raw-http-environment/control.py new file mode 100644 index 00000000..51284bcd --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-raw-http-environment/control.py @@ -0,0 +1,20 @@ +import http.server,socket,threading,json,http.client,urllib.request +class H(http.server.BaseHTTPRequestHandler): + def log_message(self,*a):pass + def do_GET(self): + self.send_response(200);self.send_header('Content-Length','2');self.end_headers();self.wfile.write(b'ok') + def do_POST(self): + self.send_response(413);self.send_header('Content-Length','0');self.end_headers() +s=http.server.ThreadingHTTPServer(('127.0.0.1',0),H);threading.Thread(target=s.serve_forever,daemon=True).start() +result={} +try: + port=s.server_port + for label,request in [('get',b'GET / HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n'),('header-only-post',b'POST / HTTP/1.1\r\nHost: localhost\r\nContent-Length: 999999999\r\nConnection: close\r\n\r\n')]: + with socket.create_connection(('127.0.0.1',port),timeout=2) as c: + c.settimeout(2);c.sendall(request) + try:result['raw-'+label]=c.recv(4096).decode(errors='replace').split('\r\n')[0] + except TimeoutError:result['raw-'+label]='TimeoutError' + c=http.client.HTTPConnection('127.0.0.1',port,timeout=2);c.request('GET','/');r=c.getresponse();result['httpclient-get']={'status':r.status,'body':r.read().decode()};c.close() + opener=urllib.request.build_opener(urllib.request.ProxyHandler({}));r=opener.open(f'http://127.0.0.1:{port}/',timeout=2);result['urllib-no-proxy-get']={'status':r.status,'body':r.read().decode()} +finally:s.shutdown();s.server_close() +print(json.dumps(result,indent=2)) diff --git a/.agents/evidence/verify/2026-11-17-raw-http-environment/result.json b/.agents/evidence/verify/2026-11-17-raw-http-environment/result.json new file mode 100644 index 00000000..e4df0879 --- /dev/null +++ b/.agents/evidence/verify/2026-11-17-raw-http-environment/result.json @@ -0,0 +1,13 @@ +{ + "scope": "Project-independent stdlib HTTP comparison; no agent_sandbox import; no cloud resources", + "raw-get": "HTTP/1.1 501 Not Implemented", + "raw-header-only-post": "TimeoutError", + "httpclient-get": { + "status": 200, + "body": "ok" + }, + "urllib-no-proxy-get": { + "status": 200, + "body": "ok" + } +} diff --git a/.agents/notes/proposed/feature/2026-11-17-managed-harness-adapters.md b/.agents/notes/proposed/feature/2026-11-17-managed-harness-adapters.md new file mode 100644 index 00000000..08cc0738 --- /dev/null +++ b/.agents/notes/proposed/feature/2026-11-17-managed-harness-adapters.md @@ -0,0 +1,68 @@ +# Decision: Native harness adapters behind one managed protocol + +Status: proposed + +## Problem + +Managed Agents accepts only Codex and Qwen Code. Renamed templates cannot use Claude, +Qoder, OpenCode or official DeepSeek Harness, and the universal OPENAI credential mapping +would misrepresent their native authentication and model protocols. + +## Decision + +Add Qoder 1.1.90, OpenCode 1.19.5 and official DeepSeek Harness 0.2.2-rc.1 invocation/parser +adapters. Make existing Claude Code available through the managed bridge. Keep the six +canonical adapter IDs behind one durable Session/submission contract. Each Worker binds +one model and harness and injects exactly its known native environment names. Qoder uses +a native PAT and no fake model endpoint. DSH uses its official Messages route and native +headless session restoration, rather than the older project-owned DeepSeek tool loop. + +The client maps credentials using a dependency-free model helper. The standalone server +retains its own fixed descriptors because it must remain installable without the client; +a parity test checks the two descriptors. Native parser terminal checks supplement actual +process exit and existing process-domain/reconciliation rules. New adapters remain +experimental pending real account/model and hosting acceptance. + +OpenCode's native JSON emits tools only at completion. Record completed items atomically, +declare completion-only tool events and no live per-tool timeout, and preserve the overall +run deadline. Reject its unsupported workspace_write mode instead of widening permissions. + +## API Design + +Internal Worker model binding remains `{adapter, model, apiKey, baseUrl}`. `baseUrl` is +required for model APIs and omitted/empty for Qoder's native service. The existing public +managed API envelopes do not change. Canonical adapter IDs are `codex`, `qwen-code`, +`claude-code`, `qoder`, `opencode` and `deepseek-harness`. + +## Alternatives considered + +- Copy six complete Gateway implementations: duplicates state/lifecycle behavior. +- Wrap all CLIs as generic text commands: loses native session/error/tool semantics. +- Treat all credentials as OPENAI keys: breaks native Qoder/Claude/DeepSeek authentication. +- Import client configuration from the standalone server: breaks package independence. + +## Dependencies + +Existing stdlib-only AgentRuntime adapter boundary and managed bridge; official native CLI +packages installed by each template. Client/server source metadata moves together to a8; +this is a candidate, not proof that a8 exists on PyPI. Existing release artifacts remain unchanged. + +## Test Strategy + +Invocation/parser/error/resume/credential/parity unit tests; installed real CLI version/help +and unauthenticated rejection; native subprocesses against bounded loopback model fixtures +where feasible, clearly separated from real-model acceptance. Required owner suite, lint, +typecheck, build/packaging and real cloud/model checks remain necessary. + +## Acceptance criteria + +Six bindings preserve one protocol and exact native identity. Credentials remain out of argv, +generated files and Gateway public responses. Native nonzero, missing terminal, malformed +configuration and unconfirmed stop never become success. Each real-model path demonstrates +two turns, independent generated artifact execution, cancellation and owned cleanup. Revised +FC/PostgreSQL deployment and old-session upgrade pass before full delivery is claimed. + +## Evidence + +- [Verification](../../../evidence/verify/2026-11-17-managed-harness-adapters.md). +- [Installed native components and real-model preflight](../../../evidence/verify/2026-11-17-native-harness-components.md). diff --git a/.agents/notes/proposed/feature/2026-11-17-managed-turn-wire.md b/.agents/notes/proposed/feature/2026-11-17-managed-turn-wire.md new file mode 100644 index 00000000..a99ce90b --- /dev/null +++ b/.agents/notes/proposed/feature/2026-11-17-managed-turn-wire.md @@ -0,0 +1,72 @@ +# Decision: Preserve managed Turn identities and lifecycle event shapes + +Status: proposed + +## Problem + +Managed Turn retrieval omitted the Agent and root-agent identity fields and exposed +fractional timestamps. The in-progress lifecycle event dropped its native Turn without +replacing it with the host's public Turn. Consumers of the existing same-name resources +could not consistently associate lifecycle events with retrieved results. + +## Decision + +Keep public Session/Turn identities separate from the guest runtime. Freeze an inline +Agent snapshot identity with its Session, preserve saved Agent identity, and include +that same identity on each Turn. Inline identities identify snapshots, not separately +retrievable saved Agent definitions. Project integer Unix seconds without reducing +internal timestamp precision. Reconstruct only the in-progress Turn event's embedded +Turn from host state; terminal events use the same public projection. + +For retained older records, derive the same inline snapshot identity from their stable +Session identity, and project unknown start time as null. Do not rewrite historical +records or look up a subsequently changed/deleted saved Agent definition. + +## API Design + +`public(row, *, session=None) -> dict[str, Any]` adds Session context when projecting +older Turns. Public Turns carry `agent_id`, `subagent_id: null`, and integer/null lifecycle +timestamps. New Turns prefer native start time; if absent, the Worker records the first +execution observation time. No steering, subagent or external tool ability is added. Capabilities retain the adapter +ID list and add per-configured-adapter stream/tool timing and per-tool-timeout +support. OpenCode completed-only tool events do not claim an enforceable per-tool deadline. +Runtime inventory identifies configured adapters and returns `installed: null`; a Gateway +cannot inspect a Guest that does not yet exist. + +## Alternatives considered + +- **Leave same-name shapes incomplete** — rejected because a concrete in-progress + event cannot be consumed using its documented embedded Turn. +- **Resolve the current saved Agent during each read** — rejected because a Session + freezes its original configuration and survives later definition update/deletion. +- **Create saved definitions for all inline configurations** — rejected because it + silently changes Agent collection and retention behavior. +- **Use the read time as the start time of older Turns** — rejected because that + would invent a lifecycle observation that never occurred. + +## Dependencies + +The existing managed service, worker, database and HTTP listener. The optional OpenAI +package is used only for a local interoperability regression, never as a runtime +requirement or evidence of complete SDK/API parity. + +## Test Strategy + +Reproduce the failure before fixing it. Verify stable inline/saved identities, immutable +legacy projection, private clock precision, and matching retrieved/event Turn shapes. +Optionally validate with official OpenAI typed models and use that SDK against a real +local HTTP listener and durable event replay. Run the owning repository's full gates; +retain cloud/model and raw-socket failures separately. + +## Acceptance criteria + +- New and retained Turns expose stable frozen Agent identity and root-agent identity. +- Retrieval and in-progress/terminal events agree on host Turn and Session identity. +- Public timestamps use integer seconds; unknown historical start times remain null. +- Saved Agent update/deletion does not change an existing Session's snapshot identity. +- Regression, lint, type/health/hygiene gates pass, and real managed cloud acceptance is + recorded before full delivery is claimed. + +## Evidence + +- [Verification](../../../evidence/verify/2026-11-17-managed-turn-wire.md). diff --git a/.agents/notes/proposed/process/2026-11-17-current-template-consumer-boundary.md b/.agents/notes/proposed/process/2026-11-17-current-template-consumer-boundary.md new file mode 100644 index 00000000..6a1bf96f --- /dev/null +++ b/.agents/notes/proposed/process/2026-11-17-current-template-consumer-boundary.md @@ -0,0 +1,57 @@ +# Decision: State the actual SDK named-resource consumer boundary + +Status: proposed + +## Problem + +The contributor entry described an earlier single-Sandbox draft as the current YAML +contract. The template owner now defines named Sandbox/Serving resources, but this +SDK's packaged normalizer and public launch convenience still consume the older +shape. Rewording documentation must not claim an unimplemented consumer migration. + +## Decision + +Correct AGENTS.md to identify the current owner contract and the actual working +runtime paths: generated run.py uses prepared references and ProviderSandbox, while +managed roles consume explicit private configuration. Mark the older YAML consumer +as an unresolved migration, including its use by private instance validation. +A schema-byte synchronization alone is unsafe; migrate consumers and tests together. +Update the paired user guides/reference/design descriptions to the same actual boundary, +remove current-source examples using obsolete service/instance wrappers, and preserve +the independent prepared SDK API. This documentation increment does not close the +remaining consumer criteria in the template owner Issue309. + +## API Design + +N/A — this decision does not involve API changes. + +## Alternatives considered + +- **Claim named-resource support after editing the entry point** — rejected because + neither the normalizer nor launcher currently consumes that resource shape. +- **Replace only schema files** — rejected because launch and managed instance + validation still construct and consume the earlier shape. +- **Expand this wording fix into another deployment engine** — rejected because the + new template runners and managed backend already use explicit runtime APIs. + +## Dependencies + +The template owner defines current configuration: +https://github.com/Alibaba-Agent-Sandbox/awesome-templates/pull/311. +The SDK's local immutable source lock identifies the earlier consumer contract. + +## Test Strategy + +Trace imports/callers in SDK, template runners and CLI; check that the contributor +entry matches those paths. Run repository record/link/hygiene checks. This documentation +correction does not establish new YAML, cloud or model support. + +## Acceptance criteria + +- AGENTS.md describes named resources without claiming the old SDK parser accepts them. +- The functioning explicit-runtime paths and remaining migration are clear. +- The owning YAML migration Issue remains open until actual consumer criteria land. + +## Evidence + +- [Verification](../../../evidence/verify/2026-11-17-current-template-consumer-boundary.md). diff --git a/AGENTS.md b/AGENTS.md index c66c7b58..0ef10718 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -169,18 +169,24 @@ Every exception carries: `code`, `message`, `suggestion`, `docs_url` (populated ### Template startup and operation model -Templates use the canonical `specVersion: 1` contract, `sandbox.services`, -`sandbox.start` and `sandbox.ready`. The immutable owner source/schema lock is in -`client-sdk/src/agent_sandbox/template_contract/source.json`; synchronize those bytes, -never maintain another parser or invent an expression evaluator. Native Devs parses -expressions; Python consumes literals or an already resolved v1 snapshot. - -Canonical `contracts/launch-v1.json` and `launch-vectors.json` have byte-identical -package copies. `launch_template` consumes prepared references and instance values; -Python does not build source. Serving/application inputs require the deployment -orchestrator. Server policy validation remains an independent runtime API. -Managed instance settings exclude every environment value; only Worker private -configuration supplies those values, with reserved controls protected. +Current template resources use `specVersion: 1`, named `sandbox..template` +resources and native `serving..props`. The CLI owns their construction, +expression evaluation, resource references and deployment. The generated template +`run.py` creates a dynamic instance from its prepared reference through +`ProviderSandbox.create` and starts its application explicitly. + +The SDK's packaged `template_contract/source.json` and `launch_template` still target +an earlier single-Sandbox draft. They do not consume the current named resource +files; do not document them as current `template.yaml` support. Managed instance +validation also consumes that older private snapshot today, so replacing schema +bytes alone is not a complete migration. Preserve the immutable source lock until +all affected consumers and regressions are migrated together. Never introduce a +second expression evaluator: native Devs owns expressions. + +Managed Gateway/Worker/Dispatcher roles consume their explicit private runtime +configuration, not the old public YAML launcher. Instance settings exclude secret +environment values; only Worker private configuration supplies those values, with +reserved controls protected. Server policy remains an independent runtime document. --- diff --git a/CHANGELOG.md b/CHANGELOG.md index 223eea3a..28994370 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] +### Added + +- Add experimental native Qoder, OpenCode and official DeepSeek Harness adapters, and + connect Claude Code to the managed bridge. All six harnesses share Session APIs with + explicit native credentials and exact resume identities. Client/server a8 remains a + source candidate until separately published. / 新增实验性的 Qoder、OpenCode、官方 + DeepSeek Harness 原生适配,并将 Claude Code 接入托管桥;六种 Harness 共用 Session API, + 凭据按原生协议映射并精确续接会话,a8 发布状态需单独确认。 + ### Fixed +- Keep managed Turn identities stable across Session configuration snapshots, return + integer-second Turn timestamps and include the public Turn in in-progress events. / + 托管 Turn 保持 Session 配置快照的稳定身份,时间输出为整数秒,执行中事件包含完整公开 Turn。 + - Read public v1 template files with shared YAML1.2 Core rules, strict UTF-8 and bounded input; reject duplicate keys/aliases without exposing source values. / 公开 v1 模板文件统一采用 YAML1.2 Core、严格 UTF-8 与大小限制,拒绝重复键和别名,错误不泄露原文值。 @@ -27,6 +40,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ### Documentation +- Correct named-resource documentation and contributor guidance: the current CLI and + template runners use prepared IDs; the SDK's earlier YAML snapshot interface has + not migrated to current source files. / 更正命名资源文档和贡献者指引:当前 CLI 与模板脚本 + 使用已准备 ID;SDK 较早的 YAML 快照接口尚未迁移到当前源码格式。 + + - Describe optional SandboxServer access policy as a standalone JSON/YAML runtime document and remove obsolete template-root server/automatic-compilation instructions. / 可选的 SandboxServer 访问策略改为独立 JSON/YAML 运行时文档,移除旧清单根字段及自动编译说明。 diff --git a/client-sdk/pyproject.toml b/client-sdk/pyproject.toml index 90363bee..b9384a19 100644 --- a/client-sdk/pyproject.toml +++ b/client-sdk/pyproject.toml @@ -48,7 +48,7 @@ dependencies = [ [project.optional-dependencies] # Local command registration/runtime only; keep the lockstep version pin. -server = ["agent-sandbox-server==0.4.0a7"] +server = ["agent-sandbox-server==0.4.0a8"] managed-agents = [ "psycopg[binary]>=3.2,<4", "alibabacloud-fc20230330>=4.8.3,<5", diff --git a/client-sdk/src/agent_sandbox/_version.py b/client-sdk/src/agent_sandbox/_version.py index 3861d95e..ad413a81 100644 --- a/client-sdk/src/agent_sandbox/_version.py +++ b/client-sdk/src/agent_sandbox/_version.py @@ -1 +1 @@ -__version__ = "0.4.0a7" +__version__ = "0.4.0a8" diff --git a/client-sdk/src/agent_sandbox/managed_agents/models.py b/client-sdk/src/agent_sandbox/managed_agents/models.py index 8d4c2153..3bacd6a2 100644 --- a/client-sdk/src/agent_sandbox/managed_agents/models.py +++ b/client-sdk/src/agent_sandbox/managed_agents/models.py @@ -9,6 +9,7 @@ from typing import Any from agent_sandbox.models.managed_agents import ManagedError as ManagedError +from agent_sandbox.models.managed_harness import HARNESS_ENV PROTOCOL = "agent-sandbox-managed-agents/v1" BRIDGE_PROTOCOL = "agent-sandbox-managed-bridge/v1" @@ -162,10 +163,10 @@ def __post_init__(self) -> None: "configuration are required" ) if any( - not isinstance(k, str) or not k or len(k) > 128 or v not in {"codex", "qwen-code"} + not isinstance(k, str) or not k or len(k) > 128 or v not in HARNESS_ENV for k, v in self.models.items() ): - raise ValueError("Only tested Codex/Qwen adapters may be configured") + raise ValueError("Only explicitly supported harness adapters may be configured") if ( not isinstance(self.workspace, str) or not self.workspace.startswith("/") @@ -199,7 +200,7 @@ def __post_init__(self) -> None: ): raise ValueError("Worker revisions must map to explicit function identities") if not isinstance(self.model_env_allowlist, list) or any( - v not in {"OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"} + v not in {name for names in HARNESS_ENV.values() for name in names} for v in self.model_env_allowlist ): raise ValueError("Only explicit model environment names may be allowed") diff --git a/client-sdk/src/agent_sandbox/managed_agents/service.py b/client-sdk/src/agent_sandbox/managed_agents/service.py index 47d8443c..460b905f 100644 --- a/client-sdk/src/agent_sandbox/managed_agents/service.py +++ b/client-sdk/src/agent_sandbox/managed_agents/service.py @@ -11,6 +11,8 @@ import time from typing import Any, cast +from agent_sandbox.models.managed_harness import HARNESS_CAPABILITIES + from .models import ( PROTOCOL, SUBMISSION_TERMINAL, @@ -69,7 +71,7 @@ ) -def public(row: dict[str, Any]) -> dict[str, Any]: +def public(row: dict[str, Any], *, session: dict[str, Any] | None = None) -> dict[str, Any]: """Remove all private control/state fields before serializing a public object.""" out = {k: v for k, v in row.items() if not k.startswith("_")} if row.get("_kind") == "session": @@ -77,6 +79,19 @@ def public(row: dict[str, Any]) -> dict[str, Any]: out[key] = int(row[key]) out["required_actions"] = [] out["vault_ids"] = [] + # Inline configurations have a Session-scoped snapshot identity, not a + # saved Agent definition. Derivation also keeps older snapshots stable. + out["agent"] = { + **row["agent"], + "id": row["agent"].get("id") or "agent_" + row["id"].removeprefix("sess_"), + } + if row.get("_kind") == "turn": + for key in ("created_at", "started_at", "completed_at"): + value = row.get(key) + out[key] = int(value) if value is not None else None + out.setdefault("subagent_id", None) + if session is not None: + out.setdefault("agent_id", public(session)["agent"]["id"]) if row.get("_kind") == "session" and isinstance(row.get("environment"), dict): out["environment"] = { **row["environment"], @@ -106,6 +121,10 @@ def capabilities(self) -> dict[str, Any]: "revision": self.config.revision, "operations": [{"method": m, "path": p} for m, p in OPERATIONS], "adapters": sorted(set(self.config.models.values())), + "adapter_capabilities": { + adapter: dict(HARNESS_CAPABILITIES[adapter]) + for adapter in sorted(set(self.config.models.values())) + }, "features": { "steering": False, "explicit_queue": True, @@ -183,7 +202,13 @@ def _remember( ) def _page( - self, rows: list[dict[str, Any]], owner: str, scope: str, query: dict[str, str] + self, + rows: list[dict[str, Any]], + owner: str, + scope: str, + query: dict[str, str], + *, + session: dict[str, Any] | None = None, ) -> dict[str, Any]: reject_unknown(query, {"limit", "order", "after", "idempotency_key"}) try: @@ -238,7 +263,7 @@ def cursor_for(row: dict[str, Any]) -> str: return { "object": "list", - "data": [public(r) for r in selected], + "data": [public(r, session=session) for r in selected], "first_id": selected[0]["id"] if selected else None, "last_id": selected[-1]["id"] if selected else None, "has_more": len(rows) > limit, @@ -495,6 +520,7 @@ def create_session( "storage": self.config.storage, }, ) + agent.setdefault("id", "agent_" + row["id"].removeprefix("sess_")) env = new_object( "environment", owner, @@ -742,7 +768,14 @@ def _handle( ] if path == "/v1/models" else [ - {"id": name, "object": "agent.runtime", "implemented": True, "installed": True} + { + "id": name, + "object": "agent.runtime", + "implemented": True, + "configured": True, + # The Gateway cannot inspect a future Guest's binaries. + "installed": None, + } for name in sorted(set(self.config.models.values())) ] ) @@ -1020,6 +1053,7 @@ def _handle( owner, kind + ":" + session["id"], query, + session=session, ), {}, ) @@ -1030,7 +1064,7 @@ def _handle( if row.get("expires_at", float("inf")) <= time.time(): raise ManagedError(410, "resource_expired", "Stored result has expired") if len(tail) == 2 and method == "GET": - return 200, public(row), {} + return 200, public(row, session=session), {} if kind == "turn" and tail[2:] == ["items"] and method == "GET": rows = [ r diff --git a/client-sdk/src/agent_sandbox/managed_agents/worker.py b/client-sdk/src/agent_sandbox/managed_agents/worker.py index e8c2561f..e3655864 100644 --- a/client-sdk/src/agent_sandbox/managed_agents/worker.py +++ b/client-sdk/src/agent_sandbox/managed_agents/worker.py @@ -84,7 +84,7 @@ def _uncertain(self, sid: str, subid: str | None, claim: str, code: str) -> None tx.event( row, "agent.session.turn.failed", - {"turn_id": turn["id"], "turn": public(turn)}, + {"turn_id": turn["id"], "turn": public(turn, session=row)}, ) tx.event(row, "agent.session.failed", {"error": row["error"]}) @@ -436,13 +436,26 @@ def _ingest(self, sid: str, subid: str, claim: str, receipt: dict[str, Any]) -> e.get("wire", {}).get("type") == "agent.session.turn.in_progress" for e in wires ) if not sub.get("turn_id") and started: + # The first native execution receipt proves that work started. + # Prefer its timestamp; otherwise retain our observation time. + native_turn: dict[str, Any] = receipt.get("turn") or next( + ( + e.get("wire", {}).get("turn", {}) + for e in wires + if e.get("wire", {}).get("type") == "agent.session.turn.in_progress" + ), + {}, + ) turn = new_object( "turn", sub["_owner"], parent=sid, session_id=sid, + agent_id=public(session)["agent"]["id"], status="in_progress", + started_at=native_turn.get("started_at") or time.time(), completed_at=None, + subagent_id=None, usage=None, error=None, _submission=subid, @@ -453,7 +466,11 @@ def _ingest(self, sid: str, subid: str, claim: str, receipt: dict[str, Any]) -> tx.event( session, "agent.session.turn.created", - {"turn_id": turn["id"], "turn": public(turn), "submission_id": subid}, + { + "turn_id": turn["id"], + "turn": public(turn, session=session), + "submission_id": subid, + }, ) seen: set[str] = set() frontier = sub.get("_native_seq", 0) @@ -481,6 +498,8 @@ def _ingest(self, sid: str, subid: str, claim: str, receipt: dict[str, Any]) -> value.pop("session", None) value.pop("turn", None) value["session_id"], value["turn_id"] = sid, sub.get("turn_id") + if kind == "agent.session.turn.in_progress" and sub.get("turn_id"): + value["turn"] = public(tx.get(sub["turn_id"]), session=session) if isinstance(value.get("item"), dict): value["item"] = self._item(sid, sub.get("turn_id"), value["item"]) if "item_id" in value: @@ -603,7 +622,7 @@ def _finish(self, sid: str, subid: str, claim: str, receipt: dict[str, Any]) -> tx.event( session, "agent.session.turn." + status, - {"turn_id": turn["id"], "turn": public(turn)}, + {"turn_id": turn["id"], "turn": public(turn, session=session)}, ) if not pending: tx.event(session, "agent.session.idle", {"session": public(session)}) diff --git a/client-sdk/src/agent_sandbox/models/managed_harness.py b/client-sdk/src/agent_sandbox/models/managed_harness.py new file mode 100644 index 00000000..70ee7faf --- /dev/null +++ b/client-sdk/src/agent_sandbox/models/managed_harness.py @@ -0,0 +1,72 @@ +"""Fixed managed-harness credential names; no environment discovery or plugin loading.""" + +from __future__ import annotations + +from typing import Any +from urllib.parse import urlsplit + +__all__ = ["HARNESS_ENV", "HARNESS_CAPABILITIES", "model_environment", "validate_model_binding"] + +# The standalone server has its own runtime descriptors, checked for parity in tests. +HARNESS_ENV: dict[str, tuple[str, ...]] = { + "codex": ("OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"), + "qwen-code": ("OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"), + "claude-code": ("ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL"), + "qoder": ("QODER_PERSONAL_ACCESS_TOKEN",), + "opencode": ("OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"), + "deepseek-harness": ("DEEPSEEK_API_KEY", "DEEPSEEK_BASE_URL", "DEEPSEEK_MODEL"), +} + +# These describe event observation, not cloud/model qualification. +HARNESS_CAPABILITIES: dict[str, dict[str, Any]] = { + adapter: { + "streaming": "native_partial" + if adapter in {"codex", "claude-code", "qwen-code"} + else "committed_steps" + if adapter == "deepseek-harness" + else "complete_messages", + "tool_events": "completed_only" if adapter == "opencode" else "live", + "per_tool_timeout": adapter != "opencode", + } + for adapter in HARNESS_ENV +} + + +def validate_model_binding(model: dict[str, Any]) -> None: + """Validate native authentication without requiring a fake endpoint for Qoder.""" + if ( + not isinstance(model, dict) + or not isinstance(model.get("adapter"), str) + or model["adapter"] not in HARNESS_ENV + ): + raise ValueError("An explicit supported harness adapter is required") + required = {"adapter", "model", "apiKey"} + if model["adapter"] != "qoder": + required.add("baseUrl") + if not required <= set(model) or set(model) - (required | {"baseUrl"}): + raise ValueError("Explicit harness credentials, model and applicable endpoint are required") + if any(not isinstance(model.get(k), str) or not model[k].strip() for k in required): + raise ValueError("Harness credentials, model and adapter cannot be empty") + endpoint = model.get("baseUrl", "") + if model["adapter"] == "qoder": + if endpoint not in (None, ""): + raise ValueError("Qoder native authentication does not accept a model endpoint") + return + parsed = urlsplit(endpoint) + if ( + parsed.scheme != "https" + or not parsed.hostname + or parsed.username + or parsed.password + or parsed.query + or parsed.fragment + ): + raise ValueError("Model endpoints must be explicit HTTPS URLs without credentials or query") + + +def model_environment(model: dict[str, Any]) -> dict[str, str]: + """Return only the selected harness's known credential/configuration variables.""" + validate_model_binding(model) + names = HARNESS_ENV[model["adapter"]] + values = (model["apiKey"], model.get("baseUrl", ""), model["model"]) + return dict(zip(names, values[: len(names)], strict=True)) diff --git a/client-sdk/src/agent_sandbox/providers/alicloud_express/managed.py b/client-sdk/src/agent_sandbox/providers/alicloud_express/managed.py index f7e1c22f..b5ea97b7 100644 --- a/client-sdk/src/agent_sandbox/providers/alicloud_express/managed.py +++ b/client-sdk/src/agent_sandbox/providers/alicloud_express/managed.py @@ -7,6 +7,7 @@ from urllib.parse import urlsplit from agent_sandbox.models.managed_agents import ManagedError +from agent_sandbox.models.managed_harness import model_environment, validate_model_binding if TYPE_CHECKING: from collections.abc import Callable @@ -29,17 +30,11 @@ def __init__( raise ValueError( "Explicit Express provider, Key, API URL, domain and region are required" ) - if model is not None and ( - set(model) != {"apiKey", "baseUrl", "model", "adapter"} - or model["adapter"] not in {"codex", "qwen-code"} - ): - raise ValueError("Explicit model credentials, endpoint, model and adapter are required") - if any( - not isinstance(v, str) or not v.strip() - for v in (*provider.values(), *(model or {}).values()) - ): + if model is not None: + validate_model_binding(model) + if any(not isinstance(v, str) or not v.strip() for v in provider.values()): raise ValueError("Service credentials and endpoint values cannot be empty") - for url in [provider["baseUrl"], *([model["baseUrl"]] if model else [])]: + for url in [provider["baseUrl"]]: parsed = urlsplit(url) if ( parsed.scheme != "https" @@ -91,11 +86,8 @@ async def create( 400, "model_binding_mismatch", "This Worker has no matching model binding" ) settings = session["_settings"] - if set(settings.get("modelEnvAllowlist", [])) != { - "OPENAI_API_KEY", - "OPENAI_BASE_URL", - "OPENAI_MODEL", - }: + native_env = model_environment(self.model) + if set(settings.get("modelEnvAllowlist", [])) != set(native_env): raise ManagedError( 400, "model_env_not_allowed", "Required model variables are not allowed" ) @@ -127,9 +119,7 @@ async def create( **custom_env, "ABX_SERVER_TOKEN": token, "ABX_MANAGED_WORKSPACE": settings["workspace"], - "OPENAI_API_KEY": self.model["apiKey"], - "OPENAI_BASE_URL": self.model["baseUrl"], - "OPENAI_MODEL": self.model["model"], + **native_env, }, ) info = await infra.sandbox_protocol.create(config, request_timeout=30) diff --git a/client-sdk/tests/test_managed_harness.py b/client-sdk/tests/test_managed_harness.py new file mode 100644 index 00000000..5d88f876 --- /dev/null +++ b/client-sdk/tests/test_managed_harness.py @@ -0,0 +1,73 @@ +"""Managed native credential mappings remain explicit across host and standalone server.""" + +from __future__ import annotations + +import pytest + +from agent_sandbox.models.managed_harness import ( + HARNESS_ENV, + model_environment, + validate_model_binding, +) + + +@pytest.mark.parametrize("adapter", sorted(HARNESS_ENV)) +def test_native_environment_binding(adapter): + binding = {"adapter": adapter, "model": "native-model", "apiKey": "placeholder-model-secret"} + if adapter != "qoder": + binding["baseUrl"] = "https://model.example/v1" + environment = model_environment(binding) + assert set(environment) == set(HARNESS_ENV[adapter]) + assert environment[HARNESS_ENV[adapter][0]] == "placeholder-model-secret" + assert "ABX_SERVER_TOKEN" not in environment + + +def test_standalone_bridge_contract_parity(): + from agent_sandbox.server.managed import MANAGED_HARNESS_ENV + + assert MANAGED_HARNESS_ENV == HARNESS_ENV + + +@pytest.mark.parametrize( + "endpoint", + [ + "http://model.example/v1", + "https://user:password@model.example/v1", + "https://model.example/v1?token=placeholder", + "https://model.example/#secret", + ], +) +def test_invalid_model_endpoints_reject(endpoint): + with pytest.raises(ValueError): + validate_model_binding( + { + "adapter": "claude-code", + "model": "native-model", + "apiKey": "placeholder", + "baseUrl": endpoint, + } + ) + + +def test_qoder_does_not_accept_fake_openai_endpoint(): + with pytest.raises(ValueError): + validate_model_binding( + { + "adapter": "qoder", + "model": "auto", + "apiKey": "placeholder", + "baseUrl": "https://model.example/v1", + } + ) + + +def test_model_binding_rejects_arbitrary_secret_names(): + with pytest.raises(ValueError): + validate_model_binding( + { + "adapter": "qoder", + "model": "auto", + "apiKey": "placeholder", + "AWS_SECRET_ACCESS_KEY": "placeholder", + } + ) diff --git a/client-sdk/tests/test_managed_wire.py b/client-sdk/tests/test_managed_wire.py new file mode 100644 index 00000000..c62cf674 --- /dev/null +++ b/client-sdk/tests/test_managed_wire.py @@ -0,0 +1,222 @@ +"""Managed Turn retrieval and lifecycle events share stable public identities.""" + +from __future__ import annotations + +import hashlib +import threading +from typing import Any + +import pytest + +from agent_sandbox.managed_agents import ManagedConfig, ManagedService, ManagedStore +from agent_sandbox.managed_agents.http import TokenAuthenticator, make_server +from agent_sandbox.managed_agents.store import new_object +from agent_sandbox.managed_agents.worker import ManagedWorker + + +@pytest.fixture +def service(tmp_path: Any) -> ManagedService: + return ManagedService( + ManagedStore("sqlite:///" + str(tmp_path / "state.db"), local=True), + ManagedConfig("revision-a", "template-a", {"test-model": "qwen-code"}), + ) + + +def start(service: ManagedService, agent_id: str | None = None) -> tuple[str, str, ManagedWorker]: + body: dict[str, Any] = {"input": "Create a report"} + body.update({"agent_id": agent_id} if agent_id else {"agent": {"model": "test-model"}}) + session, subid = service.create_session("owner", body) + sid = session["id"] + assert subid is not None + with service.store.transaction() as tx: + session = tx.get(sid) + session["_claim"] = "test-claim" + tx.put(session) + worker = ManagedWorker(service, None) + worker._ingest( + sid, + subid, + "test-claim", + { + "events": [ + { + "seq": 1, + "wire": { + "type": "agent.session.turn.in_progress", + "event_id": "guest-event", + "session_id": "guest-session", + "turn_id": "guest-turn", + "turn": {"id": "guest-turn", "started_at": 1700000000.75}, + }, + } + ] + }, + ) + return sid, subid, worker + + +def finish(service: ManagedService, sid: str, subid: str, worker: ManagedWorker) -> None: + worker._finish( + sid, + subid, + "test-claim", + {"status": "completed", "turn": {"usage": None}, "items": [], "artifacts": []}, + ) + + +def test_turn_retrieval_and_events_preserve_host_identity_and_integer_seconds( + service: ManagedService, +) -> None: + sid, subid, worker = start(service) + session = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}")[1] + turns = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}/turns")[1]["data"] + turn = turns[0] + assert turn["agent_id"] == session["agent"]["id"] + assert turn["session_id"] == sid and turn["id"] != "guest-turn" + assert type(turn["created_at"]) is int + assert type(turn["started_at"]) is int + assert turn["started_at"] == 1700000000 + assert turn["subagent_id"] is None and turn["completed_at"] is None + in_progress = next( + e + for e in service.events("owner", sid, "0") + if e["type"] == "agent.session.turn.in_progress" + ) + assert in_progress["turn"] == turn + assert in_progress["turn_id"] == turn["id"] and in_progress["session_id"] == sid + with service.store.transaction() as tx: + assert type(tx.get(turn["id"])["created_at"]) is float + finish(service, sid, subid, worker) + terminal = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}/turns/{turn['id']}")[1] + assert type(terminal["completed_at"]) is int + assert terminal["agent_id"] == turn["agent_id"] + assert terminal["started_at"] == turn["started_at"] + assert terminal["status"] == "completed" + event = next( + e for e in service.events("owner", sid, "0") if e["type"] == "agent.session.turn.completed" + ) + assert event["turn"] == terminal + + +def test_saved_agent_identity_stays_frozen_after_definition_update_and_delete( + service: ManagedService, +) -> None: + agent = service.handle("owner", "POST", "/v1/agents", {"model": "test-model"})[1] + sid, subid, worker = start(service, agent["id"]) + service.handle("owner", "POST", "/v1/agents/" + agent["id"], {"instructions": "Changed"}) + service.handle("owner", "DELETE", "/v1/agents/" + agent["id"]) + finish(service, sid, subid, worker) + turn = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}/turns")[1]["data"][0] + session = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}")[1] + assert turn["agent_id"] == session["agent"]["id"] == agent["id"] + assert session["agent"].get("instructions") != "Changed" + + +def test_legacy_turn_projection_uses_frozen_session_without_rewriting_private_state( + service: ManagedService, +) -> None: + session, _ = service.create_session("owner", {"agent": {"model": "test-model"}}) + sid = session["id"] + with service.store.transaction() as tx: + legacy = tx.get(sid) + legacy["agent"].pop("id", None) + tx.put(legacy) + turn = new_object( + "turn", + "owner", + parent=sid, + session_id=sid, + status="completed", + completed_at=1700000001.75, + usage=None, + error=None, + ) + tx.put(turn) + first = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}")[1] + again = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}")[1] + result = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}/turns/{turn['id']}")[1] + listed = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}/turns")[1]["data"][0] + assert first["agent"]["id"] == again["agent"]["id"] == result["agent_id"] + assert result["started_at"] is None and result["subagent_id"] is None + assert result == listed + assert result["completed_at"] == 1700000001 + with service.store.transaction() as tx: + assert "id" not in tx.get(sid)["agent"] + assert "started_at" not in tx.get(turn["id"]) + + +def test_supported_turn_events_parse_with_official_openai_types(service: ManagedService) -> None: + openai = pytest.importorskip("openai") + turn_types = pytest.importorskip("openai.types.beta.agents.sessions.turn") + progress_types = pytest.importorskip("openai.types.beta.agent_session_turn_in_progress_event") + completed_types = pytest.importorskip("openai.types.beta.agent_session_turn_completed_event") + sid, subid, worker = start(service) + finish(service, sid, subid, worker) + events = service.events("owner", sid, "0") + for kind, model in ( + ("agent.session.turn.in_progress", progress_types.AgentSessionTurnInProgressEvent), + ("agent.session.turn.completed", completed_types.AgentSessionTurnCompletedEvent), + ): + event = model.model_validate(next(e for e in events if e["type"] == kind)) + assert event.turn.subagent_id is None + assert event.turn.id == event.turn_id and event.turn.session_id == sid + assert event.turn.agent_id + turn = service.handle("owner", "GET", f"/v1/agents/sessions/{sid}/turns")[1]["data"][0] + parsed = turn_types.Turn.model_validate(turn) + assert parsed.status == "completed" and parsed.completed_at is not None + token = "placeholder-official-client-local-fixture" + auth = TokenAuthenticator( + { + "tokens": [ + { + "sha256": hashlib.sha256(token.encode()).hexdigest(), + "owner": "owner", + "scopes": ["agents:read"], + } + ] + } + ) + server = make_server(service, auth, port=0) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + with openai.OpenAI( + base_url=f"http://127.0.0.1:{server.server_port}/v1", + api_key=token, + max_retries=0, + timeout=5, + ) as client: + retrieved = client.beta.agents.sessions.turns.retrieve(parsed.id, session_id=sid) + assert retrieved.agent_id == parsed.agent_id + assert retrieved.subagent_id is None and retrieved.status == "completed" + with client.beta.agents.sessions.events.stream( + sid, extra_query={"after": "0"} + ) as stream: + for event in stream: + if event.type == "agent.session.turn.completed": + assert event.turn.subagent_id is None + assert event.turn.id == retrieved.id + break + else: + pytest.fail("The completed Turn was absent from its durable event stream") + finally: + server.shutdown() + server.server_close() + thread.join(timeout=3) + + +def test_capabilities_only_advertise_configured_harness_and_actual_tool_timing( + service: ManagedService, +) -> None: + configured = ManagedService( + service.store, ManagedConfig("revision-a", "template-a", {"test-model": "opencode"}) + ) + caps = configured.handle("owner", "GET", "/v1/agent-sandbox/capabilities")[1] + assert caps["adapters"] == ["opencode"] + assert set(caps["adapter_capabilities"]) == {"opencode"} + assert caps["adapter_capabilities"]["opencode"]["tool_events"] == "completed_only" + assert caps["adapter_capabilities"]["opencode"]["per_tool_timeout"] is False + assert caps["features"]["steering"] is False + runtime = configured.handle("owner", "GET", "/v1/agents/runtimes")[1]["data"][0] + assert runtime["id"] == "opencode" and runtime["configured"] is True + assert runtime["installed"] is None diff --git a/docs/en/design/template-system.md b/docs/en/design/template-system.md index 17ac6d3c..9db8651f 100644 --- a/docs/en/design/template-system.md +++ b/docs/en/design/template-system.md @@ -1,49 +1,40 @@ # Template System -Templates use specification 1. A template defines the complete sandbox contents, -its startup/readiness commands and every service it provides. Starting a template -never selects a subset by workflow, operation or application/exec/interpreter type. +Templates define reusable application source and named Sandbox/Serving resources. +Use `specVersion: 1`, optional author-defined `vars`, `sandbox..template` +and component-native `serving..props`. The [field reference](../reference/template-yaml-spec.md) +links the owning specification and explains Python's current consumer limits. ## Responsibilities -The template owns application source, dependencies, configuration and startup. -The Provider owns image upload/registration, platform identifiers, sandbox creation -and endpoint resolution. The CLI prepares source and starts the complete template. -Python consumes a prepared reference or connects to an existing sandbox; it does -not acquire Docker/source-build responsibilities. +The template owns application source, dependencies and runtime startup code. The +Provider owns native preparation, instance lifecycle and endpoint resolution. The +CLI handles resource expressions, builds and deployment; deploying a Sandbox +resource does not create every future runtime instance. -## Launch and use +Python consumes prepared IDs through ProviderSandbox or connects to an existing +instance. Template runners create dynamic instances and start their applications +with the required private values. Managed Agents API uses Worker-owned Session +instances; its clients call one Gateway endpoint. -Use `abx --provider PROVIDER deploy TEMPLATE_REF` or Python -`launch_template(manifest, provider=..., reference=...)`. The launcher checks only -operations needed to create, start, inspect readiness and clean up. Missing interpreter -operations never prevent an unrelated application from starting. Actual operations -remain guarded by the Provider and server policy at invocation time. +## Runtime and source configuration -Every `sandbox.services` service is retained. SandboxServer protocol v2 endpoints receive protocol checks; -unknown protocols are returned and use the author's readiness command. A multi-service -template starts once. Calling one endpoint later does not start a different template. +Current named-resource template.yaml files are consumed by the CLI. The SDK's +older launch_template/TemplateSession snapshot interface and discovery projection +have not migrated to those source files. Keep their independent supported contract +separate; do not infer current source support from a shared version number. -## Manifest and migration +The direct runtime path does not require another YAML parser or a Python deployment +engine. Native Devs owns expressions. Application runtime configuration and server +policy are separate from reusable resource preparation. -See [the field reference](../reference/template-yaml-spec.md) and the authoritative -[template-v1 schema](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/spec/template-v1.schema.json). -Remove `workflow_contract_version`, `default_workflow` and `workflows`; keep -`specVersion: 1`, `sandbox.services`, `sandbox.start`, `sandbox.ready` and application metadata. -Old running manifests require explicit migration. Source locations, prepared image -references and native template IDs are preparation details, not user-selectable flows. +## Ownership and cleanup -## Ownership and verification +Delete only instances/resources created by the owning application. Closing a local +connection does not delete a borrowed instance. Managed Sessions expose close and +cleanup Operations separately from public deletion; inspect their outcome before +considering compute released. -The launcher records creation intent and owned IDs. Uncertain creates are not replayed; -cleanup attempts every owned client and sandbox, retaining failures for reconciliation. -Connecting to an existing sandbox does not confer deletion ownership. - -Catalog membership or a static supported plan is not a test pass. Historical workflow -receipts remain readable history; they do not certify specification 1. A template's -metadata version is not a registry storage/versioning service. Use actual Git revisions -and recorded inputs to reproduce a run. - -See [Python launch examples](../guide/template-workflows.md), +See [Python runtime examples](../guide/template-workflows.md), [authoring templates](../guide/authoring-templates.md), and [the server API](../guide/template-server-api.md). diff --git a/docs/en/guide/authoring-templates.md b/docs/en/guide/authoring-templates.md index f05750c1..c72ae876 100644 --- a/docs/en/guide/authoring-templates.md +++ b/docs/en/guide/authoring-templates.md @@ -1,6 +1,6 @@ # Authoring Templates -A template contains application source, a Dockerfile and one `template.yaml`. Use `specVersion: 1`; the [field reference](../reference/template-yaml-spec.md) describes resource, instance and native Serving configuration. Optional `registry.yaml` carries catalog descriptions and initialization questions. Dependencies belong in the Dockerfile and native dependency files. +A template contains application source, a Dockerfile and one `template.yaml`. Use `specVersion: 1`; the [field reference](../reference/template-yaml-spec.md) describes named resource and native Serving configuration; dynamic instance values belong to runtime code. Optional `registry.yaml` carries catalog descriptions and initialization questions. Dependencies belong in the Dockerfile and native dependency files. For Python application endpoints, install `agent-sandbox-server` in the image and register actual business functions: @@ -15,8 +15,8 @@ if __name__ == "__main__": start(9000) ``` -Declare the application's startup/readiness in `sandbox.start` / `sandbox.ready` and endpoints in `sandbox.services`. YAML declarations do not register functions or enable opt-in server groups. Server policy is independent runtime configuration; install its file in the image or use the documented server configuration input. See [the server API](template-server-api.md). +Provide the application's create-time startup and readiness in its runtime code, such as the supplied `run.py`. Resource YAML declares reusable Sandbox templates and native Serving props. YAML declarations do not register functions or enable opt-in server groups. Server policy is independent runtime configuration; install its file in the image or use the documented server configuration input. See [the server API](template-server-api.md). Use [CLI authoring](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/authoring-templates.md) to prepare and publish source. Python [launches a prepared template](template-workflows.md) or connects to an existing Sandbox. Choose one startup owner; a native template entrypoint and Python startup command must not launch the same service twice. -Call registered functions through `session.servers["app"].commands.run("hello", name="Python")` or an explicitly resolved `sandbox.application_client`. Application tokens, gateway headers and Sandbox API credentials have separate audiences. Shell execution remains `sandbox.commands.run(...)` and does not imply a business API or interpreter operation. +Call registered functions through `client.commands.run("hello", name="Python")` after explicitly resolving `client` with `sandbox.application_client`. Application tokens, gateway headers and Sandbox API credentials have separate audiences. Shell execution remains `sandbox.commands.run(...)` and does not imply a business API or interpreter operation. diff --git a/docs/en/guide/build-and-deploy.md b/docs/en/guide/build-and-deploy.md index 02bbcc62..6f146a48 100644 --- a/docs/en/guide/build-and-deploy.md +++ b/docs/en/guide/build-and-deploy.md @@ -6,12 +6,11 @@ The Python SDK is a runtime client. The CLI owns source acquisition, builds, dep abx template init ./my-template --template python abx deploy ./my-template --name my-app --yes abx status my-app -abx sandbox command run my-app hello --arg name=Ada abx delete my-app --yes ``` For reuse, prepare with `abx template build ./my-template --out ./.abx/build.json --yes`, then deploy with `abx deploy --build ./.abx/build.json --name my-app --yes`. Building creates no running instance. Deleting the application retains a separately prepared build. Clean an unused build with `abx template build --clean ./.abx/build.json --yes`; retained resources that require manual cleanup, such as images, are listed. -For an existing native template, Python can call `await ProviderSandbox.create(template=template_id, provider=provider)`. Connect to the returned Sandbox ID when the CLI already started the application. `launch_template` is an advanced runtime entry: its caller must ensure that the image entrypoint or platform startup does not also start the manifest’s service. +For a Sandbox resource, deployment returns a reusable template ID. Follow the selected template's `run.py` instructions to create and start a dynamic instance, or use `await ProviderSandbox.create(template=template_id, provider=provider)` and explicitly start its application. Connect to that returned Sandbox ID for later calls and close/delete it before removing prepared resources. The SDK's older `launch_template` snapshot interface does not accept current named-resource source files; see the linked runtime guide. [CLI authoring guide](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/authoring-templates.md) · [SDK application connections](template-workflows.md) diff --git a/docs/en/guide/managed-agents-api.md b/docs/en/guide/managed-agents-api.md index c4b9c086..10873853 100644 --- a/docs/en/guide/managed-agents-api.md +++ b/docs/en/guide/managed-agents-api.md @@ -4,17 +4,16 @@ Use one Gateway URL and a business bearer token to run coding agents in isolated sandboxes. A Session creates its sandbox on the first input and reuses its workspace for subsequent turns. -The optional runtime supports the built-in Express provider and explicitly configured Codex or -Qwen Code models. It implements selected OpenAI-inspired resource shapes; it does not claim +The optional runtime supports the built-in Express provider and explicit native Harness +model bindings; see the [Harness profiles](managed-harnesses.md) for credentials and version requirements. It implements selected OpenAI-inspired resource shapes; it does not claim OpenAI SDK compatibility or OpenAI-managed harness behavior. -Install the matching client and server packages with the managed deployment dependencies: +Business clients need an HTTP client, such as `httpx`. Operators must use the matching +client/server runtime selected by the template. The six-Harness runtime0.4.0a8 is a +candidate and is not yet published; do not substitute0.4.0a7, which only admits the +older Codex/Qwen subset. See [source installation](install-python.md) for development. -```bash -python -m pip install --pre 'agent-sandbox-client[managed-agents]==0.4.0a7' -``` - -The [agents-api template](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/tree/main/agents-api) +The [Agents API family](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/docs/agents-api-harnesses.md) provides the application configuration. Deploy it with the matching [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox). Applications connect to the returned Gateway endpoint; they do not configure individual sandbox endpoints. @@ -50,6 +49,15 @@ with httpx.Client( Session `created_at` and `last_active_at` are Unix timestamps in integer seconds. `required_actions` and `vault_ids` are empty arrays; client-required actions and Vault bindings are unsupported. +Turn `created_at`, `started_at` and `completed_at` use integer Unix seconds; timestamps that +are not known are `null`. A new Turn uses the native start timestamp when available, otherwise +the time the Worker first observes execution. Its `agent_id` identifies the Session's frozen +Agent configuration, and `subagent_id` is `null`. Inline configurations receive a stable +Session-scoped identity; that identity does not create a saved Agent definition to retrieve. +The in-progress and terminal Turn events contain the same public Turn shape as `/turns`. +These resource shapes support the documented HTTP workflow; they do not establish full +OpenAI SDK interoperability or features absent from the deployment's capabilities. + Creation returns `201`. Input reception returns a durable Submission, while a public Turn appears when execution starts. Poll the Session and its `/turns` and `/artifacts` collections. Download a published artifact through `/v1/agents/sessions/{id}/artifacts/{artifact_id}/content`. @@ -133,11 +141,15 @@ Operation results before treating resource cleanup as complete. | Managed lifecycle | Close, Operations, Submission enqueue/list/detail/cancel | `GET /v1/agent-sandbox/capabilities` returns the supported routes and deployment budgets. +Runtime inventory lists configured adapters; `installed: null` means the Gateway has +not inspected a Guest binary. Guest readiness and actual task execution remain separate. Lists accept `limit`, `order` and `after`; use `last_id` or the scoped `next_cursor` for the next page. Session updates support metadata only. Function tools, arbitrary MCP configuration, subagents, steering, image/audio input and dynamic model/settings changes are rejected. Shell/file tools -provided by the selected CLI remain available inside its sandbox. Tool wall deadlines begin at -observed native tool-start events. Unknown runtime epochs or uncertain submission receipts freeze +provided by the selected CLI remain available inside its sandbox. +`adapter_capabilities` describes the configured Harness's stream granularity and tool-event timing. +Per-tool deadlines apply only when `per_tool_timeout` is true: pinned OpenCode reports tools +after completion, so only its whole-turn deadline can be enforced. Unknown runtime epochs or uncertain submission receipts freeze execution; they never automatically replay an input. The Gateway requires PostgreSQL for FC deployment. SQLite is restricted to explicit local mode. @@ -147,7 +159,7 @@ preserves private ownership records required to resolve uncertain resources. ## Sandbox instance configuration -The v1 `sandbox.instance` controls each Session's new Sandbox: `timeout`, CPU/memory/disk/GPU, existing Volume-name mounts and user metadata. Managed TTL defaults to3600 seconds; internal lifetime budgets are derived from this single value. New revisions preserve each existing Session's settings and Worker routing. Preparation `sandbox.template.props` does not change a Session instance. +The template's `vars.policy.instance.timeout` controls the Session Sandbox lifetime; its default is 3600 seconds. The current recipe exposes this lifetime setting, while the SDK's private `ManagedConfig.instance` also supports admitted instance specifications, existing Volume mounts and metadata for custom application operators. Those private settings are not a public `sandbox.instance` YAML block. Template properties under `sandbox..template` apply during preparation. Updates retain each existing Session's frozen settings and Worker route. All custom environment values are private, including values that look harmless. The deployer sends names in compiled configuration and resolves values only for the Worker through `ABX_MANAGED_SANDBOX_ENV_JSON` or `_FILE`; values never enter Session settings or public plans. Worker source names must exactly match `instanceEnvNames`. Model credentials stay in the separate model binding. Runtime/model controls (`ABX_*`, `OPENAI_*`, `QWEN_*`, `CODEX_*`, `PYTHON*`, `LD_*`, `HOME`, `PATH`, `SHELL`, `USER`, `LOGNAME`, `ANTHROPIC_API_KEY`, `DASHSCOPE_API_KEY`) cannot be overridden through custom environment input. @@ -156,7 +168,8 @@ Managed Sandboxes use secure access and kill-on-timeout without automatic resume ## Operator configuration Run `python -m agent_sandbox.managed_agents gateway|worker|dispatcher`. The guest image runs -`python -m agent_sandbox.server.managed --port 9000`; it requires Codex or Qwen Code installed. +`python -m agent_sandbox.server.managed --port 9000`; its image must contain the selected +pinned Harness and matching server runtime. Each configuration document accepts exactly one `_FILE` or `_JSON` source: @@ -165,7 +178,7 @@ Each configuration document accepts exactly one `_FILE` or `_JSON` source: | `ABX_MANAGED_CONFIG` | Non-secret `instance`, `instanceEnvNames`, compiled revision, application ID, template, model/adapter allowlist, `modelEnvAllowlist`, Session/storage/execution budgets, `expectedStateId` and retained Worker mapping | | `ABX_MANAGED_AUTH` | `tokens: [{sha256,owner,scopes,expiresAt?}]`; scopes are `agents:read` and `agents:write` | | `ABX_MANAGED_SANDBOX_ENV` | Worker-only custom environment string map, with names exactly matching `instanceEnvNames` | -| `ABX_MANAGED_MODEL_CONFIG` | Worker-only `{apiKey,baseUrl,model,adapter}` | +| `ABX_MANAGED_MODEL_CONFIG` | Worker-only `{apiKey,model,adapter}` plus `baseUrl` for applicable Harnesses | | `ABX_MANAGED_PROVIDER_CONFIG` | Worker/Dispatcher `{provider:"alicloud-express",apiKey,baseUrl,domain,region}` | `ABX_MANAGED_DATABASE_URL` identifies PostgreSQL. The deployment pins its persistent state identity; replacing the database with empty state is rejected, including by warm instances. Credential and CA rotation on the same state remains supported. `ABX_MANAGED_INTERNAL_TOKEN` authenticates private @@ -173,7 +186,12 @@ role invocations and must remain stable while retained revisions drain. `ABX_MANAGED_FC_ENDPOINT` selects the explicit FC service host for dispatch. Private control requests may omit `revision` to address the whole application or supply a nonempty revision. The private HTTP listener rejects an empty string with HTTP 400 before accessing or changing application state. -`modelEnvAllowlist` must explicitly allow `OPENAI_API_KEY`, `OPENAI_BASE_URL` and `OPENAI_MODEL`. +`modelEnvAllowlist` must exactly match the selected Harness's native environment names. +Codex/Qwen/OpenCode use `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`; Claude Code +uses `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`; DeepSeek Harness uses +`DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`, `DEEPSEEK_MODEL`; Qoder uses its native +`QODER_PERSONAL_ACCESS_TOKEN` without an invented model endpoint. The model ID remains +in its explicit binding. The family bootstrap supplies these names. Credentials are passed only to roles which need them, and never put in images or public resources. File-backed business authentication is reread for revocation; optional token expiry is enforced. diff --git a/docs/en/guide/managed-harnesses.md b/docs/en/guide/managed-harnesses.md new file mode 100644 index 00000000..e34e2d57 --- /dev/null +++ b/docs/en/guide/managed-harnesses.md @@ -0,0 +1,62 @@ +# Managed Agent harnesses + +The managed Gateway uses the same Session, input, turn, item, event, file and artifact +protocol for every supported harness. Choose a template such as `agents-api-codex` +when deploying the application. A Session's native harness stays fixed for its lifetime; +model credentials are supplied to its private Worker and Sandbox, separately from the +Gateway's client authentication. + +The harness additions described here are source changes for client/server **0.4.0a8**. +Check package availability before building images. An unpublished candidate does not +provide a working PyPI installation command. Installed older servers do not gain new +adapters when only a host client is updated. + +| Adapter | Native command | Credentials | Model endpoint | +| --- | --- | --- | --- | +| `codex` | `codex exec --json` | `OPENAI_API_KEY` | Explicit Responses-compatible `OPENAI_BASE_URL` | +| `qwen-code` | `qwen --output-format stream-json` | `OPENAI_API_KEY` | Explicit Chat Completions-compatible `OPENAI_BASE_URL` | +| `claude-code` | `claude -p --output-format stream-json` | `ANTHROPIC_API_KEY` | Explicit Messages-compatible `ANTHROPIC_BASE_URL` | +| `qoder` | `qoder --print --output-format stream-json` | `QODER_PERSONAL_ACCESS_TOKEN` | Native Qoder service; no custom endpoint in this adapter | +| `opencode` | `opencode run --format json` | `OPENAI_API_KEY` | Explicit Chat Completions-compatible `OPENAI_BASE_URL`, configured as native provider `abx` | +| `deepseek-harness` | `dsh --profile headless --json` | `DEEPSEEK_API_KEY` | Explicit Messages-compatible `DEEPSEEK_BASE_URL`; official root is `https://api.deepseek.com/anthropic` | + +Use the corresponding template's private credential source and configuration guide. +Do not put credentials in the image or commit them in `template.yaml`. The application +model ID selects the template's fixed harness. For Qoder, use a model available to the +PAT's account, such as the account's native model choice; an OpenAI model key cannot +replace a Qoder PAT. Obtain a PAT from [Qoder integrations](https://qoder.com/account/integrations). +Qoder BYOK depends on the account's supported plan and catalog and is managed through +its `/model` wizard; this adapter does not invent a manual BYOK configuration. + +Native model names are passed to the selected harness. Codex/Qwen/OpenCode use +`OPENAI_MODEL`; Claude uses `ANTHROPIC_MODEL`; DeepSeek Harness uses `DEEPSEEK_MODEL`. +The Worker injects only the names required by its selected adapter. It rejects a +different model/harness binding and unrelated credential names. + +Each turn runs the real native CLI. Later turns restore its exact native session ID in +the same Session Sandbox. Close releases compute while retaining the Gateway's stored +results; opening a fresh Sandbox cannot promise restoration of files or native history +from deleted compute. Use the public lifecycle described in the [managed API guide](managed-agents-api.md). + +Codex, Claude and Qwen can provide partial native events. OpenCode's JSON text and +DeepSeek Harness's headless text represent complete messages or committed steps; they +are not token deltas. A terminal native message alone does not prove that every process +has exited. The bridge also observes process exit and owned process cleanup, preserving +an uncertain state when it cannot establish completion. + +OpenCode 1.19.5 reports tools only after they complete. Its tool items represent completed +records; a live per-tool timeout cannot be enforced from this stream. The overall run +deadline and owned process cleanup still apply. In the general local runtime, this adapter +supports `read_only` or `full_access` and rejects `workspace_write`, which cannot be mapped +reliably to this native CLI. Managed Session execution uses `full_access` inside its Sandbox. + +The new adapters are experimental. Qoder, OpenCode and DeepSeek Harness do not yet map +external MCP server configuration through this adapter API. Qoder 1.1.90 does not expose +the `--max-turns` flag described by some newer documentation, so a configured turn count +is rejected. Steering, functions, subagents and tools remain subject to the Gateway's +capabilities and native harness behavior. See the template's actual verification scope +before relying on a provider, model route or account type. + +The DeepSeek adapter invokes the official `@deepseek-ai/dsh` package. The older +`deepseek-harness` named-command template implements a separate project-owned tool loop; +its model execution history does not certify the official native adapter. diff --git a/docs/en/guide/sdk-usage.md b/docs/en/guide/sdk-usage.md index 9a940fb8..a539045d 100644 --- a/docs/en/guide/sdk-usage.md +++ b/docs/en/guide/sdk-usage.md @@ -261,7 +261,7 @@ async for event in watcher: The `sandbox.network` submodule computes port access URLs (purely local computation, no network requests involved). -> Port addressing is supplied by the selected Provider. Declare template endpoints with v1 `sandbox.services` or additional `sandbox.ports`; a declaration does not grant Provider operations. The template launcher requires the selected Provider's `ports.resolve` support for declared endpoints. +> Port addressing is supplied by the selected Provider. Use the running instance's `application_endpoint` or `application_client`; an open port does not start an application or grant Provider operations. Current named-resource YAML and Python runtime usage are described in [template usage](template-workflows.md). ```python # Get port URL diff --git a/docs/en/guide/template-workflows.md b/docs/en/guide/template-workflows.md index 7a2a44c0..35b6c3d3 100644 --- a/docs/en/guide/template-workflows.md +++ b/docs/en/guide/template-workflows.md @@ -1,6 +1,6 @@ # Launch and use a template -Use `abx --provider PROVIDER deploy SOURCE --name my-app --yes` to prepare and start a source template, then connect with Python using the returned sandbox ID and the same provider. If the platform already provides a template ID, Python can create it directly. +Use `abx --provider PROVIDER deploy SOURCE --name my-app --yes` to prepare source resources. Start an ordinary Sandbox application with its supplied `run.py`, then connect using the returned Sandbox ID and the same provider. If the platform already provides a template ID, Python can create an instance directly. ## Python application consumption @@ -21,53 +21,38 @@ finally: The client also sends the explicit application token in the server's existing `X-Access-Token` header when that header is unused. This keeps authentication working through proxies that strip `Authorization`, including OpenSandbox 1.1.1. Existing gateway headers, including defaults on an injected HTTP client, are never replaced. Bearer authentication remains available for services that require it. -For advanced preparation, `launch_template` creates a new sandbox from a prepared provider reference and runs the manifest's `sandbox.start`. The reference must not also start the same service through its native startup command or image entrypoint. CLI build artifacts retain their declared startup behavior; do not treat a prepared reference as an instruction to start the service twice. If the CLI has already started the application, connect to its sandbox as above. +## Create and start an owned instance -To let Python own startup and cleanup after checking that preparation boundary: +A source template's `abx deploy` prepares reusable Sandbox resources and deploys any +Serving resources. For an ordinary Sandbox template, run its supplied `run.py` with +the returned prepared template ID. The runner creates the instance, starts its +application and saves a private session file. Follow that template's README for +credentials, model settings, endpoints and cleanup. Creating an instance alone does +not start an application that expects this explicit startup step. -```python -from agent_sandbox.api import launch_template - -async with await launch_template( - "template.yaml", provider="opensandbox", - reference=prepared_reference, application_token=application_token, -) as session: - result = await session.run_command("hello", name="Python") -``` - -There is no workflow selection. Python creates one sandbox, runs `sandbox.start` once, -checks `sandbox.ready`, and resolves every service in `sandbox.services`. SandboxServer protocol v2 services -receive health/discovery checks before use. Other service protocols use the template's -readiness command; their endpoints are returned without guessing protocol routes. -`session.services` contains every service client, while `session.servers` contains -SandboxServer clients. `session.server` and `session.run_command` are conveniences -only when there is exactly one SandboxServer. With several, call -`session.servers["service-name"].commands.run(...)` to choose the invocation target. -Choosing a client never changes which template services were started. - -Python does not build sources. Source preparation belongs to the CLI; choose one -startup owner as described above. A manifest may -also declare a fixed digest-pinned `sandbox.template.image`, or a `sandbox.template.reference` and `sandbox.provider` for a -platform-managed template. References are interpreted by that Provider; native IDs -need no artificial version. For an existing external HTTP service, use `ServerClient` -directly. Application deployment hooks still belong to the deployment orchestrator. - -The launcher freezes the manifest, records intent and owned IDs, and deletes only its -own sandbox. Uncertain creation is not retried and remains recorded for reconciliation -using `abx_template_run` metadata. Every resolved client is closed on failure, including -failure of a later service. Journals exclude tokens, environment values and signed URLs; -they do not constitute verified cloud receipts. One effective `ABX_SERVER_TOKEN` value -is used both for the sandbox environment and the application clients. - -After process-start acknowledgement, the launcher polls a nonzero `sandbox.ready` result within one `readiness_timeout` budget. Each probe uses the remaining budget; a successful exit completes readiness. Expiration raises `readiness-command-failed` and removes the owned sandbox. Cancellation also retains owned cleanup. This waits for application readiness, which is separate from acknowledging that its process started. +If your application manages instances directly, use `ProviderSandbox.create` with the +prepared template ID and the required runtime values. Start its documented process +with `start_server`, resolve its application client, and delete only the instance you +created. Connecting to an existing instance releases a local connection when closed; +it does not confer resource ownership. ## Resource configuration -The v1 examples describe the updated SDK source consumer. Use a matching [source installation](install-python.md) when this behavior is not in your installed distribution; unchanged package version metadata alone does not establish v1 support. +The current [resource format](../reference/template-yaml-spec.md) has named Sandbox and +Serving resources. The CLI handles its native expressions, builds and deployment. +Python creates instances from prepared IDs and consumes explicit runtime configuration; +it does not evaluate a current named-resource `template.yaml`. -Use the [v1 resource fields](../reference/template-yaml-spec.md). Parsing literal prepared input needs no CLI installation; the selected Provider can still have its own runtime dependencies. Native expressions must first be resolved by the Devs parser. `sandbox.instance.timeout` supplies the TTL unless the explicit Python `timeout` argument overrides it; omitted overrides preserve the manifest. Instance specs, existing Volume mounts, environment and metadata are forwarded. Environment values never implicitly read the host environment. Application deployment remains an orchestrator responsibility and is rejected before creating a sandbox. +The existing advanced `launch_template` API still accepts its earlier prepared snapshot +format. It does not accept current named-resource source files. Its `TemplateSession` +service/endpoint helpers remain available for that separate interface; do not pass the +current template's `template.yaml` to it. Use the template's runner or the explicit +instance API for the current resource format. Runtime TTL, environment, metadata and +mount overrides belong to instance creation or the application's runtime policy. -Additional declared `sandbox.ports` are returned as `session.endpoints[port]` Provider descriptors, without creating clients or probing them. Their gateway headers stay in memory and are not part of the public plan or journal. A port declaration does not establish native TCP reachability or start that service. +For a deployment of the managed Agents API, clients use its Gateway HTTP endpoint; +the template's Worker owns dynamic Sandbox creation and cleanup. See the +[managed API guide](managed-agents-api.md). ## Interpreter operations @@ -90,10 +75,7 @@ finally: await sandbox.kill() # this code created and owns the sandbox ``` -With `specVersion: 1`, `sandbox.provider: alicloud-express`, -`sandbox.template.reference: base` and no services, `launch_template(manifest, -provider="alicloud-express")` provides the same owned cleanup through its async -context manager. Existing Volume mounts are borrowed; Sandbox cleanup never deletes them. +Existing Volume mounts are borrowed; instance cleanup never deletes those Volumes. Executing a shell command on `code-interpreter-v1` does not exercise the interpreter API. Express, E2B and REST project adapters currently do not implement unified interpreter operations; use the documented native SDK where applicable. CubeSandbox and container edition support the persistent default-context operation. diff --git a/docs/en/reference/api-reference.md b/docs/en/reference/api-reference.md index be531040..734726cf 100644 --- a/docs/en/reference/api-reference.md +++ b/docs/en/reference/api-reference.md @@ -515,4 +515,4 @@ See [Error Codes Reference](./error-codes.md) for the complete error code listin Provider lifecycle methods that accept cloud AccessKeys also accept `security_token`; the environment name is `ALIBABA_CLOUD_SECURITY_TOKEN`. `ProviderSandbox.create` additionally accepts `network` and `allow_internet_access`. `ProviderSandbox.connect(..., traffic_access_token=...)` retains GET-only attach semantics, and `application_client(..., traffic_access_token=...)` provides a per-client gateway credential override. See [provider commands](../guide/provider-commands.md) and [authentication](../guide/authentication.md). -For canonical v1 prepared templates, `launch_template(..., timeout=None)` preserves the declared instance TTL. Explicit resource and environment arguments override the corresponding values. `TemplateSession.services` holds actual declared service clients; `TemplateSession.endpoints` holds additional port descriptors with headers only in memory. See [template fields](template-yaml-spec.md) and [launch ownership/cleanup](../guide/template-workflows.md). +`launch_template` and `TemplateSession` retain their earlier prepared snapshot interface; they do not consume current named-resource `template.yaml` source files. Use prepared IDs with `ProviderSandbox` or the template's supplied `run.py`. See [resource fields and consumer limits](template-yaml-spec.md) and [runtime ownership/cleanup](../guide/template-workflows.md). diff --git a/docs/en/reference/template-yaml-spec.md b/docs/en/reference/template-yaml-spec.md index c8164987..1ba3560a 100644 --- a/docs/en/reference/template-yaml-spec.md +++ b/docs/en/reference/template-yaml-spec.md @@ -1,68 +1,55 @@ -# template.yaml Specification +# template.yaml resources and Python runtime -Use `specVersion: 1` and one local `template.yaml`. The complete field types and Provider subsets belong to the [template v1 schema](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/spec/template-v1.schema.json) and [template specification](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/docs/template-spec.md). Publication metadata and initialization questions belong to optional `registry.yaml`; local runs do not require it or `parameters`. - -Template files use YAML1.2 Core with strict UTF-8 and a 1 MiB limit. Plain `on` and dates such as `2026-11-12` remain strings. Duplicate keys, aliases, unsupported tags, non-string mapping keys and non-finite/non-JSON values are rejected before resource creation. +Keep one local `template.yaml` with `specVersion: 1`. The authoritative fields are in +the [template specification](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/docs/template-spec.md) +and [schema](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/spec/template-v1.schema.json) +for the matching template/CLI revision. Publication metadata and initialization questions +belong to `registry.yaml`; local execution does not depend on that file. | Field | Meaning | | --- | --- | | `specVersion` | Integer `1` | -| `name` | Resource name | -| `sandbox.provider` | Selected Provider ID; Python's explicit Provider context can fill it | -| `sandbox.template` | Exactly one `source`, `image` or `reference`; optional preparation `props` and `aliases` | -| `sandbox.instance` | Runtime TTL, environment, metadata and Provider-supported instance settings | -| `sandbox.start`, `sandbox.ready` | Whole-sandbox startup and readiness commands | -| `sandbox.ports` | Optional additional port numbers; no inferred protocol or automatic service start | -| `sandbox.services` | Endpoint map: protocol, integer version, port and optional operations | -| `deployment` | Native Serverless Devs project; `resources.*.component` and native `props` | -| `application` | Explicit supported application coordinator, currently `type: agents-api` | - -Preparation properties under `sandbox.template.props` do not become instance overrides. Existing template references cannot take preparation properties. Python consumes instance CPU/memory/disk/GPU, existing Volume-name mounts, environment, metadata and TTL when supported by the selected schema and Provider. It accepts the fixed `lifecycle: {onTimeout: kill, autoResume: false}` policy; pause/resume lifecycle orchestration is unavailable in this launcher and fails before creation. The independent `ProviderSandbox` lifecycle APIs retain their own contract. - -Generic instance TTL defaults to 300 seconds; Managed Agents API uses 3600. Explicit Python `timeout`, `cpu`, `memory`, `disk`, `gpu` and `volume_mounts` replace the corresponding instance values. Explicit `envs` and `metadata` merge by name; the launch ownership metadata is reserved. Memory/disk units and availability follow the Provider, not a universal cloud quota promise. Express's high-level schema uses integer MB values. - -Native `${...}` expressions require the real Devs parser. Python's prepared launcher accepts literals or an already resolved v1 snapshot and explicitly rejects unresolved expressions. Environment values are literal; empty strings do not implicitly read the host environment. Resolve secrets in the caller and pass them through `envs` or the resolved snapshot. Python does not construct source images or turn arbitrary component properties into cloud support. Custom Providers without actual v1 validators are refused by the prepared launcher; their independent Provider APIs remain available. +| `name` | Project/application name | +| `vars` | Optional reusable values with author-defined keys | +| `sandbox..provider` | Resource's Provider | +| `sandbox..template` | Template properties, including its region and image/reference/build declaration | +| `sandbox..template.buildConfig` | Dockerfile with optional context, or native Steps | +| `sandbox..volumes` | Named static Volumes, when supported by the selected Provider | +| `sandbox..actions` | Resource lifecycle actions | +| `serving..component` | Component source and pinned version | +| `serving..props` | Component-native properties | +| `serving..actions` | Resource lifecycle actions | + +The CLI evaluates native Devs expressions and prepares/deploys these resources. This +file does not declare each dynamic Sandbox instance or a universal application process. +The selected template supplies its runtime startup code. Native template +`startCommand`/`readyCommand` retain their Provider preparation semantics; they are not +a replacement for an application's create-time authenticated startup. + +## Use resources from Python + +Take the prepared template ID returned by deployment and follow the template's +`run.py` instructions, or call `ProviderSandbox.create` and explicitly start the +application. TTL, model credentials, runtime environment and dynamic mounts belong +to the instance or application runtime policy. Existing mounted Volumes remain owned +by whoever supplied them; deleting an instance does not delete those Volumes. + +The SDK's existing `launch_template`/`TemplateSession` interface accepts an earlier +prepared snapshot shape. Its YAML parser and discovery projection have not migrated +to the current named-resource source format. Resolving `${...}` first does not make +that source shape acceptable. Use the direct runtime path above; the current source +file must not be passed to that older snapshot interface. See +[launching and cleanup](../guide/template-workflows.md). -## Services and server policy - -`sandbox.services` describes endpoints; it does not enable server APIs or grant Provider operations. The launcher starts the entire template once. SandboxServer protocol v2 services receive health/discovery checks. Other protocols use `sandbox.ready` and are returned without inferred routes. - -The root `server` key is not a v1 resource field. SandboxServer endpoint policy remains its own runtime configuration, loaded through the documented policy file or `ABX_SERVER_POLICY_FILE` / `ABX_SERVER_POLICY`. `validate_server_block` remains a standalone structural validator; the real server validates policy values. See [fine-grained capabilities](../design/fine-grained-capabilities.md). Named commands are Python functions registered with `@command`; YAML does not create them. - -## Prepared reference example - -The referenced template must already contain the application and server dependencies. The existing Volume must be accessible to the selected Provider/account. Python creates and owns only the Sandbox; it never deletes the borrowed Volume. - -```yaml -specVersion: 1 -name: python-hello -sandbox: - provider: alicloud-express - template: - reference: base - instance: - timeout: 600 - cpu: 2 - memory: 2048 - envs: - APP_MESSAGE: hello - metadata: - purpose: example - volume_mounts: - /data: existing-volume-name - start: python /home/user/app/commands.py - ready: agent-sandbox-server healthcheck --port 9000 - services: - app: - protocol: agent-sandbox-server - version: 2 - port: 9000 - operations: [commands.list, commands.run] -``` - -For source preparation, replace `reference` with `source: {dockerfile: Dockerfile, context: .}` and use the CLI; Python still requires its prepared reference. Choose one startup owner so the image's native entrypoint does not launch the same application twice. See [launch and cleanup](../guide/template-workflows.md). +## Application endpoints and server policy -Provider authors can override the optional synchronous `Provider.validate_template_input(stage, value)` with their version's actual schema. Stages are `template.prepare` (template object) and `sandbox.create` (instance object). Return `False` or raise to reject. The inherited default is not a validator; asynchronous validation is rejected. Admission does not grant operations or forward instance fields that the high-level creation API has not implemented. +An open port does not start a process, grant a Provider operation or define a business +protocol. Use `await sandbox.application_endpoint(port)` for the selected Provider's +actual endpoint descriptor, or `application_client` for a running SandboxServer. +Gateway headers remain distinct from the application token. -`sandbox.ports` preserves optional extra ports such as browser debugging or a database port. The compiled port list is the sorted union with service ports. `session.endpoints[port]` returns the Provider descriptor for extra ports outside `sandbox.services`, including gateway headers only in memory. It creates no ServerClient and sends no health/discovery request. A declared port does not guarantee native TCP or public connectivity; use the Provider's actual addressing/protocol. `await sandbox.application_endpoint(port)` provides the same descriptor independently. Existing service clients remain in `session.services`. +SandboxServer API permissions are independent runtime policy. Load the documented +policy file or `ABX_SERVER_POLICY_FILE` / `ABX_SERVER_POLICY`. Named commands are real +Python functions registered with `@command`; YAML does not create them. See +[fine-grained capabilities](../design/fine-grained-capabilities.md). diff --git a/docs/zh/design/template-system.md b/docs/zh/design/template-system.md index 502c9bb5..6b8c4b08 100644 --- a/docs/zh/design/template-system.md +++ b/docs/zh/design/template-system.md @@ -1,41 +1,31 @@ # 模板系统 -模板采用规范 1,描述完整沙箱内容、启动与就绪命令,以及所有对外服务。 -启动模板不会再按工作流、单个操作或 application/exec/interpreter 类型选择其中一部分。 +模板包含可复用应用源码与命名 Sandbox/Serving 资源。使用 `specVersion: 1`、可选的 +作者自定义 `vars`、`sandbox.<名称>.template` 和组件原生 `serving.<名称>.props`。 +[字段参考](../reference/template-yaml-spec.md)提供规范入口及 Python 当前消费边界。 ## 职责 -模板负责应用源码、依赖、配置和启动。Provider 负责镜像上传注册、平台标识、沙箱创建和 -服务地址解析。CLI 准备源码并整体启动模板。Python 消费已准备好的引用,或连接既有沙箱, -不承担 Docker 和源码构建职责。 +模板负责应用源码、依赖和运行启动代码。Provider 负责原生准备、实例生命周期与端点解析。 +CLI 处理资源表达式、构建和部署;部署 Sandbox 资源不代表创建未来每个运行实例。 -## 启动与使用 +Python 通过 ProviderSandbox 使用已准备 ID,或连接已有实例。模板脚本负责动态创建实例, +携带私有运行配置启动应用。托管 Agents API 由 Worker 管理每个 Session 的实例, +业务客户端只调用同一个 Gateway。 -CLI 使用 `abx --provider PROVIDER deploy TEMPLATE_REF`;Python 使用 -`launch_template(manifest, provider=..., reference=...)`。启动前只检查创建、启动、 -就绪和清理实际需要的操作。缺少解释器不阻止无关应用启动。执行具体操作时, -Provider 和服务端策略仍负责实际能力与权限检查。 +## 运行与源码配置 -保留 `sandbox.services` 中所有服务。SandboxServer 协议 v2 额外检查 health/discovery;其他协议返回客户端, -由作者的就绪命令检查。多服务模板只启动一次,后续选择调用地址不会改变启动内容。 +当前命名资源 template.yaml 由 CLI 消费。SDK 现有 launch_template/TemplateSession +快照接口与发现投影尚未迁移到这些源码文件。保留其独立支持边界,不能因为版本编号相同 +就推断当前源码格式已经可用。 -## 清单与迁移 +直接运行路径不需要再增加一套 YAML 解析器或 Python 部署引擎。原生 Devs 负责表达式; +应用运行配置与服务端策略独立于资源准备。 -参见[字段参考](../reference/template-yaml-spec.md)和权威的 -[规范 1 schema](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/spec/template-v1.schema.json)。 -删除 `workflow_contract_version`、`default_workflow`、`workflows`,保留 -`specVersion: 1`、`sandbox.services`、`sandbox.start`、`sandbox.ready` 以及应用元数据。 -旧运行清单明确要求迁移,不静默选择旧默认项。源码位置、镜像引用和平台模板 ID -属于准备过程的输入,不再暴露为用户选择的启动流程。 +## 资源归属与清理 -## 资源归属与验证 +只删除所属应用创建的实例和资源。关闭本地连接不会删除借用实例。托管 Session 的关闭、 +清理 Operation 与公开删除分开;检查操作结果后再将计算资源视为释放。 -启动器记录创建意图与资源 ID,不自动重放结果不确定的创建请求。 -清理时尝试关闭所有客户端并删除自己创建的沙箱,保留失败记录供核对。 -连接已有沙箱不代表获得删除它的所有权。 - -目录收录或静态计划支持不等于实测成功。历史工作流证据保留,但不认证规范 1。 -模板元数据版本不代表有一个 Registry 版本存储服务器;复现应使用真实 Git 修订和运行输入。 - -参见 [Python 启动示例](../guide/template-workflows.md)、 +参阅 [Python 运行示例](../guide/template-workflows.md)、 [模板编写](../guide/authoring-templates.md)和[服务端 API](../guide/template-server-api.md)。 diff --git a/docs/zh/guide/authoring-templates.md b/docs/zh/guide/authoring-templates.md index 63ad7fa8..6d6916c1 100644 --- a/docs/zh/guide/authoring-templates.md +++ b/docs/zh/guide/authoring-templates.md @@ -1,6 +1,6 @@ # 编写模板 -模板包含应用源码、Dockerfile 和一个 `template.yaml`。使用 `specVersion: 1`;[字段参考](../reference/template-yaml-spec.md)说明资源、实例与原生 Serving 配置。可选的 `registry.yaml` 负责目录描述和初始化问题。依赖写入 Dockerfile 与语言原生依赖文件。 +模板包含应用源码、Dockerfile 和一个 `template.yaml`。使用 `specVersion: 1`;[字段参考](../reference/template-yaml-spec.md)说明命名资源与原生 Serving 配置;动态实例参数属于运行时代码。可选的 `registry.yaml` 负责目录描述和初始化问题。依赖写入 Dockerfile 与语言原生依赖文件。 Python 应用端点在镜像内安装 `agent-sandbox-server`,注册真实业务函数: @@ -15,8 +15,8 @@ if __name__ == "__main__": start(9000) ``` -在 `sandbox.start` / `sandbox.ready` 声明启动和就绪命令,在 `sandbox.services` 声明端点。YAML 不注册函数,也不会启用服务端默认关闭的组。服务端策略是独立运行时配置,通过镜像内策略文件或服务端文档说明的配置入口加载。参阅[服务端 API](template-server-api.md)。 +应用创建后的启动与就绪检查放在运行时代码中,例如随模板提供的 `run.py`。资源 YAML 声明可复用 Sandbox 模板与原生 Serving 属性。YAML 不注册函数,也不会启用服务端默认关闭的组。服务端策略是独立运行时配置,通过镜像内策略文件或服务端文档说明的配置入口加载。参阅[服务端 API](template-server-api.md)。 通过 [CLI 模板编写流程](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/zh/guide/authoring-templates.md)准备和发布源码。Python [启动已准备模板](template-workflows.md),或连接已有 Sandbox。镜像原生入口和 Python 启动命令应只有一个责任方,避免同一服务重复启动。 -通过 `session.servers["app"].commands.run("hello", name="Python")` 或显式解析的 `sandbox.application_client` 调用注册函数。应用令牌、网关请求头和 Sandbox API 凭据属于不同认证层。Shell 使用 `sandbox.commands.run(...)`,其存在不等于业务 API 或解释器能力。 +通过 `sandbox.application_client` 显式解析客户端后,使用 `client.commands.run("hello", name="Python")` 调用注册函数。应用令牌、网关请求头和 Sandbox API 凭据属于不同认证层。Shell 使用 `sandbox.commands.run(...)`,其存在不等于业务 API 或解释器能力。 diff --git a/docs/zh/guide/build-and-deploy.md b/docs/zh/guide/build-and-deploy.md index ccef68f0..df5b9e67 100644 --- a/docs/zh/guide/build-and-deploy.md +++ b/docs/zh/guide/build-and-deploy.md @@ -6,12 +6,11 @@ Python SDK 负责运行时调用。源码获取、构建、部署和源码版本 abx template init ./my-template --template python abx deploy ./my-template --name my-app --yes abx status my-app -abx sandbox command run my-app hello --arg name=Ada abx delete my-app --yes ``` 重复部署时,可先用 `abx template build ./my-template --out ./.abx/build.json --yes` 准备构建,再用 `abx deploy --build ./.abx/build.json --name my-app --yes` 复用。构建不创建运行实例。删除应用后,独立构建仍保留;用 `abx template build --clean ./.abx/build.json --yes` 清理不再被应用使用的构建资源。镜像等需手动清理的资源会明确列出。 -使用已有平台模板时,Python 可直接 `await ProviderSandbox.create(template=template_id, provider=provider)`。CLI 创建的应用则用其返回的沙箱 ID 连接,避免再创建一个实例。`launch_template` 是高级运行时入口:调用者必须确保镜像入口或平台启动命令不会重复启动清单中的服务。 +Sandbox 资源部署后返回可复用模板 ID。按所选模板的 `run.py` 说明创建并启动动态实例,或调用 `await ProviderSandbox.create(template=template_id, provider=provider)` 后显式启动应用。后续通过该 Sandbox ID 连接;删除已准备资源前,先关闭/删除自有动态实例。SDK 较早的 `launch_template` 快照接口不接受当前命名资源源码,详见下方运行指南。 [CLI 模板编写](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/zh/guide/authoring-templates.md) · [SDK 应用连接](template-workflows.md) diff --git a/docs/zh/guide/managed-agents-api.md b/docs/zh/guide/managed-agents-api.md index 4a177f8b..6d7f6de1 100644 --- a/docs/zh/guide/managed-agents-api.md +++ b/docs/zh/guide/managed-agents-api.md @@ -3,16 +3,15 @@ [English](../../en/guide/managed-agents-api.md) 应用只配置一个 Gateway 地址和业务 Bearer Token,即可让编码 Agent 在独立沙箱中运行。 -Session 在首次输入时创建沙箱,后续轮次复用工作区。可选托管运行时支持内置极速版提供方与明确配置的 -Codex、Qwen Code 模型。它采用部分 OpenAI 风格资源结构,不声明 OpenAI SDK 互操作或官方托管 harness 等价能力。 +Session 在首次输入时创建沙箱,后续轮次复用工作区。可选托管运行时支持内置极速版提供方及显式原生 Harness +模型绑定,凭据与版本要求见 [Harness 配置](managed-harnesses.md)。它采用部分 OpenAI 风格资源结构, +不声明完整 OpenAI SDK 互操作或官方托管 Harness 等价能力。 -安装匹配版本的客户端、服务端与托管部署依赖: +业务客户端只需 `httpx` 等 HTTP 客户端。部署方应使用模板指定的匹配 client/server 运行时。 +六种 Harness 所需的0.4.0a8仍是未发布候选,不能用只承接较早 Codex/Qwen 子集的0.4.0a7替代。 +开发使用参阅[源码安装](install-python.md)及 [Harness 配置](managed-harnesses.md)。 -```bash -python -m pip install --pre 'agent-sandbox-client[managed-agents]==0.4.0a7' -``` - -[agents-api 模板](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/tree/main/agents-api) +[agents-api 模板](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/docs/agents-api-harnesses.zh-CN.md) 提供应用配置;使用匹配的 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) 部署。 应用连接返回的 Gateway endpoint,无需配置每个沙箱的 endpoint。 @@ -45,6 +44,13 @@ with httpx.Client( Session 的 `created_at` 与 `last_active_at` 为整数秒 Unix 时间戳。`required_actions` 与 `vault_ids` 返回空数组;当前不支持客户端待办动作或 Vault 绑定。 +Turn 的 `created_at`、`started_at`、`completed_at` 同样使用整数秒,未知的时间返回 `null`。 +新 Turn 优先使用原生运行时的启动时间,否则使用 Worker 首次观察到执行的时间。 +`agent_id` 对应 Session 冻结的 Agent 配置,`subagent_id` 为 `null`。 +内联配置获得稳定的 Session 内身份,但不会因此创建可单独查询的已保存 Agent 定义。 +执行中与结束时的 Turn 事件包含与 `/turns` 查询一致的公开 Turn 结构。 +这些结构适用于本文的 HTTP 流程,不代表完整 OpenAI SDK 互通,也不代表支持能力声明中尚未提供的功能。 + 创建返回 `201`。接收输入后生成持久 Submission,真正开始执行时才出现公开 Turn。 轮询 Session、`/turns` 和 `/artifacts` 集合,通过 `/v1/agents/sessions/{id}/artifacts/{artifact_id}/content` 下载已发布产物。 @@ -120,10 +126,14 @@ Gateway 使用 HTTP/1.1 chunked 事件流响应;FC 部署需要支持流式响 | 托管生命周期 | 关闭、Operation、Submission 排队、列表、详情与取消 | `GET /v1/agent-sandbox/capabilities` 返回支持路由与部署预算。 +运行时列表说明已配置的适配器;`installed: null` 表示 Gateway 尚未检查 Guest 二进制安装。 +Guest 就绪与实际任务执行仍是独立条件。 列表接受 `limit`、`order`、`after`,下一页使用 `last_id` 或限定范围的 `next_cursor`。 Session 仅支持更新 metadata。Function tools、任意 MCP 配置、subagents、steering、图像/音频输入、 动态模型和 settings 更新会明确拒绝;所选 CLI 自带的 shell、文件工具仍在沙箱内可用。 -工具墙钟期限从观察到原生工具开始事件起计算。运行时 epoch 改变或提交收据不确定时冻结执行, +`adapter_capabilities` 说明所选 Harness 的流式粒度与工具事件时点。仅 `per_tool_timeout` +为 true 时执行单工具期限;固定版 OpenCode 在工具完成后才报告,因此只能执行整轮期限。 +运行时 epoch 改变或提交收据不确定时冻结执行, 不会自动重放输入。 FC 部署要求 PostgreSQL;SQLite 仅用于明确的本地模式。存储、队列、执行时间、事件与订阅者均有有限预算, @@ -132,7 +142,7 @@ FC 部署要求 PostgreSQL;SQLite 仅用于明确的本地模式。存储、 ## Sandbox 实例配置 -v1 `sandbox.instance` 控制每个 Session 新建的 Sandbox:`timeout`、CPU/内存/磁盘/GPU、已有卷名称挂载与用户元数据。托管 TTL 默认3600秒,内部 lifetime 预算由这一值派生。更新应用时,已有 Session 保留其配置快照和 Worker 路由。`sandbox.template.props` 是模板准备参数,不会自动变成实例规格。 +模板的 `vars.policy.instance.timeout` 控制 Session Sandbox 生命周期,默认3600秒。当前配方只开放该生命周期设置;定制应用的部署方还可在 SDK 私有 `ManagedConfig.instance` 中使用已承接的实例规格、已有卷挂载与元数据。这些私有运行设置不是公开 YAML 的 `sandbox.instance` 区块。`sandbox.<名称>.template` 属性在准备阶段生效。更新应用后,已有 Session 保持冻结设置与原 Worker 路由。 所有自定义环境值都按敏感数据处理,包括看似普通的值。部署器只在编译配置中保存 `instanceEnvNames`,值仅通过 Worker 的 `ABX_MANAGED_SANDBOX_ENV_JSON` 或 `_FILE` 私有来源解析,不进入 Session settings 或公开 plan。私有映射的名字必须与声明完全一致。模型凭据使用独立模型 binding。`ABX_*`、`OPENAI_*`、`QWEN_*`、`CODEX_*`、`PYTHON*`、`LD_*`、`HOME`、`PATH`、`SHELL`、`USER`、`LOGNAME`、`ANTHROPIC_API_KEY`、`DASHSCOPE_API_KEY` 属于运行时/模型控制,不能由自定义环境覆盖。 @@ -143,7 +153,7 @@ Worker 自定义环境配置前缀为 `ABX_MANAGED_SANDBOX_ENV`,与其他配 ## 部署方配置 入口为 `python -m agent_sandbox.managed_agents gateway|worker|dispatcher`。 -沙箱镜像运行 `python -m agent_sandbox.server.managed --port 9000`,并需安装 Codex 或 Qwen Code。 +沙箱镜像运行 `python -m agent_sandbox.server.managed --port 9000`,并需安装 所选固定版本的 Harness 及匹配服务端运行时。 以下每种配置只能选择一个 `_FILE` 或 `_JSON` 来源: @@ -151,13 +161,17 @@ Worker 自定义环境配置前缀为 `ABX_MANAGED_SANDBOX_ENV`,与其他配 | --- | --- | | `ABX_MANAGED_CONFIG` | 编译后的 revision、application ID、模板、模型/adapter 白名单、`modelEnvAllowlist`、Session/存储/执行预算、`expectedStateId` 与保留 Worker 映射 | | `ABX_MANAGED_AUTH` | `tokens: [{sha256,owner,scopes,expiresAt?}]`,scope 为 `agents:read`、`agents:write` | -| `ABX_MANAGED_MODEL_CONFIG` | 仅 Worker 使用 `{apiKey,baseUrl,model,adapter}` | +| `ABX_MANAGED_MODEL_CONFIG` | 仅 Worker 使用 `{apiKey,model,adapter}`;适用的 Harness 另需 `baseUrl` | | `ABX_MANAGED_PROVIDER_CONFIG` | Worker/Dispatcher 使用 `{provider:"alicloud-express",apiKey,baseUrl,domain,region}` | `ABX_MANAGED_DATABASE_URL` 指向 PostgreSQL。部署会固定持久状态身份,替换为空数据库会被拒绝,已有暖实例也会校验;同一状态库的凭据与 CA 轮换仍可使用。`ABX_MANAGED_INTERNAL_TOKEN` 认证私有角色调用, 保留旧 revision 排空期间应保持稳定。`ABX_MANAGED_FC_ENDPOINT` 指定派发所用 FC 服务主机。 私有控制请求可省略 `revision` 来操作整个应用,或提供非空 revision。私有 HTTP 监听端会在访问或修改应用状态前拒绝空字符串,并返回 HTTP 400。 -`modelEnvAllowlist` 必须明确允许 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`。 +`modelEnvAllowlist` 必须精确匹配所选 Harness 的原生环境名:Codex/Qwen/OpenCode 使用 +`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`;Claude Code 使用 +`ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`;DeepSeek Harness 使用 +`DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL`;Qoder 使用原生 +`QODER_PERSONAL_ACCESS_TOKEN`,不虚构模型端点,模型 ID 保留在显式绑定中。模板 bootstrap 负责填入这些名字。 凭据仅交给需要它的角色,不写入镜像或公开资源。文件来源的业务认证每次重读以支持撤权,并执行可选到期限制。 正常版本更新通过上一份部署收据复用现有应用与数据库。完整销毁部署后,外部管理的 PostgreSQL diff --git a/docs/zh/guide/managed-harnesses.md b/docs/zh/guide/managed-harnesses.md new file mode 100644 index 00000000..eb57e87f --- /dev/null +++ b/docs/zh/guide/managed-harnesses.md @@ -0,0 +1,46 @@ +# 托管 Agent Harness + +托管 Gateway 对各 Harness 使用相同的 Session、输入、Turn、Item、事件、文件和产物协议。 +部署应用时选择 `agents-api-codex` 等对应模板。Session 生命周期内原生 Harness 保持固定; +模型凭据通过私有 Worker 注入 Sandbox,与 Gateway 的客户端认证分开配置。 + +本文新增适配对应客户端/服务端 **0.4.0a8** 源码。构建镜像前先确认版本是否已经发布; +尚未发布的候选版本不能当作可安装的 PyPI 版本。只更新宿主客户端不会更新已有镜像内的服务端。 + +| 适配器 | 原生命令 | 凭据 | 模型端点 | +| --- | --- | --- | --- | +| `codex` | `codex exec --json` | `OPENAI_API_KEY` | 显式配置兼容 Responses 的 `OPENAI_BASE_URL` | +| `qwen-code` | `qwen --output-format stream-json` | `OPENAI_API_KEY` | 显式配置兼容 Chat Completions 的 `OPENAI_BASE_URL` | +| `claude-code` | `claude -p --output-format stream-json` | `ANTHROPIC_API_KEY` | 显式配置兼容 Messages 的 `ANTHROPIC_BASE_URL` | +| `qoder` | `qoder --print --output-format stream-json` | `QODER_PERSONAL_ACCESS_TOKEN` | Qoder 原生服务;此适配器不配置自定义模型端点 | +| `opencode` | `opencode run --format json` | `OPENAI_API_KEY` | 显式配置兼容 Chat Completions 的 `OPENAI_BASE_URL`,生成原生 `abx` Provider 配置 | +| `deepseek-harness` | `dsh --profile headless --json` | `DEEPSEEK_API_KEY` | 显式配置兼容 Messages 的 `DEEPSEEK_BASE_URL`;官方根地址为 `https://api.deepseek.com/anthropic` | + +按对应模板的说明修改私有凭据来源和配置,不要将凭据写入镜像或提交到 `template.yaml`。 +应用的模型 ID 绑定模板选定的 Harness。Qoder 的模型须属于该 PAT 账号可用的模型; +OpenAI 模型 Key 不能代替 Qoder PAT。PAT 从 [Qoder 账号集成页](https://qoder.com/account/integrations) +生成。Qoder BYOK 取决于账号套餐和模型目录,按官方 `/model` 向导配置;本适配器不编造手动 BYOK 配置。 + +原生模型名称传给对应 Harness。Codex/Qwen/OpenCode 使用 `OPENAI_MODEL`, +Claude 使用 `ANTHROPIC_MODEL`,DeepSeek Harness 使用 `DEEPSEEK_MODEL`。 +Worker 仅注入所选适配器需要的变量,拒绝不匹配的模型/Harness 绑定和无关凭据名称。 + +每个 Turn 实际运行原生 CLI,后续 Turn 在同一个 Session Sandbox 中通过精确原生会话 ID 续接。 +Close 释放计算并保留 Gateway 已存结果;新建 Sandbox 不能承诺恢复已经删除的计算资源内的 +文件或原生历史。公开生命周期参见[托管 API 指南](managed-agents-api.md)。 + +Codex、Claude 和 Qwen 可以提供原生增量事件。OpenCode JSON 文本和 DeepSeek Harness +无头文本分别对应完整消息或已提交步骤,不等于逐 Token 输出。收到原生终态消息也不代表 +所有进程均已退出;桥接同时检查进程退出与所属子进程清理,无法确认时保留不确定状态。 + +OpenCode 1.19.5 只在工具完成后报告工具记录,不能据此从工具真实开始计时执行单工具超时; +整体任务期限和所属进程清理仍生效。通用本地运行时中,此适配器支持 `read_only` 或 +`full_access`,拒绝无法可靠映射的 `workspace_write`;托管 Session 在 Sandbox 内使用 `full_access`。 + +新增适配仍为实验能力。Qoder、OpenCode、DeepSeek Harness 暂未通过此适配器 API +映射外部 MCP 配置。Qoder 1.1.90 的实际 CLI 没有部分新文档所述的 `--max-turns`, +因此会拒绝配置该次数限制。Steering、函数、子 Agent 和工具能力取决于 Gateway 能力声明 +与原生 Harness。使用某个 Provider、模型端点或账号类型前,查看对应模板的实际验证范围。 + +DeepSeek 适配器调用官方 `@deepseek-ai/dsh`。旧 `deepseek-harness` 命名命令模板是项目自研 +工具循环,其模型实跑记录不能替代官方原生适配的验证。 diff --git a/docs/zh/guide/sdk-usage.md b/docs/zh/guide/sdk-usage.md index ea3100b5..1f650bab 100644 --- a/docs/zh/guide/sdk-usage.md +++ b/docs/zh/guide/sdk-usage.md @@ -261,7 +261,7 @@ async for event in watcher: `sandbox.network` 子模块用于计算端口访问 URL(纯本地计算,不涉及网络请求)。 -> 端口地址由所选 Provider 提供。v1 模板通过 `sandbox.services` 声明服务端点,额外端口使用 `sandbox.ports`;声明本身不会授予 Provider 操作权限。模板启动器要求所选 Provider 对声明端点实际支持 `ports.resolve`。 +> 端口地址由所选 Provider 提供,使用运行实例的 `application_endpoint` 或 `application_client` 解析。端口放行不代表应用已经启动或 Provider 操作已获授权。当前命名资源 YAML 与 Python 运行方式见[模板使用](template-workflows.md)。 ```python # 获取端口 URL diff --git a/docs/zh/guide/template-workflows.md b/docs/zh/guide/template-workflows.md index 21fb04ac..5545d852 100644 --- a/docs/zh/guide/template-workflows.md +++ b/docs/zh/guide/template-workflows.md @@ -1,6 +1,6 @@ # 启动和使用模板 -源码模板使用 `abx --provider PROVIDER deploy SOURCE --name my-app --yes` 准备并启动,再用 Python 通过返回的沙箱 ID 和同一个 Provider 连接。平台已经提供模板 ID 时,可以直接用 Python 创建。 +源码模板使用 `abx --provider PROVIDER deploy SOURCE --name my-app --yes` 准备资源。普通 Sandbox 应用使用随模板提供的 `run.py` 创建和启动,再用返回的 Sandbox ID 与相同 Provider 连接。平台已经提供模板 ID 时,可以直接用 Python 创建实例。 ## Python 应用调用 @@ -21,47 +21,30 @@ finally: 如果 `X-Access-Token` 请求头未被占用,客户端还会通过服务端已有的这个请求头发送同一个显式应用令牌,使认证能通过 OpenSandbox 1.1.1 等会过滤 `Authorization` 的代理。已有网关请求头(包括注入 HTTP 客户端的默认请求头)不会被覆盖;需要 Bearer 的服务仍可使用原认证方式。 -高级准备场景中,`launch_template` 根据已准备好的 Provider 引用创建新沙箱,并执行清单的 `sandbox.start`。该引用的原生启动命令或镜像入口不能同时启动同一个服务。构建产物保留其启动声明,不能把准备好的引用理解为可以重复启动同一服务。如果 CLI 已启动应用,按上文连接它返回的沙箱即可。 +## 创建并启动自有实例 -确认准备阶段没有重复启动后,让 Python 负责启动和清理: +源码模板的 `abx deploy` 准备可复用的 Sandbox 资源,并部署其中声明的 Serving 资源。 +普通 Sandbox 模板应按自己的 README,把返回的模板 ID 交给随模板提供的 `run.py`。 +运行脚本负责创建实例、启动应用并保存私有会话文件。凭据、模型配置、端口和清理操作 +以该模板文档为准。只创建实例,不会自动完成要求显式启动的应用流程。 -```python -from agent_sandbox.api import launch_template - -async with await launch_template( - "template.yaml", provider="opensandbox", - reference=prepared_reference, application_token=application_token, -) as session: - result = await session.run_command("hello", name="Python") -``` - -不再选择工作流。Python 创建一个沙箱,执行一次 `sandbox.start`,检查 `sandbox.ready`, -并解析 `sandbox.services` 中所有服务。SandboxServer 协议 v2 服务执行 health/discovery 检查; -其他协议由模板的就绪命令检查,返回对应客户端但不猜测其协议路由。 -`session.services` 包含全部服务客户端,`session.servers` 包含 SandboxServer 客户端。 -只有一个 SandboxServer 时可以使用 `session.server` 和 `session.run_command`; -多个时使用 `session.servers["服务名"].commands.run(...)` 选择调用目标。 -这不会改变已经整体启动的模板内容。 - -Python 不构建源码;源码准备由 CLI 负责,按上文选择一个启动方。 -模板也可声明固定摘要的 `sandbox.template.image`,或者 `sandbox.provider` 与 `sandbox.template.reference` 原生模板标识。 -引用由 Provider 解释,原生 ID 不需要虚构版本。已有外部 HTTP 服务直接使用 -`ServerClient`;应用部署 hook 仍由部署编排器处理。 - -启动器冻结 manifest、记录创建意图和所拥有的资源 ID,仅删除自己创建的沙箱。 -创建结果不确定时不自动重试,可使用 `abx_template_run` 元数据核对资源。 -后续服务失败也会关闭之前解析的所有客户端。日志不记录令牌、环境变量值和签名 URL, -也不等于云端验证证据。同一个最终 `ABX_SERVER_TOKEN` 同时用于沙箱环境和客户端。 - -收到进程启动确认后,启动器会在一个 `readiness_timeout` 预算内重复执行尚未成功的 `sandbox.ready`。每次探测受剩余预算约束,退出码为 0 时才完成就绪检查;预算耗尽会抛出 `readiness-command-failed` 并删除本次创建的沙箱,取消启动同样保留资源清理。进程已经启动与应用已经就绪是两个独立条件。 +应用自行管理实例时,通过 `ProviderSandbox.create` 传入已准备模板 ID 和运行参数, +使用 `start_server` 启动文档声明的进程,再解析应用客户端。只删除自己创建的实例。 +连接已有实例后关闭连接只释放本地资源,不代表取得该实例的删除归属。 ## 资源配置 -v1 示例描述更新后的 SDK 源码消费者。已安装发行物尚无该能力时,使用匹配的[源码安装](install-python.md);包版本元信息相同不代表都具备 v1 支持。 +当前[资源格式](../reference/template-yaml-spec.md)采用命名 Sandbox 和 Serving。 +原生表达式、构建和部署由 CLI 处理。Python 使用已准备 ID 和显式运行配置创建实例, +不会解析当前命名资源的 `template.yaml`。 -使用 [v1 资源字段](../reference/template-yaml-spec.md)。解析字面量已准备模板无需安装 CLI,所选 Provider 仍可能有其自身运行时依赖;原生表达式需先由 Devs 解析器解析。`sandbox.instance.timeout` 提供 TTL,只有显式 Python `timeout` 才会覆盖;省略时保留清单值。实例规格、已有卷、环境变量和元数据会实际传入创建请求。环境值不会隐式读取宿主环境。应用部署由协调器负责,Python 在创建 Sandbox 前拒绝这类输入。 +现有高级 `launch_template` API 仍接受其较早的已准备快照格式,不接受当前命名资源源码文件。 +它的 `TemplateSession` 服务及端口助手属于该独立接口;不要把当前模板的 `template.yaml` +直接交给它。当前资源格式应使用模板随附脚本或显式实例 API。 +实例 TTL、环境变量、元数据与挂载覆盖值属于实例创建或应用运行策略。 -额外声明的 `sandbox.ports` 通过 `session.endpoints[端口]` 返回 Provider 描述,不为其创建客户端或发送探测。网关请求头只在内存中,不进入公开 plan 或日志。端口声明不保证原生 TCP 可达,也不会启动该服务。 +部署托管 Agents API 后,业务客户端使用其 Gateway HTTP 入口;动态 Sandbox 创建及清理 +由模板的 Worker 负责。参阅[托管 API 指南](managed-agents-api.md)。 ## 解释器操作 @@ -84,9 +67,7 @@ finally: await sandbox.kill() # 本段代码创建并负责删除这个沙箱 ``` -v1 清单声明 `sandbox.provider: alicloud-express`、`sandbox.template.reference: base` 和 -`sandbox.services: {}` 后,可以调用 `launch_template(manifest, provider="alicloud-express")`, -通过异步上下文管理器自动删除自己创建的沙箱。不再声明或选择工作流。 +已有卷属于借用资源,实例清理不会删除这些卷本体。 在 `code-interpreter-v1` 上运行 shell 命令,并不代表调用了解释器 API。极速版、E2B 和 REST 的项目适配器尚未接入统一解释器操作,需要时使用已记录的平台原生 SDK;CubeSandbox 和容器版接入了持久默认上下文操作。 diff --git a/docs/zh/reference/api-reference.md b/docs/zh/reference/api-reference.md index 26343167..a8529ab3 100644 --- a/docs/zh/reference/api-reference.md +++ b/docs/zh/reference/api-reference.md @@ -512,4 +512,4 @@ class SandboxStatus(str, Enum): 接受云 AccessKey 的 Provider 生命周期方法同时接受 `security_token`,环境变量为 `ALIBABA_CLOUD_SECURITY_TOKEN`。`ProviderSandbox.create` 另接受 `network`、`allow_internet_access`。`ProviderSandbox.connect(..., traffic_access_token=...)` 保留 GET 只读连接语义;`application_client(..., traffic_access_token=...)` 仅为该应用客户端覆盖网关凭据。详见[提供方命令](../guide/provider-commands.md)和[认证](../guide/authentication.md)。 -canonical v1 已准备模板使用 `launch_template(..., timeout=None)` 保留清单实例 TTL;显式规格和环境参数覆盖对应值。`TemplateSession.services` 保存实际声明的服务客户端,`TemplateSession.endpoints` 保存附加端口描述,请求头只在内存中。参阅[模板字段](template-yaml-spec.md)与[启动归属及清理](../guide/template-workflows.md)。 +`launch_template` 与 `TemplateSession` 保留较早的已准备快照接口,不消费当前命名资源 `template.yaml` 源码。使用已准备 ID 与 `ProviderSandbox`,或模板随附 `run.py`。参阅[资源字段与消费边界](template-yaml-spec.md)及[运行归属与清理](../guide/template-workflows.md)。 diff --git a/docs/zh/reference/template-yaml-spec.md b/docs/zh/reference/template-yaml-spec.md index 527503ae..6795f347 100644 --- a/docs/zh/reference/template-yaml-spec.md +++ b/docs/zh/reference/template-yaml-spec.md @@ -1,68 +1,46 @@ -# template.yaml 规范 +# template.yaml 资源与 Python 运行时 -使用 `specVersion: 1`,本地资源配置只需一个 `template.yaml`。完整字段类型和各 Provider 的参数子集见 [template v1 schema](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/spec/template-v1.schema.json) 与[模板规范](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/docs/template-spec.md)。上架元信息和初始化问题属于可选的 `registry.yaml`;本地运行无需该文件,也无需 `parameters`。 - -模板文件使用 YAML1.2 Core,必须为严格 UTF-8,最大 1 MiB。`on` 和 `2026-11-12` 等未加引号的日期保持字符串。重复键、别名、不支持的标签、非字符串键及非有限或非 JSON 值会在创建资源前被拒绝。 +本地保留一个 `template.yaml`,使用 `specVersion: 1`。完整字段以匹配模板及 CLI 修订的 +[模板规范](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/docs/template-spec.zh-CN.md) +和 [schema](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/spec/template-v1.schema.json) +为准。上架元信息和初始化问题属于 `registry.yaml`;本地运行不依赖该文件。 | 字段 | 含义 | | --- | --- | | `specVersion` | 整数 `1` | -| `name` | 资源名称 | -| `sandbox.provider` | Provider ID;可由 Python 显式选择的 Provider 补全 | -| `sandbox.template` | `source`、`image`、`reference` 三选一;可带构建 `props` 和 `aliases` | -| `sandbox.instance` | 实例 TTL、环境变量、元数据及 Provider 支持的实例参数 | -| `sandbox.start`、`sandbox.ready` | 整体启动和就绪检查命令 | -| `sandbox.ports` | 可选的附加端口号,不推测协议或自动启动服务 | -| `sandbox.services` | 端点映射:协议、整数版本、端口及可选 operations | -| `deployment` | 原生 Serverless Devs 项目,直接使用组件名和原生 props | -| `application` | 显式选择应用协调器,目前为 `type: agents-api` | - -`sandbox.template.props` 是准备模板时的参数,不是实例覆盖值。引用已有模板时不能声明准备参数。Python 按选定 schema 和 Provider 消费 instance 的 CPU、内存、磁盘、GPU、已有卷名称挂载、环境变量、元数据和 TTL。启动器只接受固定的 `lifecycle: {onTimeout: kill, autoResume: false}`;暂停/自动恢复协调尚未承接,会在创建前拒绝。独立 `ProviderSandbox` 生命周期 API 保持其自身契约。 - -普通实例 TTL 默认 300 秒,托管 Agents API 默认为 3600 秒。Python 显式 `timeout`、`cpu`、`memory`、`disk`、`gpu`、`volume_mounts` 替换对应实例值;显式 `envs` 和 `metadata` 按名称合并,启动器自己的归属标签保留。内存/磁盘单位与可用性由 Provider 决定;Express 高层 schema 使用整数 MB,不代表所有云账号都能创建这些规格。 - -原生 `${...}` 表达式必须由真实 Devs 解析器执行。Python 已准备模板启动器接受字面量或已解析的 v1 快照,明确拒绝未解析表达式。环境变量值按字面量使用,空字符串不会隐式读取宿主环境。调用方应自行解析秘密来源,通过 `envs` 或已解析快照传入。Python 不构建源码镜像,也不因某个组件字段存在就承诺云端支持。缺少真实 v1 校验器的自定义 Provider 会被模板启动器拒绝,独立 Provider API 仍可使用。 +| `name` | 项目/应用名称 | +| `vars` | 可选的复用值,键名由作者自定 | +| `sandbox.<名称>.provider` | 该资源的 Provider | +| `sandbox.<名称>.template` | 模板属性,包含地域、镜像/引用/构建声明 | +| `sandbox.<名称>.template.buildConfig` | Dockerfile 配合可选 context,或原生 Steps | +| `sandbox.<名称>.volumes` | 所选 Provider 支持的命名静态卷 | +| `sandbox.<名称>.actions` | 资源生命周期动作 | +| `serving.<名称>.component` | 组件来源及固定版本 | +| `serving.<名称>.props` | 组件原生属性 | +| `serving.<名称>.actions` | 资源生命周期动作 | + +CLI 负责原生 Devs 表达式、资源准备和部署。该文件不声明每个动态 Sandbox 实例, +也不声明通用应用进程。具体模板提供运行时代码;模板原生 `startCommand`、`readyCommand` +保留 Provider 准备语义,不替代应用在实例创建后携带认证的启动步骤。 + +## Python 使用方式 + +将部署返回的模板 ID 交给模板的 `run.py`,或使用 `ProviderSandbox.create` 并显式启动应用。 +TTL、模型凭据、运行环境与动态挂载属于实例创建或应用运行策略。已有卷保持原归属, +删除实例不会删除借用卷本体。 + +SDK 现有 `launch_template`/`TemplateSession` 接受较早的已准备快照格式,其 YAML 解析器 +和发现投影尚未迁移到当前命名资源源码。即使先解析 `${...}`,也不会让两种结构变得相同。 +当前源码文件应使用上面的直接运行路径,不要交给旧快照接口。 +参阅[启动与清理](../guide/template-workflows.md)。 -## 服务与服务端策略 - -`sandbox.services` 声明端点,不会启用服务端 API 或授予 Provider 操作。启动器一次启动整个模板,检查 SandboxServer 协议 v2 的健康和发现接口;其他协议使用 `sandbox.ready`,不会推测其路由。 - -根 `server` 不是 v1 资源字段。SandboxServer 端点策略仍通过其运行时策略文件或 `ABX_SERVER_POLICY_FILE` / `ABX_SERVER_POLICY` 加载。独立的 `validate_server_block` 结构校验器保留,实际服务端负责校验策略值。参阅[细粒度能力](../design/fine-grained-capabilities.md)。命名命令来自 Python `@command` 注册函数,YAML 不生成函数。 - -## 已准备模板示例 - -引用的模板必须已经包含应用及服务端依赖,已有卷必须对该 Provider/账号可用。Python 只创建并拥有 Sandbox,不删除借用卷本体。 - -```yaml -specVersion: 1 -name: python-hello -sandbox: - provider: alicloud-express - template: - reference: base - instance: - timeout: 600 - cpu: 2 - memory: 2048 - envs: - APP_MESSAGE: hello - metadata: - purpose: example - volume_mounts: - /data: existing-volume-name - start: python /home/user/app/commands.py - ready: agent-sandbox-server healthcheck --port 9000 - services: - app: - protocol: agent-sandbox-server - version: 2 - port: 9000 - operations: [commands.list, commands.run] -``` - -源码准备时将 `reference` 换为 `source: {dockerfile: Dockerfile, context: .}` 并使用 CLI,Python 仍需准备后的引用。启动命令和镜像原生入口应只有一个启动责任方,避免同一服务启动两次。参阅[启动与清理](../guide/template-workflows.md)。 +## 应用端点与服务端策略 -Provider 作者可覆盖可选的同步 `Provider.validate_template_input(stage, value)`,使用该版本的真实 schema。阶段为 `template.prepare`(模板对象)和 `sandbox.create`(实例对象),返回 `False` 或抛错表示拒绝。继承的默认方法不算校验器,异步校验会被拒绝。校验通过不授予操作能力,也不代表高层创建 API 自动承接了尚未实现的实例字段。 +端口放行不代表进程已经启动、Provider 操作已获授权,也不定义业务协议。 +`await sandbox.application_endpoint(port)` 返回所选 Provider 的实际端点描述; +已运行的 SandboxServer 可使用 `application_client`。网关请求头与应用令牌分属不同认证层。 -`sandbox.ports` 保留浏览器调试、数据库等可选附加端口;编译端口列表为它与服务端口的排序去重并集。`session.endpoints[端口]` 返回未归属 `sandbox.services` 的附加端口的 Provider 描述,网关请求头只在内存中。它不创建 ServerClient,也不发送 health/discovery 请求。声明端口不保证原生 TCP 或公网可达,实际地址与协议由 Provider 决定。也可单独调用 `await sandbox.application_endpoint(port)`,已有服务客户端仍在 `session.services`。 +SandboxServer API 权限使用独立运行时策略,通过文档说明的策略文件或 +`ABX_SERVER_POLICY_FILE`/`ABX_SERVER_POLICY` 加载。命名命令来自 `@command` +注册的真实 Python 函数,YAML 不生成函数。参阅[细粒度能力](../design/fine-grained-capabilities.md)。 diff --git a/server-sdk/src/agent_sandbox/server/_version.py b/server-sdk/src/agent_sandbox/server/_version.py index 3861d95e..ad413a81 100644 --- a/server-sdk/src/agent_sandbox/server/_version.py +++ b/server-sdk/src/agent_sandbox/server/_version.py @@ -1 +1 @@ -__version__ = "0.4.0a7" +__version__ = "0.4.0a8" diff --git a/server-sdk/src/agent_sandbox/server/agents/adapters/__init__.py b/server-sdk/src/agent_sandbox/server/agents/adapters/__init__.py index 986345c2..484b0f61 100644 --- a/server-sdk/src/agent_sandbox/server/agents/adapters/__init__.py +++ b/server-sdk/src/agent_sandbox/server/agents/adapters/__init__.py @@ -19,6 +19,9 @@ from .codex import CodexAdapter from .command import CommandAdapter from .cursor import CursorAdapter +from .deepseek_harness import DeepSeekHarnessAdapter +from .opencode import OpenCodeAdapter +from .qoder import QoderAdapter from .qwen_code import QwenCodeAdapter __all__ = [ @@ -55,6 +58,9 @@ def __init__(self, *, builtins: bool = True) -> None: CursorAdapter, QwenCodeAdapter, CommandAdapter, + QoderAdapter, + OpenCodeAdapter, + DeepSeekHarnessAdapter, ): self.register(cls) diff --git a/server-sdk/src/agent_sandbox/server/agents/adapters/base.py b/server-sdk/src/agent_sandbox/server/agents/adapters/base.py index c4f938c4..0b3f65ce 100644 --- a/server-sdk/src/agent_sandbox/server/agents/adapters/base.py +++ b/server-sdk/src/agent_sandbox/server/agents/adapters/base.py @@ -45,6 +45,7 @@ class AdapterCapabilities: max_turns: bool = False budget: bool = False experimental: bool = False + tool_events: str = "live" # "live" | "completed_only" @dataclasses.dataclass diff --git a/server-sdk/src/agent_sandbox/server/agents/adapters/deepseek_harness.py b/server-sdk/src/agent_sandbox/server/agents/adapters/deepseek_harness.py new file mode 100644 index 00000000..cebe97e2 --- /dev/null +++ b/server-sdk/src/agent_sandbox/server/agents/adapters/deepseek_harness.py @@ -0,0 +1,181 @@ +"""Official DeepSeek Harness headless adapter (not a project-owned model loop).""" + +from __future__ import annotations + +import json +import os +from typing import TYPE_CHECKING, ClassVar + +from .. import events as ev +from .base import ( + AdapterCapabilities, + AgentAdapter, + EventParser, + Invocation, + InvocationFile, + TurnContext, +) + +if TYPE_CHECKING: + from ..config import AgentSpec + from ..events import ParsedEvent + +__all__ = ["DeepSeekHarnessAdapter", "DeepSeekHarnessParser"] + + +class DeepSeekHarnessParser(EventParser): + """Read committed-step events and require the authoritative final reason.""" + + def __init__(self) -> None: + self.final = False + self.sequence = 0 + + def feed(self, line: str) -> list[ParsedEvent]: + """Normalize native JSON without presenting step text as token deltas.""" + try: + obj = json.loads(line) + except (ValueError, TypeError): + return [ev.log(line)] + if not isinstance(obj, dict): + return [] + kind = obj.get("type") + self.sequence += 1 + identity = "dsh-" + str(self.sequence) + if kind == "session" and isinstance(obj.get("sessionId"), str): + return [ev.session_event(obj["sessionId"])] + if kind in {"text", "thinking"} and isinstance(obj.get("text"), str): + return [(ev.message if kind == "text" else ev.reasoning)(identity, obj["text"])] + if kind == "tool_call": + return [ + ev.tool_start( + str(obj.get("callId") or identity), + "other", + str(obj.get("tool") or "tool"), + arguments=obj.get("input"), + ) + ] + if kind == "tool_result": + return [ + ev.tool_end( + str(obj.get("callId") or identity), + ok=obj.get("status") == "completed", + output=str(obj.get("result") or ""), + ) + ] + if kind == "status" and obj.get("phase") == "step_end": + usage = obj.get("usage") + if isinstance(usage, dict): + return [ + ev.usage( + input_tokens=int(usage.get("inputTokens") or 0), + output_tokens=int(usage.get("outputTokens") or 0), + cached_tokens=int(usage.get("cacheReadTokens") or 0), + reasoning_tokens=int(usage.get("reasoningTokens") or 0), + ) + ] + if kind == "final": + self.final = True + reason = obj.get("reason") + ok = isinstance(reason, dict) and reason.get("kind") == "completed" + return [ + ev.result( + ok, + str(obj.get("text") or ""), + reason.get("kind") if isinstance(reason, dict) else "missing_reason", + ) + ] + if kind == "error": + return [ + ev.error( + "native_error", str(obj.get("message") or "DeepSeek Harness failed"), fatal=True + ) + ] + return [] + + def finish(self, returncode: int | None) -> list[ParsedEvent]: + """A stream without final cannot represent a completed native turn.""" + return [] if self.final else [ev.result(False, "DeepSeek Harness ended without final")] + + +class DeepSeekHarnessAdapter(AgentAdapter): + """Invoke the official dsh package and preserve its home for exact native resume.""" + + name: ClassVar[str] = "deepseek-harness" + aliases: ClassVar[tuple[str, ...]] = ("deepseekharness", "dsh") + binary: ClassVar[str] = "dsh" + install_steps: ClassVar[tuple[tuple[str, ...], ...]] = ( + ("npm", "install", "-g", "@deepseek-ai/dsh@0.2.2-rc.1"), + ) + capabilities: ClassVar[AdapterCapabilities] = AdapterCapabilities( + resume=True, + mcp=False, + base_url=True, + system_prompt="preamble", + experimental=True, + ) + passthrough_env: ClassVar[tuple[str, ...]] = ( + "DEEPSEEK_API_KEY", + "DEEPSEEK_BASE_URL", + "DEEPSEEK_MODEL", + ) + credential_env_names: ClassVar[tuple[str, ...]] = ("DEEPSEEK_API_KEY",) + + def validate(self, spec: AgentSpec) -> list[str]: + """Reject unsupported external MCP mapping instead of silently dropping it.""" + return ( + ["deepseek-harness managed MCP configuration is not supported"] + if spec.mcp_servers + else [] + ) + + def new_parser(self, ctx: TurnContext) -> EventParser: + """Return a fresh committed-step parser.""" + return DeepSeekHarnessParser() + + def build_invocation(self, ctx: TurnContext) -> Invocation: + """Select a model through the native profile overlay; secrets remain in env.""" + spec = ctx.spec + patch = [ + { + "id": "agent-default-model", + "config": { + "provider": "deepseek-official", + "model": spec.model or "deepseek-flash", + }, + } + ] + path = os.path.join(ctx.turn_dir, "dsh.patch.yml") + modes = { + "read_only": "read-only", + "workspace_write": "workspace-write", + "full_access": "danger-full-access", + } + argv = [ + "dsh", + "--profile", + "headless", + "--patch", + path, + "--json", + "--permission-mode", + modes[spec.permissions], + "--approval-policy", + "never", + ] + if ctx.native_session_id: + argv += ["--session-id", ctx.native_session_id] + argv += list(spec.extra_args) + ["-"] + env = { + "DSH_HOME": os.path.join(ctx.workdir, ".agent-sandbox", "dsh"), + "DSH_TELEMETRY_DISABLED": "1", + } + if spec.provider.api_key: + env["DEEPSEEK_API_KEY"] = spec.provider.api_key + if spec.provider.base_url: + env["DEEPSEEK_BASE_URL"] = spec.provider.base_url + return Invocation( + argv=argv, + env=env, + stdin=self.prompt_stdin(ctx), + files=[InvocationFile(path, json.dumps(patch).encode())], + ) diff --git a/server-sdk/src/agent_sandbox/server/agents/adapters/opencode.py b/server-sdk/src/agent_sandbox/server/agents/adapters/opencode.py new file mode 100644 index 00000000..156d2060 --- /dev/null +++ b/server-sdk/src/agent_sandbox/server/agents/adapters/opencode.py @@ -0,0 +1,183 @@ +"""OpenCode 1.19.x JSON event adapter with explicit OpenAI-compatible provider config.""" + +from __future__ import annotations + +import json +from typing import TYPE_CHECKING, ClassVar + +from .. import events as ev +from .base import AdapterCapabilities, AgentAdapter, EventParser, Invocation, TurnContext + +if TYPE_CHECKING: + from ..config import AgentSpec + from ..events import ParsedEvent + +__all__ = ["OpenCodeAdapter", "OpenCodeParser"] + + +class OpenCodeParser(EventParser): + """Consume native run JSON records; model errors never become successful turns.""" + + def __init__(self) -> None: + self.session_id: str | None = None + self.terminal = False + + def feed(self, line: str) -> list[ParsedEvent]: + """Map complete native text/tool/step records without inventing token deltas.""" + try: + obj = json.loads(line) + except (ValueError, TypeError): + return [ev.log(line)] + if not isinstance(obj, dict): + return [] + out = [] + sid = obj.get("sessionID") + if isinstance(sid, str) and sid != self.session_id: + self.session_id = sid + out.append(ev.session_event(sid)) + kind = obj.get("type") + part = obj.get("part") or {} + if not isinstance(part, dict): + part = {} + identity = str(part.get("id") or "native") + if kind in {"text", "reasoning"} and isinstance(part.get("text"), str): + out.append((ev.message if kind == "text" else ev.reasoning)(identity, part["text"])) + elif kind == "tool_use": + state = part.get("state") or {} + if isinstance(state, dict): + name = str(part.get("tool") or "tool") + if state.get("status") in {"completed", "error"}: + arguments = state.get("input") + command = arguments.get("command") if isinstance(arguments, dict) else None + timing = state.get("time") + duration = None + if isinstance(timing, dict) and all( + isinstance(timing.get(k), (int, float)) for k in ("start", "end") + ): + duration = max(0, int(timing["end"] - timing["start"])) + out.append( + ev.ParsedEvent( + "tool_complete", + identity, + str(state.get("output") or ""), + { + "kind": "command" if name == "bash" else "other", + "name": name, + "arguments": arguments, + "command": command, + "ok": state.get("status") == "completed", + "error": str(state.get("error") or "") or None, + "duration_ms": duration, + }, + ) + ) + elif kind == "step_finish": + tokens = part.get("tokens") or {} + if isinstance(tokens, dict): + out.append( + ev.usage( + input_tokens=int(tokens.get("input") or 0), + output_tokens=int(tokens.get("output") or 0), + ) + ) + if part.get("reason") in {"stop", "end_turn", "length"}: + self.terminal = True + out.append(ev.result(part.get("reason") != "length", stop_reason=part["reason"])) + elif kind == "error": + self.terminal = True + error = obj.get("error") or {} + if not isinstance(error, dict): + error = {"name": str(error)} + data = error.get("data") or {} + if not isinstance(data, dict): + data = {} + message = str(data.get("message") or error.get("name") or "OpenCode failed") + out += [ev.error("native_error", message, fatal=True), ev.result(False, message)] + return out + + def finish(self, returncode: int | None) -> list[ParsedEvent]: + """Require a native terminal step even when the process exits zero.""" + if not self.terminal: + return [ev.result(False, "OpenCode ended without a terminal step")] + return [] + + +class OpenCodeAdapter(AgentAdapter): + """Run an isolated OpenCode headless invocation using native session persistence.""" + + name: ClassVar[str] = "opencode" + aliases: ClassVar[tuple[str, ...]] = ("open-code",) + binary: ClassVar[str] = "opencode" + install_steps: ClassVar[tuple[tuple[str, ...], ...]] = ( + ("npm", "install", "-g", "opencode-ai@1.19.5"), + ) + capabilities: ClassVar[AdapterCapabilities] = AdapterCapabilities( + resume=True, + mcp=False, + base_url=True, + system_prompt="preamble", + experimental=True, + tool_events="completed_only", + ) + passthrough_env: ClassVar[tuple[str, ...]] = ( + "OPENAI_API_KEY", + "OPENAI_BASE_URL", + "OPENAI_MODEL", + ) + credential_env_names: ClassVar[tuple[str, ...]] = ("OPENAI_API_KEY",) + + def validate(self, spec: AgentSpec) -> list[str]: + """Keep custom provider and unsupported MCP behavior explicit.""" + problems = [] + if spec.permissions == "workspace_write": + problems.append( + "opencode adapter does not support workspace_write; choose read_only or full_access" + ) + if spec.mcp_servers: + problems.append("opencode managed MCP configuration is not supported") + return problems + + def new_parser(self, ctx: TurnContext) -> EventParser: + """Return a fresh parser for each native turn.""" + return OpenCodeParser() + + def build_invocation(self, ctx: TurnContext) -> Invocation: + """Configure the native provider through its environment-referenced JSON config.""" + spec = ctx.spec + if spec.permissions == "workspace_write": + raise ValueError("opencode adapter does not support workspace_write") + model = spec.model or "default" + config = { + "$schema": "https://opencode.ai/config.json", + "model": "abx/" + model, + "provider": { + "abx": { + "npm": "@ai-sdk/openai-compatible", + "name": "Configured model", + "options": { + "baseURL": "{env:OPENAI_BASE_URL}", + "apiKey": "{env:OPENAI_API_KEY}", + }, + "models": {model: {"name": model}}, + } + }, + "permission": "allow", + } + if spec.permissions == "read_only": + config["permission"] = { + "*": "deny", + "read": "allow", + "glob": "allow", + "grep": "allow", + "list": "allow", + } + argv = ["opencode", "run", "--format", "json", "--model", "abx/" + model] + if ctx.native_session_id: + argv += ["--session", ctx.native_session_id] + argv += list(spec.extra_args) + env = {"OPENCODE_CONFIG_CONTENT": json.dumps(config), "OPENCODE_DISABLE_AUTOUPDATE": "true"} + if spec.provider.api_key: + env["OPENAI_API_KEY"] = spec.provider.api_key + if spec.provider.base_url: + env["OPENAI_BASE_URL"] = spec.provider.base_url + return Invocation(argv=argv, env=env, stdin=self.prompt_stdin(ctx)) diff --git a/server-sdk/src/agent_sandbox/server/agents/adapters/qoder.py b/server-sdk/src/agent_sandbox/server/agents/adapters/qoder.py new file mode 100644 index 00000000..12bc1408 --- /dev/null +++ b/server-sdk/src/agent_sandbox/server/agents/adapters/qoder.py @@ -0,0 +1,94 @@ +"""Qoder native headless adapter; PAT authentication is separate from model API keys.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, ClassVar + +from .. import events as ev +from .base import AdapterCapabilities, AgentAdapter, EventParser, Invocation, TurnContext +from .stream_json import StreamJsonParser + +if TYPE_CHECKING: + from ..config import AgentSpec + from ..events import ParsedEvent + +__all__ = ["QoderAdapter", "QoderParser"] + + +class QoderParser(StreamJsonParser): + """Use Qoder's native message envelope and require its terminal result.""" + + def __init__(self) -> None: + super().__init__() + self.terminal = False + + def feed(self, line: str) -> list[ParsedEvent]: + """Preserve native parser results and remember terminal delivery.""" + events = super().feed(line) + self.terminal = self.terminal or any(event.kind == "result" for event in events) + return events + + def finish(self, returncode: int | None) -> list[ParsedEvent]: + """Do not infer success from an empty successful process exit.""" + return [] if self.terminal else [ev.result(False, "Qoder ended without result")] + + +class QoderAdapter(AgentAdapter): + """Run Qoder's structured one-shot command and restore its native session.""" + + name: ClassVar[str] = "qoder" + aliases: ClassVar[tuple[str, ...]] = ("qodercli",) + binary: ClassVar[str] = "qoder" + install_steps: ClassVar[tuple[tuple[str, ...], ...]] = ( + ("npm", "install", "-g", "@qoder-ai/qodercli@1.1.90"), + ) + capabilities: ClassVar[AdapterCapabilities] = AdapterCapabilities( + resume=True, + mcp=False, + base_url=False, + system_prompt="flag", + max_turns=False, + experimental=True, + ) + prompt_transport: ClassVar[str] = "argv" + passthrough_env: ClassVar[tuple[str, ...]] = ("QODER_PERSONAL_ACCESS_TOKEN",) + credential_env_names: ClassVar[tuple[str, ...]] = ("QODER_PERSONAL_ACCESS_TOKEN",) + + def validate(self, spec: AgentSpec) -> list[str]: + """Reject unimplemented BYOK/MCP configuration instead of ignoring it.""" + problems = [] + if spec.provider.base_url: + problems.append("qoder uses native PAT authentication, not provider.base_url") + if spec.limits.max_turns: + problems.append("qoder 1.1.90 does not expose a max-turns flag") + if spec.mcp_servers: + problems.append("qoder managed MCP configuration is not supported") + return problems + + def new_parser(self, ctx: TurnContext) -> EventParser: + """Read Qoder's stream-json message envelope.""" + return QoderParser() + + def build_invocation(self, ctx: TurnContext) -> Invocation: + """Keep the PAT in the child environment and use exact session continuation.""" + spec = ctx.spec + argv = ["qoder", "--print", "--output-format", "stream-json"] + if ctx.native_session_id: + argv += ["--resume", ctx.native_session_id] + if spec.model: + argv += ["--model", spec.model] + modes = { + "read_only": "dont_ask", + "workspace_write": "accept_edits", + "full_access": "bypass_permissions", + } + argv += ["--permission-mode", modes[spec.permissions]] + if spec.instructions: + argv += ["--append-system-prompt", spec.instructions] + if spec.permissions == "read_only": + argv += ["--tools", "Read,Glob,Grep", "--strict-mcp-config"] + argv += list(spec.extra_args) + [self.prompt_argv_value(ctx)] + env = ( + {"QODER_PERSONAL_ACCESS_TOKEN": spec.provider.api_key} if spec.provider.api_key else {} + ) + return Invocation(argv=argv, env=env) diff --git a/server-sdk/src/agent_sandbox/server/agents/events.py b/server-sdk/src/agent_sandbox/server/agents/events.py index 72ebf15a..daf0a4f9 100644 --- a/server-sdk/src/agent_sandbox/server/agents/events.py +++ b/server-sdk/src/agent_sandbox/server/agents/events.py @@ -29,7 +29,7 @@ class ParsedEvent: ``kind`` is one of ``session``, ``text_delta``, ``message``, ``reasoning_delta``, ``reasoning``, ``tool_start``, ``tool_output``, - ``tool_end``, ``usage``, ``error``, ``result``, ``log``, ``subagent``. + ``tool_end``, ``tool_complete``, ``usage``, ``error``, ``result``, ``log``, ``subagent``. """ kind: str diff --git a/server-sdk/src/agent_sandbox/server/agents/runtime.py b/server-sdk/src/agent_sandbox/server/agents/runtime.py index 307a912e..0d563588 100644 --- a/server-sdk/src/agent_sandbox/server/agents/runtime.py +++ b/server-sdk/src/agent_sandbox/server/agents/runtime.py @@ -365,13 +365,16 @@ def _field(item: Item) -> tuple[str, str]: return "text", "reasoning" return "output", "output" - def _new_item(self, type_: str, native_id: str | None, **data: Any) -> Item: + def _new_item( + self, type_: str, native_id: str | None, *, _status: str = "in_progress", **data: Any + ) -> Item: self._flush_pending_message("commentary") item = Item( id="item_" + uuid.uuid4().hex[:24], type=type_, turn_id=self.turn.id, output_index=len(self.turn.items), + status=_status, data=data, ) self.turn.items.append(item) @@ -469,6 +472,8 @@ def handle(self, pe: ParsedEvent) -> None: self._push(native, pe.text) elif kind == "tool_end": self._tool_end(pe) + elif kind == "tool_complete": + self._tool_complete(pe) elif kind == "subagent": self._subagent(pe) elif kind == "usage": @@ -521,6 +526,42 @@ def _tool_start(self, pe: ParsedEvent) -> None: if paths: self._file_items[item.id] = paths + def _tool_complete(self, pe: ParsedEvent) -> None: + """Record a completion-only observation without fabricating a live tool start.""" + data = pe.data + kind = str(data.get("kind") or "other") + ok = bool(data.get("ok")) + fields = { + "kind": kind, + "arguments": self.redactor.redact_obj(data.get("arguments")), + "output": self.redactor.redact(pe.text or "")[:_MAX_TOOL_OUTPUT], + "observation": "completed_only", + } + if kind == "command": + fields.update( + command=self.redactor.redact(str(data.get("command") or "")), + cwd=self.turn_cwd, + exit_code=data.get("exit_code"), + duration_ms=data.get("duration_ms"), + ) + else: + fields.update( + server_label=self.runtime_name, + name=str(data.get("name") or "tool"), + error=self.redactor.redact(str(data.get("error") or "")) or None, + ) + item = self._new_item( + "command_execution" if kind == "command" else "mcp_call", + pe.item_id, + _status="completed" if ok else "failed", + **fields, + ) + if ok: + self.reported_paths.extend( + _reported_paths(kind, str(data.get("name") or ""), data.get("arguments")) + ) + self.session.emit("item.done", self.turn.id, item=item.to_dict()) + def _subagent(self, pe: ParsedEvent) -> None: """Record a subagent id (and its own stream entries) the CLI emitted.""" op = pe.data.get("op") diff --git a/server-sdk/src/agent_sandbox/server/managed.py b/server-sdk/src/agent_sandbox/server/managed.py index 42e1edd0..529b0b1e 100644 --- a/server-sdk/src/agent_sandbox/server/managed.py +++ b/server-sdk/src/agent_sandbox/server/managed.py @@ -26,6 +26,7 @@ from typing import Any from urllib.parse import parse_qs, urlsplit +from .agents.adapters import default_adapters from .agents.config import AgentSpec, LimitsSpec, ProviderSpec, WorkspaceSpec from .agents.runtime import AgentRuntime from .agents.wire_sessions import SessionsEventMapper, item_object, turn_object @@ -33,6 +34,15 @@ PROTOCOL = "agent-sandbox-managed-bridge/v1" _TERMINAL = frozenset({"completed", "failed", "cancelled", "uncertain"}) +# Standalone server cannot depend on the client distribution. Parity is checked in tests. +MANAGED_HARNESS_ENV = { + "codex": ("OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"), + "qwen-code": ("OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"), + "claude-code": ("ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL"), + "qoder": ("QODER_PERSONAL_ACCESS_TOKEN",), + "opencode": ("OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"), + "deepseek-harness": ("DEEPSEEK_API_KEY", "DEEPSEEK_BASE_URL", "DEEPSEEK_MODEL"), +} class BridgeError(Exception): @@ -108,8 +118,9 @@ def create_session(self, body: dict[str, Any]) -> dict[str, Any]: if not isinstance(agent, dict) or set(agent) - {"adapter", "model", "instructions"}: raise BridgeError(400, "invalid_agent") adapter = agent.get("adapter") - if adapter not in {"codex", "qwen-code"}: + if adapter not in MANAGED_HARNESS_ENV: raise BridgeError(400, "unsupported_adapter") + names = MANAGED_HARNESS_ENV[adapter] spec = AgentSpec( name="managed", runtime=adapter, @@ -117,9 +128,9 @@ def create_session(self, body: dict[str, Any]) -> dict[str, Any]: instructions=agent.get("instructions"), workspace=WorkspaceSpec(path=self.workspace), provider=ProviderSpec( - base_url=os.getenv("OPENAI_BASE_URL"), - api_key=os.getenv("OPENAI_API_KEY"), - wire_api="responses" if adapter == "codex" else "chat_completions", + base_url=os.getenv(names[1]) if len(names) > 1 else None, + api_key=os.getenv(names[0]), + wire_api="responses" if adapter == "codex" else "chat", ), permissions="full_access", limits=LimitsSpec(max_output_bytes=self.max_output_bytes), @@ -305,7 +316,7 @@ def _watch_tools(self, rid: str, seconds: float) -> None: item = event.data.get("item", {}) if item.get("type") not in {"command_execution", "mcp_call"}: continue - if event.type == "item.added": + if event.type == "item.added" and item.get("status") == "in_progress": active[item["id"]] = time.monotonic() elif event.type == "item.done": active.pop(item["id"], None) @@ -570,8 +581,9 @@ def _handle(self, method: str) -> None: if method == "GET" and url.path == "/capabilities": adapters = [ name - for name, binary in (("codex", "codex"), ("qwen-code", "qwen")) - if shutil.which(binary, path=bridge.runtime._environ.get("PATH")) + for name in MANAGED_HARNESS_ENV + if (adapter := default_adapters().get(name)) is not None + and shutil.which(adapter.binary, path=bridge.runtime._environ.get("PATH")) ] self._send( 200, diff --git a/server-sdk/tests/fixtures/native-harnesses/README.md b/server-sdk/tests/fixtures/native-harnesses/README.md new file mode 100644 index 00000000..26d67df1 --- /dev/null +++ b/server-sdk/tests/fixtures/native-harnesses/README.md @@ -0,0 +1,6 @@ +# Native CLI captures + +Captured from installed OpenCode 1.19.5 and official DeepSeek Harness 0.2.2-rc.1 +using Node 24.16.0 and a deterministic loopback model fixture on 2026-11-17. +Paths, native IDs and timestamps were normalized; message/tool/outcome envelopes +were retained. These are real CLI transport captures, not real-model acceptance. diff --git a/server-sdk/tests/fixtures/native-harnesses/deepseek-harness.jsonl b/server-sdk/tests/fixtures/native-harnesses/deepseek-harness.jsonl new file mode 100644 index 00000000..91cd0d90 --- /dev/null +++ b/server-sdk/tests/fixtures/native-harnesses/deepseek-harness.jsonl @@ -0,0 +1,7 @@ +{"type":"session","sessionId":"session-captured","cwd":"/workspace"} +{"type":"status","phase":"turn_start","turn":1} +{"type":"status","phase":"step_start","turn":1,"step":1} +{"type":"text","text":"Native probe answer"} +{"type":"status","phase":"step_end","turn":1,"step":1,"usage":{"inputTokens":5,"outputTokens":3,"totalTokens":8}} +{"type":"status","phase":"turn_end","turn":1,"reason":{"kind":"completed"}} +{"type":"final","sessionId":"session-captured","reason":{"kind":"completed"},"text":"Native probe answer"} diff --git a/server-sdk/tests/fixtures/native-harnesses/opencode.jsonl b/server-sdk/tests/fixtures/native-harnesses/opencode.jsonl new file mode 100644 index 00000000..097e8b3a --- /dev/null +++ b/server-sdk/tests/fixtures/native-harnesses/opencode.jsonl @@ -0,0 +1,3 @@ +{"type":"step_start","timestamp":0,"sessionID":"ses_captured0","part":{"id":"prt_captured0","messageID":"msg_captured0","sessionID":"ses_captured0","type":"step-start"}} +{"type":"text","timestamp":0,"sessionID":"ses_captured0","part":{"id":"prt_captured1","messageID":"msg_captured0","sessionID":"ses_captured0","type":"text","text":"Native probe answer","time":{"start":0,"end":0}}} +{"type":"step_finish","timestamp":0,"sessionID":"ses_captured0","part":{"id":"prt_captured2","reason":"stop","messageID":"msg_captured0","sessionID":"ses_captured0","type":"step-finish","tokens":{"input":0,"output":0,"reasoning":0,"cache":{"write":0,"read":0}},"cost":0}} diff --git a/server-sdk/tests/test_server/test_harness_adapters.py b/server-sdk/tests/test_server/test_harness_adapters.py new file mode 100644 index 00000000..09dd8a50 --- /dev/null +++ b/server-sdk/tests/test_server/test_harness_adapters.py @@ -0,0 +1,242 @@ +"""Native harness records and command construction; no model/backend acceptance claim.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import pytest + +from agent_sandbox.server.agents.adapters import AdapterRegistry, TurnContext +from agent_sandbox.server.agents.adapters.deepseek_harness import DeepSeekHarnessParser +from agent_sandbox.server.agents.adapters.opencode import OpenCodeParser +from agent_sandbox.server.agents.adapters.qoder import QoderParser +from agent_sandbox.server.agents.config import AgentSpec, ProviderSpec + + +def context(runtime: str, tmp_path, *, resume: str | None = None) -> TurnContext: + return TurnContext( + spec=AgentSpec( + name="test", + runtime=runtime, + model="test-model", + provider=ProviderSpec( + api_key="placeholder-model-secret", + base_url=None if runtime == "qoder" else "https://model.example/v1", + ), + permissions="full_access", + ), + prompt="Inspect this project", + workdir=str(tmp_path), + turn_dir=str(tmp_path), + native_session_id=resume, + ) + + +@pytest.mark.parametrize( + "name,alias,binary", + [ + ("qoder", "qodercli", "qoder"), + ("opencode", "open-code", "opencode"), + ("deepseek-harness", "dsh", "dsh"), + ], +) +def test_native_registry_and_invocation(name, alias, binary, tmp_path): + registry = AdapterRegistry() + adapter = registry.get(alias) + assert adapter is not None and adapter.name == name + ctx = context(name, tmp_path, resume="native-session") + assert adapter.validate(ctx.spec) == [] + invocation = adapter.build_invocation(ctx) + assert invocation.argv[0] == binary + assert "native-session" in invocation.argv + assert "placeholder-model-secret" not in " ".join(invocation.argv) + assert "placeholder-model-secret" in invocation.env.values() + assert all(b"placeholder-model-secret" not in f.content for f in invocation.files) + assert not adapter.capabilities.partial_deltas + + +def test_qoder_has_native_pat_and_no_fake_endpoint(tmp_path): + adapter = AdapterRegistry().get("qoder") + assert adapter is not None + ctx = context("qoder", tmp_path) + invocation = adapter.build_invocation(ctx) + assert invocation.env == {"QODER_PERSONAL_ACCESS_TOKEN": "placeholder-model-secret"} + assert "OPENAI_API_KEY" not in invocation.env + ctx.spec.provider.base_url = "https://model.example/v1" + assert adapter.validate(ctx.spec) + + +def test_dsh_preserves_native_home_across_turns(tmp_path): + adapter = AdapterRegistry().get("deepseek-harness") + assert adapter is not None + first = adapter.build_invocation(context("deepseek-harness", tmp_path)) + second = adapter.build_invocation(context("deepseek-harness", tmp_path, resume="session-exact")) + assert first.env["DSH_HOME"] == second.env["DSH_HOME"] + assert "--session-id" not in first.argv + assert second.argv[second.argv.index("--session-id") + 1] == "session-exact" + assert json.loads(first.files[0].content)[0]["config"]["model"] == "test-model" + + +def test_dsh_committed_events_and_final_reason(): + parser = DeepSeekHarnessParser() + records = [ + {"type": "session", "sessionId": "session-exact"}, + {"type": "text", "text": "Committed answer"}, + {"type": "tool_call", "callId": "call-one", "tool": "run_shell", "input": {"cmd": "true"}}, + {"type": "tool_result", "callId": "call-one", "status": "completed", "result": "ok"}, + { + "type": "final", + "sessionId": "session-exact", + "reason": {"kind": "completed"}, + "text": "Committed answer", + }, + ] + events = [event for record in records for event in parser.feed(json.dumps(record))] + assert [e.kind for e in events] == ["session", "message", "tool_start", "tool_end", "result"] + assert events[-1].data["ok"] is True + assert parser.finish(0) == [] + + +@pytest.mark.parametrize("reason", [None, {"kind": "aborted"}, {"kind": "error"}]) +def test_dsh_final_without_completed_reason_fails(reason): + events = DeepSeekHarnessParser().feed(json.dumps({"type": "final", "reason": reason})) + assert events[-1].data["ok"] is False + + +@pytest.mark.parametrize("parser", [DeepSeekHarnessParser, OpenCodeParser, QoderParser]) +def test_zero_exit_without_native_terminal_is_not_success(parser): + assert parser().finish(0)[-1].data["ok"] is False + + +def test_opencode_native_session_text_tool_and_terminal(): + parser = OpenCodeParser() + records = [ + {"type": "step_start", "sessionID": "ses-exact", "part": {"id": "start"}}, + { + "type": "tool_use", + "sessionID": "ses-exact", + "part": { + "id": "tool-one", + "tool": "bash", + "state": {"status": "completed", "input": {"command": "true"}, "output": "ok"}, + }, + }, + {"type": "text", "sessionID": "ses-exact", "part": {"id": "text-one", "text": "Done"}}, + { + "type": "step_finish", + "sessionID": "ses-exact", + "part": {"id": "end", "reason": "stop", "tokens": {"input": 3, "output": 2}}, + }, + ] + events = [event for record in records for event in parser.feed(json.dumps(record))] + assert [e.kind for e in events] == [ + "session", + "tool_complete", + "message", + "usage", + "result", + ] + assert events[-1].data["ok"] is True + assert parser.finish(0) == [] + + +def test_opencode_tool_call_step_is_not_terminal(): + parser = OpenCodeParser() + parser.feed(json.dumps({"type": "step_finish", "part": {"reason": "tool-calls"}})) + assert parser.finish(0)[-1].data["ok"] is False + + +def test_opencode_native_error_fails(): + parser = OpenCodeParser() + events = parser.feed( + json.dumps({"type": "error", "error": {"name": "APIError", "data": {"message": "Denied"}}}) + ) + assert events[0].data["fatal"] is True + assert events[-1].data["ok"] is False + + +def test_opencode_config_uses_env_references(tmp_path): + adapter = AdapterRegistry().get("opencode") + assert adapter is not None + invocation = adapter.build_invocation(context("opencode", tmp_path)) + config = json.loads(invocation.env["OPENCODE_CONFIG_CONTENT"]) + assert config["provider"]["abx"]["options"]["apiKey"] == "{env:OPENAI_API_KEY}" + assert "placeholder-model-secret" not in invocation.env["OPENCODE_CONFIG_CONTENT"] + assert invocation.stdin == b"Inspect this project" + + +def test_opencode_never_silently_widens_workspace_write(tmp_path): + adapter = AdapterRegistry().get("opencode") + assert adapter is not None + ctx = context("opencode", tmp_path) + ctx.spec.permissions = "workspace_write" + assert adapter.validate(ctx.spec) + with pytest.raises(ValueError, match="workspace_write"): + adapter.build_invocation(ctx) + + +@pytest.mark.parametrize("name", ["opencode", "deepseek-harness"]) +def test_installed_native_cli_captures(name, tmp_path): + adapter = AdapterRegistry().get(name) + assert adapter is not None + parser = adapter.new_parser(context(name, tmp_path)) + capture = Path(__file__).parents[1] / "fixtures" / "native-harnesses" / (name + ".jsonl") + events = [event for line in capture.read_text().splitlines() for event in parser.feed(line)] + assert any(event.kind == "session" for event in events) + assert any(event.kind == "message" and event.text == "Native probe answer" for event in events) + assert events[-1].kind == "result" and events[-1].data["ok"] is True + assert parser.finish(0) == [] + + +def test_qoder_stream_terminal_and_error_mapping(): + parser = QoderParser() + # The installed Qoder 1.1.90 bundle defines this exact native result envelope. + events = parser.feed( + json.dumps( + { + "type": "result", + "subtype": "error_during_execution", + "is_error": True, + "result": "Denied", + "session_id": "native-session", + "uuid": "fixture", + } + ) + ) + assert events[-1].kind == "result" and events[-1].data["ok"] is False + assert parser.finish(1) == [] + + +def test_completed_only_tool_never_publishes_a_running_item(): + from agent_sandbox.server.agents.redact import Redactor + from agent_sandbox.server.agents.runtime import Session, Turn, _TurnBuilder + + session = Session("session", "test", 0) + turn = Turn("turn", "session", "test", "probe") + builder = _TurnBuilder(session, turn, Redactor(), "opencode") + events = OpenCodeParser().feed( + json.dumps( + { + "type": "tool_use", + "part": { + "id": "tool", + "tool": "bash", + "state": { + "status": "completed", + "input": {"command": "true"}, + "output": "done", + "time": {"start": 1000, "end": 1250}, + }, + }, + } + ) + ) + assert len(events) == 1 and events[0].kind == "tool_complete" + builder.handle(events[0]) + emitted = session.events_after(0) + assert [event.type for event in emitted] == ["item.added", "item.done"] + assert all(event.data["item"]["status"] == "completed" for event in emitted) + assert turn.items[0].data["duration_ms"] == 250 + assert turn.items[0].data["observation"] == "completed_only" + assert builder._started_at == {} diff --git a/server-sdk/tests/test_server/test_routes_agents.py b/server-sdk/tests/test_server/test_routes_agents.py index ae5ee4dc..7d139aea 100644 --- a/server-sdk/tests/test_server/test_routes_agents.py +++ b/server-sdk/tests/test_server/test_routes_agents.py @@ -284,6 +284,9 @@ def test_aliases_unknown_adapter_and_default(self, workspace: str, tmp_path: Pat "claude-code", "command", "cursor", + "deepseek-harness", + "opencode", + "qoder", ] assert [item["implemented"] for item in runtimes["data"]] == [ True, @@ -291,8 +294,11 @@ def test_aliases_unknown_adapter_and_default(self, workspace: str, tmp_path: Pat False, False, False, + False, + False, + False, ] - assert [item["default"] for item in runtimes["data"]] == [True] + [False] * 4 + assert [item["default"] for item in runtimes["data"]] == [True] + [False] * 7 status, body, headers = _request( port, @@ -329,7 +335,7 @@ def test_aliases_unknown_adapter_and_default(self, workspace: str, tmp_path: Pat reset_agent_runtime() status, runtimes, _ = _request(port, "GET", "/v1/agents/runtimes?limit=100&order=asc") assert status == 200 - assert [item["default"] for item in runtimes["data"]] == [False, True] + [False] * 3 + assert [item["default"] for item in runtimes["data"]] == [False, True] + [False] * 6 status, created, _ = _request( port, "POST", @@ -450,6 +456,9 @@ def test_event_stream_and_runtimes(self, workspace: str) -> None: status, runtimes, _ = _request(port, "GET", "/v1/agents/runtimes?limit=100") assert status == 200 assert [item["name"] for item in runtimes["data"]] == [ + "qoder", + "opencode", + "deepseek-harness", "cursor", "command", "claude-code", diff --git a/server-sdk/tests/test_server/test_routes_agents_local.py b/server-sdk/tests/test_server/test_routes_agents_local.py index 9ad46993..3aa3bfd5 100644 --- a/server-sdk/tests/test_server/test_routes_agents_local.py +++ b/server-sdk/tests/test_server/test_routes_agents_local.py @@ -331,8 +331,8 @@ def test_other_adapters_stay_404(self, ws: Path) -> None: assert ids == ["codex", "qwen-code"] runtimes = ok(call("GET", "/v1/agents/runtimes?limit=100&order=asc"))["data"] assert [r["name"] for r in runtimes][:2] == ["codex", "qwen-code"] - assert [r["implemented"] for r in runtimes] == [True, True, False, False, False] - assert [r["default"] for r in runtimes] == [True, False, False, False, False] + assert [r["implemented"] for r in runtimes] == [True, True] + [False] * 6 + assert [r["default"] for r in runtimes] == [True] + [False] * 7 def test_group_disabled_hides_every_new_route(self) -> None: table = default_table() @@ -2814,7 +2814,16 @@ def test_runtimes_report_implemented_and_installed_for_every_declared_runtime( world, "agents_runtimes_list", "GET", "/v1/agents/runtimes?limit=100&order=asc" )["data"] by_name = {r["name"]: r for r in data} - assert list(by_name) == ["codex", "qwen-code", "claude-code", "command", "cursor"] + assert list(by_name) == [ + "codex", + "qwen-code", + "claude-code", + "command", + "cursor", + "deepseek-harness", + "opencode", + "qoder", + ] assert {n for n, r in by_name.items() if r["implemented"]} == {"codex", "qwen-code"} for runtime in data: assert isinstance(runtime["implemented"], bool)