About this project

# PilotDeck · Subtask Acceptance and Local Repair This is an improved project based on [OpenBMB/PilotDeck](https://github.com/OpenBMB/PilotDeck) (Direction 3 competition entry), aimed at enhancing the delivery quality of AI agent subtasks. It introduces the `agent.acceptance` module, adding structural checks and independent model review mechanisms to the "completed" status of subtasks. ## Core Features - **Verifiable Deliverables**: First, a host rule performs a structural pre-check, followed by an independent read-only model verifying the original task, delivery declaration, and actual file content. - **Bounded Repairs**: When acceptance fails, the system executes local repairs within the same subtask, session, and permission scope, sharing the total round limit; if exhausted, it explicitly refuses while preserving passed sibling tasks. - **Auditable Experience**: Successful and rejected acceptance metadata is written to native white-box memory, grouped by actual model and contract, retaining sample denominators without automatically modifying acceptance criteria. - **Verifiable Process**: Native subtask cards display acceptance and repair statuses, including problem descriptions, repair counts, tool trajectories, and artifacts. ## Installation and Startup Requires Node.js **22.13–22.x** and pnpm **10.32.1**. ```bash corepack enable pnpm install --frozen-lockfile npm run build ``` Standard startup remains `npm run dev`. Enabling **Agent → Delivery Review** in native settings activates the second layer of review, allowing separate model selection and adjustment of review rounds and timeout durations. ### Isolated Demo Environment Supports any OpenAI-compatible tool-calling model. Configure demo parameters via local environment variables: ```bash node --import tsx scripts/verified-subtasks-native.ts ui --semantic-fault --acceptance-memory ``` Alternatively, use credentials from Zhipu Coding Plan: ```bash node --import tsx scripts/verified-subtasks-native.ts ui # Or reuse local OpenCode credentials node --import tsx scripts/verified-subtasks-native.ts ui --opencode-auth ``` ### Direct Acceptance Mode Accept directly within the same native gateway chain without starting the interface: ```bash node --import tsx scripts/verified-subtasks-native.ts live --opencode-auth ``` ### Deterministic Mechanism Verification Benchmark testing without model credentials: ```bash node --import tsx scripts/verified-subtasks-benchmark.ts artifacts/verified-benchmark ``` ## Technical Implementation | Module | Improvement | |---|---| | `src/agent/sub/acceptance/` | Finite schema pre-check, artifact check, problem normalization, host checker registration | | `SubAgentSession` / `AgentLoop` | In-session repair, total round budget, interruption and error propagation, cumulative usage | | `agent` / `ToolRuntime` | Contract passthrough, structured acceptance results, rejection as real tool failure | | Gateway and Native UI Bridge | Host rule loading, review model settings, acceptance and repair status, final judgment preservation | | `AcceptanceMemory.ts` | Terminal state metadata bridge, deduplication, denominator statistics, native feedback entries, compatibility with clearing and Dream file organization | | `modelReviewer.ts` | Independent read-only session, actual evidence reading, model inheritance and override, review results and usage | Activation is explicit: the original behavior is retained when the `acceptance` parameter is absent. Hosts can register business checkers, and models can only reference names. Native startup loads approved JSON product rules via `PILOTDECK_ACCEPTANCE_CONFIG`. ## Acceptance Experience Memory After enabling white-box memory in native settings under **Agent → Memory**, recording can be controlled via **Agent → Delivery Review → Save Acceptance Experience to Project Memory**. The configuration item is `memory.captureAcceptance`; if omitted, it defaults to recording in projects with memory enabled; setting it to `false` disables it. Observers record metadata of the true acceptance terminal state, not saving task body, delivery content, or free-text comments; the most recent 128 deduplicated observations are saved in project SQLite, with native feedback Markdown being a derived summary. Recording itself does not increase model calls, but native retrieval and Dream may still invoke models. ## Evidence and Boundaries This project provides explicit fault injection verification evidence rather than natural error rate statistics. For example, in GLM-5.3 native live runs, 4/4 deliveries passed, 1 model rejection triggered local repair, and the hash and modification times of 3 successful reports remained unchanged. Compared to full batch reruns, the local repair strategy reduced request volume by 40%. **Note**: This system does not provide global rollback, exactly-once external side effects, shared file conflict coordination, or cross-process recovery. Business credibility depends on host rules and review quality; model reviews may still misjudge. File deliveries that cannot be successfully read independently will not be accepted by the reviewer. Key test commands: ```bash node --import tsx --test tests/agent/sub/acceptance/*.spec.ts tests/agent/sub/VerifiedSubagent.spec.ts tests/agent/sub/AcceptanceInvariants.spec.ts tests/agent/sub/ModelReview.spec.ts tests/pilot/config/acceptanceReview.spec.ts tests/tool/VerifiedAgent.spec.ts tests/gateway/VerifiedSubtaskEvents.spec.ts ``` For more details, please refer to [Demo Instructions](docs/verified-subtasks/DEMO.zh-CN.md), [Validation Records](docs/verified-subtasks/VALIDATION.zh-CN.md), and [Technical Details](docs/verified-subtasks/README.zh-CN.md).