zopu-code/docs/SMOKE.md

Zopu Integration Smoke

The smoke harness is a repeatable integration lane for the thin Zopu MVP. It probes the local web app, authenticated Convex control plane, Flue project-manager route, AgentOS daemon/workspace contract, the CPA OpenAI-compatible gateway, and the Orb execution-plane dependencies (Docker, OpenCode, Gitea, repository writability) before it creates any project issue.

The harness does not edit CPA configuration, restart services, print bearer tokens/API keys, or run parallel worker calls. minimax-m3 is the serial worker-loop model; glm-5.2 performs the plan and the independent review.

Preflight checks

Check ID	Layer	What it probes
web	Control plane	Web app HTTP reachability
convex	Control plane	Convex health query returns OK
organization	Control plane	Authenticated personal organization
project-contract	Control plane	Disposable project exists with a connected source
agentos-workspace-contract	Control plane	Issue-scoped artifacts present
agentos-daemon	Control plane	Online local daemon
flue	Agent service	project-manager Flue route reachable
cpa-model-catalog	Model gateway	minimax-m3 and glm-5.2 in catalog
cpa-completion-minimax-m3	Model gateway	minimax-m3 accepts a no-tools completion
cpa-completion-glm-5.2	Model gateway	glm-5.2 accepts a no-tools completion
model-roles	Model gateway	Role selection contract (worker/planner-reviewer)
worker-gateway-config	Model gateway	AGENT_MODEL_BASE_URL matches the CPA base URL
docker-daemon	Orb execution plane	Docker daemon responds to docker version
opencode-package	Orb execution plane	@agentos-software/opencode is resolvable
gitea-reachable	Orb execution plane	Gitea /api/v1/version endpoint reachable
gitea-creds-valid	Orb execution plane	Gitea token authenticates against /api/v1/user
gitea-pr-creation	Orb execution plane	Target repository accessible for PR creation
repository-writable	Orb execution plane	Orb workspace root is writable

A missing or unreachable dependency reports the check as failed with the exact reason. The harness never fakes success.

Setup

Use a disposable/test project that already has a connected repository source and the issue-scoped artifact set. Export a Better Auth/Convex access token for the signed-in user, the local daemon id, and the CPA key/base URL. The CPA URL must include its OpenAI-compatible /v1 path.

export ZOPU_SMOKE_ACCESS_TOKEN='...'
export ZOPU_SMOKE_PROJECT_ID='...'
export ZOPU_SMOKE_DAEMON_ID='local-macbook'
export ZOPU_SMOKE_CPA_BASE_URL='https://ai.example.invalid/v1'
export ZOPU_SMOKE_CPA_API_KEY='...'

For the Orb execution-plane checks (Docker, Gitea PR creation), also export:

export GITEA_URL='https://git.example.com'
export GITEA_TOKEN='...'
export ZOPU_SMOKE_REPOSITORY_PATH='owner/repo'

The harness reuses AGENT_MODEL_*, CONVEX_URL, DAEMON_ID, SITE_URL, and VITE_FLUE_URL when their ZOPU_SMOKE_* equivalents are absent. It never rewrites those values. Override the tiny feature request with ZOPU_SMOKE_FEATURE_REQUEST when the disposable project needs a more specific target.

Commands

Run capability probes only:

bun run smoke:zopu

Drive one issue through the project loop and review it:

bun run smoke:zopu --run --report /tmp/zopu-smoke.json

The command prints one of these stable markers:

• ZOPU_SMOKE_PREFLIGHT_PASSED means all probes passed and no mutation was requested.
• ZOPU_SMOKE_COMPLETED means the issue was created, the worker reported completion, the durable issue reached completed, and GLM approved the result.
• ZOPU_SMOKE_CONTRACT_BLOCKED means a required capability or configuration is missing; the JSON report names the exact check and next action.
• ZOPU_SMOKE_FAILED means runtime execution started but did not satisfy the worker/reviewer contract.

Exit codes are 0 for a passing preflight or completed run, 2 for a contract block, and 1 for a runtime failure. Reports contain only endpoint labels, statuses, counts, ids, and sanitized failure text; model transcripts and credentials are intentionally omitted.

Cleanup

The harness does not create Docker containers or Orb workspaces in preflight mode. In run mode, the Flue project-manager agent owns its sandbox lifecycle. To clean up Orb proof fixtures or run artifacts:

docker container prune -f --filter "label=orb"
rm -rf /tmp/orb-* /tmp/orb-proof-*

Current lane boundary

The smoke intentionally stops before mutation when the project source, issue-scoped AgentOS artifacts, or online daemon contract is absent. The Orb execution-plane checks (Docker, OpenCode, Gitea) report BLOCKED when those external dependencies are not available on the local MacBook; this is expected and does not indicate an implementation failure. See docs/DOGFOOD_V0.md for the full lifecycle.