acp spec (#155)

research/acp/missing-features-spec/06-server-status.md

@@ -0,0 +1,144 @@
+# Feature 6: Server Status
+
+**Implementation approach:** Extension fields on `GET /v2/agents` and `GET /v2/health`
+
+## Summary
+
+v1 had `ServerStatus` (Running/Stopped/Error) and `ServerStatusInfo` (baseUrl, lastError, restartCount, uptimeMs) per agent. v2 has none of this. Add server/agent process status tracking.
+
+## Current v2 State
+
+`GET /v2/agents` returns `AgentInfo` with install state only:
+
+```rust
+pub struct AgentInfo {
+    pub id: String,
+    pub native_required: bool,
+    pub native_installed: bool,
+    pub native_version: Option<String>,
+    pub agent_process_installed: bool,
+    pub agent_process_source: Option<String>,
+    pub agent_process_version: Option<String>,
+    pub capabilities: AgentCapabilities,
+}
+```
+
+No runtime status (running/stopped/error), no error tracking, no restart counts.
+
+## v1 Types (exact, from `router.rs`)
+
+```rust
+/// Status of a shared server process for an agent
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum ServerStatus {
+    /// Server is running and accepting requests
+    Running,
+    /// Server is not currently running
+    Stopped,
+    /// Server is running but unhealthy
+    Error,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct ServerStatusInfo {
+    pub status: ServerStatus,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub base_url: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub uptime_ms: Option<u64>,
+    pub restart_count: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_error: Option<String>,
+}
+```
+
+## v1 Implementation (exact)
+
+### `ManagedServer::status_info`
+
+```rust
+fn status_info(&self) -> ServerStatusInfo {
+    let uptime_ms = self.start_time
+        .map(|started| started.elapsed().as_millis() as u64);
+    ServerStatusInfo {
+        status: self.status.clone(),
+        base_url: self.base_url(),
+        uptime_ms,
+        restart_count: self.restart_count,
+        last_error: self.last_error.clone(),
+    }
+}
+```
+
+### `AgentServerManager::status_snapshot`
+
+```rust
+async fn status_snapshot(&self) -> HashMap<AgentId, ServerStatusInfo> {
+    let servers = self.servers.lock().await;
+    servers.iter()
+        .map(|(agent, server)| (*agent, server.status_info()))
+        .collect()
+}
+```
+
+### `AgentServerManager::update_server_error`
+
+```rust
+async fn update_server_error(&self, agent: AgentId, message: String) {
+    let mut servers = self.servers.lock().await;
+    if let Some(server) = servers.get_mut(&agent) {
+        server.status = ServerStatus::Error;
+        server.start_time = None;
+        server.last_error = Some(message);
+    }
+}
+```
+
+## Implementation Plan
+
+### ACP Runtime Tracking
+
+The `AcpRuntime` needs to track per-agent backend process:
+
+```rust
+struct AgentProcessStatus {
+    status: String,            // "running" | "stopped" | "error"
+    start_time: Option<Instant>,
+    restart_count: u64,
+    last_error: Option<String>,
+}
+```
+
+Track:
+- Process start → set status to "running", record `start_time`, increment `restart_count`
+- Process exit (normal) → set status to "stopped", clear `start_time`
+- Process exit (error) → set status to "error", record `last_error`, clear `start_time`
+
+### Add to AgentInfo
+
+```rust
+pub struct AgentInfo {
+    // ... existing fields ...
+    pub server_status: Option<ServerStatusInfo>,
+}
+```
+
+Only include `server_status` for agents that use shared processes (Codex, OpenCode).
+
+### Files to Modify
+
+| File | Change |
+|------|--------|
+| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Track agent process lifecycle (start/stop/error/restart count) per `AgentId`; expose `status_snapshot()` method |
+| `server/packages/sandbox-agent/src/router.rs` | Add `ServerStatus`, `ServerStatusInfo` types; add `server_status` to `AgentInfo`; query runtime for status in `get_v2_agents` |
+| `sdks/typescript/src/client.ts` | Update `AgentInfo` type with `serverStatus` |
+| `server/packages/sandbox-agent/tests/v2_api.rs` | Test server status in agent listing |
+
+### Docs to Update
+
+| Doc | Change |
+|-----|--------|
+| `docs/openapi.json` | Update `/v2/agents` response with `server_status` |
+| `docs/sdks/typescript.mdx` | Document `serverStatus` field |