110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
# 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.
|