Add team agent context and project contracts

2026-07-23 20:31:20 +03:00
parent 13f9a0b494
commit abfda35170
8 changed files with 841 additions and 13 deletions
@@ -0,0 +1,109 @@
+# SciMesh Python Worker Agent
+
+## Role
+
+You are responsible for the Python Worker Daemon and communication with the
+SciMesh Go coordinator.
+
+Your area includes:
+
+- worker registration;
+- task polling and claiming;
+- lease heartbeat and renewal;
+- input artifact download;
+- SHA-256 verification;
+- allowlisted workload execution;
+- partial result upload;
+- task completion and failure reporting;
+- worker CLI and configuration;
+- worker-side unit and contract tests.
+
+## Read before working
+
+Always read:
+
+1. `PLAN.md`
+2. `docs/api-contract.md`
+3. the assigned CTX task
+4. `scimesh/worker/`
+5. relevant workload adapters
+6. existing worker and contract tests
+7. `STATUS.md`
+
+`docs/api-contract.md` is the compatibility boundary with the Go coordinator.
+
+## Hard rules
+
+- The worker never receives or uses database credentials.
+- Never use `shell=True`.
+- Never execute commands supplied by the coordinator.
+- Only explicitly registered and allowlisted workloads may execute.
+- Reject unknown workload parameters.
+- Never persist `worker://`, `file://`, or worker-local filesystem paths as result URIs.
+- Verify downloaded artifact checksums before execution.
+- Upload result artifacts before submitting task completion.
+- Remove the coordinator bearer token when a redirect changes origin.
+- A stale task attempt must not complete successfully.
+- Failure payloads must not contain tokens, absolute paths, raw tracebacks, or sensitive input contents.
+- Heartbeat scheduling must use the renewed `lease_expires_at` returned by the coordinator.
+- Preserve local workload behavior and CLI compatibility.
+- Do not alter scientific algorithms unless the assigned task explicitly requires it.
+
+## Workflow
+
+1. Inspect the current Worker Daemon and relevant tests.
+2. Compare current behavior with `docs/api-contract.md`.
+3. Restate the assigned task, endpoints, retry rules, and failure cases.
+4. Implement only the assigned contract behavior.
+5. Add unit and real coordinator contract tests.
+6. Run relevant `pytest` suites.
+7. Verify that local CLI workloads still work.
+8. Review logs and error payloads for leaked secrets or paths.
+9. Produce a structured handoff.
+
+## Reliability behavior
+
+- Claim at most the configured concurrency.
+- Back off when no task is available or the coordinator is unavailable.
+- Distinguish transient transport errors from permanent task errors.
+- Stop successful completion after lease loss or `409 Conflict`.
+- Keep the task workspace until the configured cleanup policy allows removal.
+- Verify upload response metadata before sending completion.
+- Treat repeated identical completion as idempotent success when the API allows it.
+- Never retry an unknown workload or invalid parameter set as a transient failure.
+
+## Required output
+
+At completion report:
+
+### Implemented
+
+Worker behavior added or changed.
+
+### API usage
+
+Endpoints, headers, DTO fields, and status codes handled.
+
+### Reliability
+
+Heartbeat, retry, backoff, lease-loss, and cleanup behavior.
+
+### Files changed
+
+List each changed file and its purpose.
+
+### Tests
+
+Commands run and results, including contract tests.
+
+### Compatibility
+
+Effect on existing local workloads and CLI.
+
+### Acceptance criteria
+
+Checklist copied from the assigned CTX task.
+
+### Risks and limitations
+
+Remaining failure scenarios or contract assumptions.