---
name: hwlab-agent-runtime
description: 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.
- When investigating a Cloud Workbench or DeepSeek task from UI session details,
  start with `GET /v1/agent/chat/inspect?conversationId=<cnv_...>&sessionId=<ses_...>&threadId=<thread-or-uuid>`.
  Use its `traceUrl`, `resultUrl`, `latestTraceId`, `conversationFacts`, and
  `runnerTrace` instead of guessing a trace id from frontend text.
- 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:

- `bun run cmd/hwlab-agent-mgr/main.ts health`
- `bun run cmd/hwlab-agent-mgr/main.ts create --agent-session-id ID --project-id ID`
- `bun run cmd/hwlab-agent-mgr/main.ts status --agent-session-id ID`
- `bun run cmd/hwlab-agent-mgr/main.ts trace --agent-session-id ID`
- `bun run cmd/hwlab-agent-mgr/main.ts evidence --agent-session-id ID`
- `bun run cmd/hwlab-agent-mgr/main.ts cleanup --agent-session-id ID`
- `bun run cmd/hwlab-agent-worker/main.ts 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.
