# AgentRun Agent Index

AgentRun is the shared agent execution infrastructure for UniDesk and HWLAB. This repository owns AgentRun architecture, API contracts, runner/backend behavior and runtime implementation. UniDesk only records how distributed development and deployment are coordinated from the UniDesk control center.

## Critical Source Workspace Rule

- P0: The canonical source workspace is `G14:/root/agentrun`, fixed on branch `master`, with `origin git@github.com:pikasTech/agentrun.git`.
- P0: Before development, deployment, resumed work or context recovery, run `tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'` from UniDesk and confirm the path, branch, remote and clean state.
- P0: The fixed workspace is only for precheck, fetch, worktree management and final sync. Normal work must use `/root/agentrun/.worktree/{pr_branch}` created from latest `origin/master`.
- P0: Do not use UniDesk, HWLAB, D601 workspaces, temporary clones, pod-local copies or runner checkouts as AgentRun source truth.

## Critical Runtime Target Rule

- P0: Default deployment targets are G14 native k3s namespaces `agentrun_dev` and `agentrun_prod`.
- P0: Kubernetes operations must use UniDesk route syntax `G14:k3s`, for example `tran G14:k3s kubectl get pods -n agentrun_dev`.
- P0: Do not create durable AgentRun exposure through ad hoc NodePort, host port, direct pod IP, one-off port-forward or provider-gateway business HTTP proxy. Public or cross-service access must be introduced through reviewed repository changes.

## Critical MVP Rule

- P0: AgentRun must be developed as a vertical MVP, not as a broad parallel service rewrite.
- P0: First prove minimal `runner + one backend`; then add `agentrun-mgr` durable facts and manual runner startup; only after that add automatic scheduler.
- P0: Existing UniDesk Code Queue and HWLAB Code Agent paths are not replaced by default. AgentRun starts as a new shared execution plane with canary integrations.

## Critical RESTful MVP Rule

- P0: The MVP uses short RESTful HTTP/JSON requests only. Do not add SSE, WebSocket, long-polling or long synchronous `turn` calls in the first phase.
- P0: Long agent work must be represented by asynchronous resources: commands, runs, events, status and leases. Clients observe progress by paged polling.
- P0: Runner inbound API should stay private and minimal. Clients should call `agentrun-mgr`; manually started runners must still claim and report through the manager.

## Critical CLI Spec Rule

- P0: AgentRun CLI and service work must follow the UniDesk `cli-spec` principles: JSON output by default, no empty-success output, no long blocking CLI calls, visible logs, explicit config validation and RESTful service APIs for stable boundaries.
- P0: Once a CLI is added, keep the entry small and move implementation into `scripts/src/`; long operations must return quickly and expose status/log/event polling.

## Reference Docs

- `docs/reference/architecture.md`: AgentRun product boundary, service architecture, MVP phases, RESTful API model and data model.
- `docs/reference/cli.md`: CLI and service API conventions derived from `cli-spec`.
- `TEST.md`: manual validation scenarios for the documented CLI/service behavior as it is implemented.