Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .agents/README.md
Original file line number Diff line number Diff line change
@@ -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).
Expand All @@ -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).
Expand Down Expand Up @@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading