pikasTech-HWLAB/skills/hwlab-agent-runtime/SKILL.md

name, description

name	description
hwlab-agent-runtime	Build and validate the HWLAB agent-mgr and agent-worker runtime skeleton, including session lifecycle, workspace volume bookkeeping, trace events, evidence records, and explicit skills commitId handling.

HWLAB Agent Runtime

Skill(cli-spec)

Scope: this skill is only for HWLAB-internal Code Agent runtime work inside the HWLAB repository and runtime, such as /workspace/hwlab agent sessions, /root/hwlab source changes, and HWLAB-managed worker or skill services. It does not apply to external developer workspaces such as /root/unidesk; those workspaces must follow their own repository instructions and must not treat this skill as a general UniDesk or third-party developer runtime contract.

Use this skill when working on HWLAB agent runtime skeletons.

• Keep the control plane long-lived and worker execution session-scoped.
• Model the lifecycle as create, start, trace, finish, cleanup.
• Always carry explicit evidence record fields through the run plan.
• Use repo-local skills artifacts only when commitId and version are supplied explicitly.
• Do not infer or fall back to external skill sources.
• For M3 hardware control, use only the repo-owned Skill CLI below. It calls HWLAB cloud-api POST /v1/m3/io; it must not call gateway, box, or patch-panel URLs directly, and it must not use an OpenAI/text fallback as hardware capability.

Local CLI Contract

All commands emit JSON and stay local:

• node cmd/hwlab-agent-mgr/main.mjs health
• node cmd/hwlab-agent-mgr/main.mjs create --agent-session-id ID --project-id ID
• node cmd/hwlab-agent-mgr/main.mjs status --agent-session-id ID
• node cmd/hwlab-agent-mgr/main.mjs trace --agent-session-id ID
• node cmd/hwlab-agent-mgr/main.mjs evidence --agent-session-id ID
• node cmd/hwlab-agent-mgr/main.mjs cleanup --agent-session-id ID
• node cmd/hwlab-agent-worker/main.mjs dry-run --agent-session-id ID
• node skills/hwlab-agent-runtime/scripts/hwlab-agent-runtime-cli.mjs m3 status --api-base-url URL
• node skills/hwlab-agent-runtime/scripts/hwlab-agent-runtime-cli.mjs m3 io --action do.write --value true --approved --api-base-url URL
• node skills/hwlab-agent-runtime/scripts/hwlab-agent-runtime-cli.mjs m3 io --action do.write --value false --approved --api-base-url URL
• node skills/hwlab-agent-runtime/scripts/hwlab-agent-runtime-cli.mjs m3 io --action di.read --api-base-url URL
• node tools/hwlab-cli/bin/hwlab-cli.mjs m3 status --api-base-url URL
• node tools/hwlab-cli/bin/hwlab-cli.mjs m3 io --action do.write --value true --approved --api-base-url URL

Use --state-dir DIR to isolate local state. The default state directory is .state/agent-runtime, which is intended for local runtime state only.

Provide both --skill-commit-id COMMIT and --skill-version VERSION for a ready health result. Missing fields must produce degraded health and degraded evidence metadata; there is no silent fallback.

M3 IO Control Contract

The M3 IO CLI is the controlled Code Agent -> Skill CLI -> HWLAB API adapter. --api-base-url must be a cloud-api base such as http://hwlab-cloud-api.hwlab-dev.svc.cluster.local:6667 or the public DEV API endpoint. In the cloud-api runtime, configure HWLAB_CODE_AGENT_HWLAB_API_BASE_URL=http://hwlab-cloud-api.hwlab-dev.svc.cluster.local:6667 so the Skill CLI can reach the service-local HWLAB API from inside the container. The CLI appends /v1/m3/io itself and rejects direct gateway/box/patch-panel targets. If no API base URL is configured, the CLI returns skill_cli_api_base_missing and does not fall back to 127.0.0.1 or any direct hardware service.

Use m3 status for read-only status aggregation; it performs GET /v1/m3/status through the HWLAB API base and never calls gateway, box, or patch-panel URLs. Use m3 io --action di.read for a controlled DI read through POST /v1/m3/io. DO writes must include --approved or --confirm-control; without that explicit approval flag the CLI returns approval_required before any HTTP request. The Code Agent runner adds this flag only after the user's message explicitly asks to write res_boxsimu_1 / DO1 through the HWLAB API, and the request body carries an approval object with policy hwlab-api-control-with-approval.

The JSON response includes route, method, traceId, operationId, audit, evidence, accepted, status, readback, capabilityLevel, readiness, blocker, trustBlocker, and direct-call safety flags. capabilityLevel is hwlab-api-control-with-approval only after the HWLAB API accepts an approved write request through /v1/m3/io; read-only status uses hwlab-api-readonly. Direct target rejection, gateway unavailability, missing wiring, approval absence, or other control blockers return hwlab-api-control-blocked. Durable runtime blockers are preserved as structured durable, trustBlocker, and evidence state; a reachable control path with blocked durable persistence must not be called DEV-LIVE or trusted green.