From 6d11ecc93aa15649b9051c5745f869597608d09b Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Fri, 17 Apr 2026 18:45:16 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(api-ref):=20workspace=20hibernation=20?= =?UTF-8?q?=E2=80=94=20status,=20/hibernate=20endpoint,=20auto-wake=20(PR?= =?UTF-8?q?=20#724)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - api-reference.mdx: add POST /workspaces/:id/hibernate to Lifecycle table; callout explaining hibernated vs paused, 503+Retry-After auto-wake pattern, and hibernation_idle_minutes config option - concepts.mdx: add workspace status lifecycle table (all 7 statuses); document hibernation as opt-in automatic cost-saving mode with link to API ref Pairs with monorepo PR #724 (feat(registry): workspace hibernation). Co-Authored-By: Claude Sonnet 4.6 --- content/docs/api-reference.mdx | 25 ++++++++++++++++++++++++- content/docs/concepts.mdx | 14 ++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx index adde987..82c43f6 100644 --- a/content/docs/api-reference.mdx +++ b/content/docs/api-reference.mdx @@ -80,8 +80,31 @@ Core workspace CRUD and lifecycle operations. | Method | Path | Auth | Description | |--------|------|------|-------------| | POST | `/workspaces/:id/restart` | WorkspaceAuth | Restart the workspace container. Sends a `restart_context` A2A message after successful re-registration. | -| POST | `/workspaces/:id/pause` | WorkspaceAuth | Stop the container and set status to `paused`. Paused workspaces skip health sweep, liveness monitor, and auto-restart. | +| POST | `/workspaces/:id/pause` | WorkspaceAuth | Stop the container and set status to `paused`. Paused workspaces skip health sweep, liveness monitor, and auto-restart. Resume manually via `/resume`. | | POST | `/workspaces/:id/resume` | WorkspaceAuth | Re-provision a paused workspace. Status transitions to `provisioning`. | +| POST | `/workspaces/:id/hibernate` | WorkspaceAuth | Immediately hibernate a workspace (stop container, set status to `hibernated`). Useful for manual cost control. See hibernation note below. | + + + **Workspace hibernation** + + A workspace with `hibernation_idle_minutes` set in its config will be **automatically hibernated** by the platform after that many idle minutes (no active tasks, no recent heartbeat). The monitor checks every 2 minutes. + + `hibernated` differs from `paused`: + - **`paused`** — manual, resumes only via `POST /resume`. + - **`hibernated`** — automatic (or via `POST /hibernate`), resumes **automatically** when an A2A message arrives. + + When a message is sent to a hibernated workspace, the platform returns: + ``` + HTTP 503 Retry-After: 15 + {"waking": true} + ``` + Callers should retry after ~15 seconds. The workspace typically returns to `online` within that window. + + To opt a workspace into auto-hibernation, add to its `config.yaml`: + ```yaml + hibernation_idle_minutes: 30 # hibernate after 30 min idle; null (default) = disabled + ``` + --- diff --git a/content/docs/concepts.mdx b/content/docs/concepts.mdx index ef70c56..90f30a7 100644 --- a/content/docs/concepts.mdx +++ b/content/docs/concepts.mdx @@ -22,6 +22,20 @@ Workspaces talk to each other via **A2A** (agent-to-agent) messages, routed by the platform. Communication rules: same workspace, siblings, and parent/child are allowed; everything else is denied. +### Workspace status lifecycle + +| Status | Meaning | Resumes via | +|--------|---------|-------------| +| `provisioning` | Container being started | automatic | +| `online` | Running and accepting tasks | — | +| `degraded` | Heartbeat `error_rate > 0.5` | auto-recovers | +| `offline` | Missed heartbeats (liveness sweep) | auto-restart | +| `paused` | Manually stopped via `/pause` | `POST /resume` | +| `hibernated` | Auto-paused after idle timeout (or via `/hibernate`) | automatic on next A2A message | +| `removed` | Deleted | — | + +**Hibernation** is an opt-in automatic cost-saving mode. Set `hibernation_idle_minutes` in the workspace's `config.yaml` to enable it. When a hibernated workspace receives an A2A message, the platform wakes it automatically (returning `503 Retry-After: 15` while it comes online). See [API Reference — Lifecycle](/docs/api-reference#lifecycle) for the `/hibernate` endpoint and configuration details. + ## External agents An **external agent** is a workspace with `runtime: external` — it runs on From edda3a068d8e4453c8206eabc7702d6febf6734b Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Sat, 18 Apr 2026 03:04:32 +0000 Subject: [PATCH 2/2] docs(api-ref): note atomic hibernate guarantee from PR #882 Closes the TOCTOU race (PR #882/issue #819): documents that hibernation uses an atomic SQL claim that aborts if active_tasks > 0 at commit time, so no in-flight task is silently dropped. Co-Authored-By: Claude Sonnet 4.6 --- content/docs/api-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx index 82c43f6..2a6c8de 100644 --- a/content/docs/api-reference.mdx +++ b/content/docs/api-reference.mdx @@ -104,6 +104,8 @@ Core workspace CRUD and lifecycle operations. ```yaml hibernation_idle_minutes: 30 # hibernate after 30 min idle; null (default) = disabled ``` + + **Atomic hibernation guarantee:** The platform uses a single atomic SQL claim (`UPDATE … WHERE active_tasks = 0`) before stopping the container. If a task arrives between the idle check and the container stop, the claim fails and hibernation is aborted — no in-flight tasks are silently lost. ---