pikasTech-agentrun/AGENTS.md

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.