docs: bootstrap agentrun references

2026-05-27 15:27:38 +08:00
commit 09c59a4dd6
5 changed files with 347 additions and 0 deletions
@@ -0,0 +1,61 @@
+# AgentRun CLI And Service API Reference
+
+AgentRun CLI and service APIs follow the UniDesk `cli-spec` principles. This document records the expected shape before the CLI exists so implementation does not drift toward long blocking commands or hidden state.
+
+## CLI Shape
+
+The future CLI entry should be small and route to implementation modules:
+
+```text
+scripts/agentrun-cli.ts
+scripts/src/*.ts
+```
+
+The CLI should default to JSON output. Empty stdout is a failure, not success. Every command must return enough structured data to continue debugging, including ids, status, log paths or follow-up commands.
+
+Long operations must be fire-and-forget or short asynchronous resource operations. CLI calls should return in under 60 seconds. A command that creates a run or starts a runner returns the created resource and polling commands; it does not wait for the model turn to complete.
+
+## Planned Commands
+
+Initial command families:
+
+```bash
+bun scripts/agentrun-cli.ts runs create --json-file <run.json>
+bun scripts/agentrun-cli.ts runs show <runId>
+bun scripts/agentrun-cli.ts runs events <runId> --after-seq <n> --limit <n>
+bun scripts/agentrun-cli.ts commands create <runId> --type turn --json-file <payload.json>
+bun scripts/agentrun-cli.ts commands show <commandId>
+bun scripts/agentrun-cli.ts runner start --run-id <runId> --backend <backendProfile>
+bun scripts/agentrun-cli.ts backends list
+bun scripts/agentrun-cli.ts server start|status|stop|logs
+```
+
+The exact command names may change when implemented, but the behavior must keep these rules:
+
+- `runs create` creates durable facts and returns immediately.
+- `runner start` starts a local process or Kubernetes Job and returns process/job identity, log path and poll commands.
+- `events` is paged and bounded by default.
+- `server logs` returns bounded logs and points to full log files.
+- `status` must expose port, process id, health and log paths once a local service exists.
+
+## Config And Logs
+
+AgentRun config must be explicit and validated. Do not silently fall back to deployment-critical defaults. When a local development server is introduced, it should use a fixed port and write real-time logs under:
+
+```text
+logs/{YYYYMMDD}/
+```
+
+Runtime state, pid files and transient job metadata belong under:
+
+```text
+.state/
+```
+
+Secrets must not be committed. Credential sources should be represented by references, not values, in CLI output and logs.
+
+## RESTful Service Rule
+
+Stable cross-service boundaries use HTTP JSON resource APIs. The MVP does not use SSE, WebSocket or long synchronous requests. Long-running work is represented by runs, commands, leases, status and paged events.
+
+The CLI should call the same REST API paths that production clients use. Debug commands may expose smaller slices of the flow, but they must share implementation with the real path rather than maintaining a parallel mock-only path.