|
| 1 | +# A3S Code 2.0 Refactor Completion Report |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +The 2.0 refactor is functionally complete. |
| 6 | + |
| 7 | +The codebase now follows the intended harness-driven shape: |
| 8 | + |
| 9 | +```text |
| 10 | +Agent / AgentSession |
| 11 | + -> context assembly |
| 12 | + -> tool selection |
| 13 | + -> permission and confirmation policy |
| 14 | + -> execution |
| 15 | + -> trace, artifacts, verification evidence |
| 16 | + -> compaction |
| 17 | +``` |
| 18 | + |
| 19 | +Routine multi-agent work has one default path: `task` and `parallel_task`. |
| 20 | +Advanced `Orchestrator` APIs remain available only for explicit SubAgent |
| 21 | +lifecycle control and event monitoring. |
| 22 | + |
| 23 | +## Removed 1.0 Mechanisms |
| 24 | + |
| 25 | +- Deleted explicit Lead/Worker/Reviewer `AgentTeam` and `TeamRunner` APIs. |
| 26 | +- Removed model-visible `run_team` and SDK `runTeam` shortcuts. |
| 27 | +- Removed the public task/progress/idle lifecycle bindings. |
| 28 | +- Deleted the legacy cron scheduler and `/loop` commands. |
| 29 | +- Removed placeholder SubAgent execution. |
| 30 | +- Removed SubAgent-level permissive permission shortcuts. |
| 31 | +- Removed public `PermissionPolicy::permissive()`. |
| 32 | +- Removed SubAgent/Orchestrator lane-queue coupling. |
| 33 | +- Removed generic queue task submission helpers from public session APIs. |
| 34 | +- Removed `.hcl` config support; `.acl` is the supported config format. |
| 35 | +- Removed unused prompt files, undercover mode, tool search side path, and stale |
| 36 | + historical SDK investigation docs. |
| 37 | + |
| 38 | +## Retained Mechanisms |
| 39 | + |
| 40 | +- `Agent` and `AgentSession` as the public facade. |
| 41 | +- `task` and `parallel_task` as the default delegation tools. |
| 42 | +- `Orchestrator` as an advanced SubAgent lifecycle control plane. |
| 43 | +- Session-level external/hybrid queue dispatch for explicit integrations. |
| 44 | +- AHP 2.3 as a harness extension. |
| 45 | +- Permission policies with explicit default decisions and rule lists. |
| 46 | +- Trace events, artifact references, and verification reports as completion |
| 47 | + evidence. |
| 48 | +- Programmatic Tool Calling for bounded, repeatable tool chains. |
| 49 | + |
| 50 | +## Public Surface |
| 51 | + |
| 52 | +The Rust crate root now exposes the intended 2.0 facade and keeps low-level |
| 53 | +runtime modules internal: |
| 54 | + |
| 55 | +- `Agent` |
| 56 | +- `AgentSession` |
| 57 | +- `AgentEvent` |
| 58 | +- `AgentResult` |
| 59 | +- `SessionOptions` |
| 60 | +- config, LLM, error, and prompt slot types |
| 61 | + |
| 62 | +Node and Python bindings now consume these root exports instead of reaching into |
| 63 | +low-level `agent` / `agent_api` modules. |
| 64 | + |
| 65 | +## Verification |
| 66 | + |
| 67 | +Latest verification pass: |
| 68 | + |
| 69 | +- `cargo test -p a3s-code-core --lib` |
| 70 | + - 1459 passed |
| 71 | + - 0 failed |
| 72 | + - 2 ignored |
| 73 | +- `cargo check -p a3s-code-core --all-targets --features ahp` |
| 74 | +- `cargo check --manifest-path sdk/node/Cargo.toml --all-targets` |
| 75 | +- `cargo check --manifest-path sdk/python/Cargo.toml --all-targets` |
| 76 | +- `cargo test --manifest-path sdk/node/Cargo.toml --lib` |
| 77 | +- `cargo test --manifest-path sdk/python/Cargo.toml --lib` |
| 78 | +- `npx tsc --noEmit` in `sdk/node/examples` |
| 79 | +- `npm --cache /private/tmp/a3s-npm-cache pack --dry-run` in `sdk/node` |
| 80 | +- `npm run build` in `sdk/node` |
| 81 | +- `npm test` in `sdk/node` |
| 82 | +- `npm run test:helpers` in `sdk/node` |
| 83 | +- `npm run basic:minimax` in `sdk/node/examples` |
| 84 | +- `npm run orchestrator:kimi` in `sdk/node/examples` |
| 85 | +- `npm run smoke` in `sdk/node/examples` |
| 86 | +- `npx tsx basic/test_runtime_nesting.ts` in `sdk/node/examples` |
| 87 | +- `python3 -m maturin build --release --out /private/tmp/a3s-code-py-dist` in `sdk/python` |
| 88 | +- wheel import smoke: |
| 89 | + `PYTHONPATH=/private/tmp/a3s-code-py-import python3 -c 'import a3s_code'` |
| 90 | +- `cargo fmt --all --check` |
| 91 | +- `git diff --check` |
| 92 | +- `scripts/check_release_versions.sh` |
| 93 | +- `cargo test -p a3s-code-core --test test_real_config_env_integration` |
| 94 | + - verifies repo `.a3s/config.acl` resolves MiniMax defaults through injected |
| 95 | + `A3S_OPENAI_*` env vars and `MINIMAX_*` aliases without making network calls |
| 96 | +- `scripts/real_config_env_integration.sh --dry-run` |
| 97 | + - runs the no-network ACL env-injection checks directly |
| 98 | +- `scripts/real_config_env_integration.sh` |
| 99 | + - can extract literal OpenAI/MiniMax credentials from `.a3s/config.acl`, |
| 100 | + inject them into `A3S_OPENAI_*` for the test process, and run against a |
| 101 | + temporary env-style config without modifying the source config |
| 102 | +- `scripts/release_preflight.sh` |
| 103 | + - passes all non-network gates |
| 104 | + - skips real-provider smoke unless `A3S_OPENAI_*` / `MINIMAX_*` is injected |
| 105 | + or literal OpenAI/MiniMax credentials are present in the config |
| 106 | + |
| 107 | +## Residual Risks |
| 108 | + |
| 109 | +- Real LLM examples and network-backed browser/search flows still require |
| 110 | + provider credentials in the local environment. |
| 111 | +- Large deleted-example churn should be reviewed once before release so no |
| 112 | + intentionally supported sample was removed accidentally. |
| 113 | +- Node native bindings were rebuilt during final verification so `index.js` and |
| 114 | + `index.d.ts` match the current Rust N-API surface. |
| 115 | +- Real-provider Node examples now skip cleanly when required credentials/config |
| 116 | + are missing, and TypeScript ESM examples no longer rely on CommonJS |
| 117 | + `__dirname`. |
| 118 | +- The examples package has a no-credential smoke script, and its Quick Start no |
| 119 | + longer points users at a live-provider test by default. |
| 120 | + |
| 121 | +## Release Readiness |
| 122 | + |
| 123 | +Before tagging a 2.0 release: |
| 124 | + |
| 125 | +1. Run `REQUIRE_REAL_PROVIDER=1 scripts/release_preflight.sh` with `A3S_OPENAI_API_KEY` / `A3S_OPENAI_BASE_URL` injected, or use the MiniMax aliases `MINIMAX_API_KEY` / `MINIMAX_BASE_URL`. |
| 126 | +2. Review generated TypeScript declarations and Python docs. |
| 127 | +3. Commit the refactor as one architecture-level change or split by phase. |
| 128 | +4. Tag and publish from a clean worktree. |
0 commit comments