SciMesh/.agents/worker.md

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.