docs: record r141-r145 public contract updates

2026-08-14 08:52:45 +00:00 · 2026-03-27 16:52:20 +08:00
parent 72c74c153f
commit ec11c16ac2
5 changed files with 59 additions and 8 deletions
@@ -75,6 +75,18 @@ Deployment profiles and hardening references:

 <details>

+<summary><strong>Snapshot-first diagnostics, delta polling contracts, schema alignment, and optional-dependency import hardening completed</strong></summary>
+
+- Moved Explorer inventory diagnostics onto a snapshot-first contract so `/openclaw/preflight/inventory` returns quickly with explicit `snapshot_ts`, `scan_state`, `stale`, and `last_error` metadata while deep refresh continues in the background.
+- Hardened event and managed-download polling around deterministic cursor metadata, so operator surfaces can resume from `effective` and `next` sequence markers instead of relying on duplicate-prone full refresh loops.
+- Unified webhook and managed-model request/documentation fixtures around one shared contract bundle, tightened model-import destination validation to reject traversal markers fail-closed, and kept the published API/OpenAPI surfaces aligned with the runtime validators.
+- Removed the remaining import-time `aiohttp` traps from high-impact route/service modules by moving them onto one bounded compatibility seam, so minimal environments degrade deterministically at call time instead of crashing on module import.
+- Re-validated the full batch on WSL with the full SOP gate: detect-secrets, pre-commit, governance verification, backend full suites, strict implementation-record lint, real-backend lanes, adaptive adversarial gate, and Playwright E2E.
+
+</details>
+
+<details>
+
 <summary><strong>Frontend host compatibility, asset-backed output interop, and CI audit alignment completed</strong></summary>

 - Hardened frontend host compatibility against current standalone frontend and desktop bundle drift by moving graph/widget compatibility logic onto shared host helpers, adding explicit sidebar host-surface stamping, and surfacing desktop embedded-frontend parity through compatibility diagnostics instead of implicit assumptions.
@@ -847,13 +859,13 @@ The OpenClaw sidebar includes these built-in tabs. Some tabs are capability-gate
 | Tab | What it does | Related docs |
 | --- | --- | --- |
 | `Settings` | Health/config/log visibility, provider/model setup, model connectivity checks, and optional localhost key storage. | [Quick Start](#quick-start-minimal), [LLM config](#llm-config-non-secret), [Troubleshooting](#troubleshooting) |
-| `Jobs` | Tracks prompt IDs, polls trace/history, and shows output previews for recent jobs across classic history refs and asset-backed output refs through the same `/view` contract. | [Observability](#observability-read-only), [Remote Control (Connector)](#remote-control-connector) |
+| `Jobs` | Tracks prompt IDs, consumes deterministic event/task cursor metadata for polling, and shows output previews for recent jobs across classic history refs and asset-backed output refs through the same `/view` contract. | [Observability](#observability-read-only), [Remote Control (Connector)](#remote-control-connector) |
 | `Planner` | Uses assist endpoint to generate structured prompt plans (positive/negative/params). | [Configure an LLM key](#1-configure-an-llm-key-for-plannerrefinervision-helpers), [Nodes](#nodes) |
 | `Refiner` | Refines existing prompts with optional image context and issue/goal input. | [Configure an LLM key](#1-configure-an-llm-key-for-plannerrefinervision-helpers), [Nodes](#nodes) |
 | `Variants` | Local helper for generating batch variant parameter JSON (seed/range-style sweeps). | [Nodes](#nodes), [Operator UX Features](#operator-ux-features) |
 | `Library` | Manages reusable prompt/params presets and provides pack-oriented library operations in one place. | [Presets](#presets-admin), [Packs](#packs-admin) |
 | `Approvals` | Lists approval gates and supports approve/reject operations. | [Triggers + approvals](#triggers--approvals-admin), [Remote Control (Connector)](#remote-control-connector) |
-| `Explorer` | Inventory/preflight diagnostics and snapshot/checkpoint troubleshooting workflows. | [Operator UX Features](#operator-ux-features), [Troubleshooting](#troubleshooting) |
+| `Explorer` | Inventory/preflight diagnostics and snapshot/checkpoint troubleshooting workflows, including snapshot-first inventory refresh state (`snapshot_ts`, `scan_state`, `stale`, `last_error`). | [Operator UX Features](#operator-ux-features), [Troubleshooting](#troubleshooting) |
 | `Packs` | Dedicated pack lifecycle tab for import/export/delete under admin boundary. | [Packs](#packs-admin) |
 | `Model Manager` | Searches model catalog/install records, queues managed downloads, and imports completed tasks into the managed install root. | [Model manager](#model-manager-admin-f54), [Model Manager tab (F64)](#model-manager-tab-f64) |
 | `Parameter Lab` | Runs bounded sweep/compare experiments, stores history, and replays parameters back into the graph. | [Operator UX Features](#operator-ux-features) |
@@ -938,6 +950,7 @@ Base path notes:
 Main API families:

 - Observability: health, capabilities, logs, traces, event feeds
+- Admin diagnostics: preflight inventory snapshot/status, doctor-facing readiness views
 - Config + LLM: effective config, provider tests, model lists, assist planner/refiner
 - Connector installation diagnostics: installation state, resolution, audit views
 - Webhooks + events: validate, submit, callback delivery, SSE/polling status
@@ -956,6 +969,8 @@ Primary references:
 Operational notes:

 - Observability remains token-gated for remote access and redacts provider reasoning-like content by default.
+- Event and managed-download polling now expose deterministic cursor metadata so reconnect/backfill behavior can stay incremental instead of falling back to full-list refreshes on every poll.
+- Preflight inventory is snapshot-first: clients should treat `snapshot_ts`, `scan_state`, `stale`, and `last_error` as part of the normal operator-diagnostics contract.
 - Config/assist/model-management paths inherit the unified config precedence contract and SSRF-safe outbound policy.
 - Connector installation diagnostics expose redacted token references only, never raw token material.
 - Webhook and rate-limit error paths expose machine-readable diagnostics; client integrations should consume codes and structured fields instead of free-form text.
@@ -1100,6 +1115,7 @@ bash scripts/run_full_tests_linux.sh
 ```

 This full gate includes detect-secrets, pre-commit, coverage governance verification, backend suites, adaptive adversarial verification, Playwright E2E, and CI-parity dependency audit expectations scoped to declared project requirements.
+It also includes backend regressions that pin snapshot-first diagnostics, delta cursor semantics, schema/OpenAPI drift checks, and minimal-environment optional-dependency import behavior.

 ## Updating

@@ -8,6 +8,7 @@ This document summarizes the current OpenClaw sidebar UI structure and how to ve
 - Shell: `web/openclaw_ui.js` now acts as the composition root for the sidebar shell and public singleton exports.
 - Actions: `web/openclaw_actions.js` owns submit/cancel/retry wiring and guarded action routing for the shell.
 - Queue monitor: `web/openclaw_queue_monitor.js` owns queue polling lifecycle and transient banner/status updates used by the shell.
+- Event/task polling: admin-console and model/task views consume deterministic delta metadata (`effective_since_seq`, `next_since_seq`, reset/truncation hints) instead of assuming every refresh is a full snapshot.
 - Notification center: `web/openclaw_notification_center.js` owns persistent in-app notification storage, dedupe, acknowledge, dismiss, and deep-link behavior.
 - Banner runtime: `web/openclaw_banner_manager.js` owns transient banner state and shell-facing banner transitions.
 - Tabs: `web/openclaw_tabs.js` manages tab registration, rendering, and remount safety.
@@ -23,6 +24,7 @@ Refactor note:
 - New tab markup should use canonical `openclaw-*` classes; legacy `moltbot-*` aliases are generated centrally at runtime instead of being duplicated in each template.
 - Host-sensitive behaviors should consume the shared host-surface helper rather than inferring desktop vs standalone frontend from ad-hoc globals.
 - Output preview flows should consume the shared asset-ref normalizer rather than assembling `/view` URLs independently in each tab.
+- Explorer/preflight consumers should treat inventory diagnostics as snapshot-first and surface `snapshot_ts`, `scan_state`, `stale`, and `last_error` instead of blocking the UI on full rescans.

 ## Feature Gating (Capabilities)

@@ -57,6 +59,7 @@ If `assist_streaming` is unavailable or the stream transport degrades, Planner/R
 - Runtime behaviors:
  - Dashboard summary + health/config snapshots
  - Jobs/Events polling + SSE stream connect/fallback
+  - Delta-aware polling cursors for events and managed-task refresh loops
  - Approvals/Schedules/Triggers control actions
  - Config read/partial write and diagnostics access
  - Quick Actions (retry/refresh/drill) remain backend-authorized
@@ -76,9 +79,10 @@ If `assist_streaming` is unavailable or the stream transport degrades, Planner/R
 3. Confirm the sidebar host-surface metadata resolves correctly for the current environment instead of defaulting silently.
 4. Planner: click **Plan Generation** with minimal input and confirm either live preview/stage updates appear (when streaming is supported) or a readable fallback result/error appears.
 5. Refiner: click **Refine Prompts** (with or without image) and confirm either live preview/stage updates appear (when streaming is supported) or a readable fallback result/error appears.
-6. Jobs: verify output previews still resolve for both classic history refs and any asset-backed refs surfaced by callback/history payloads.
-7. Library/Approvals: if backend endpoints are not enabled, confirm the UI shows a clear error state (no crashes).
-8. If you simulate/fake a stream failure in dev tools, confirm Planner/Refiner retry through the classic non-stream path without duplicate submits or broken loading state.
+6. Jobs: verify output previews still resolve for both classic history refs and any asset-backed refs surfaced by callback/history payloads, and that repeated polls do not duplicate rows after reconnect/resume.
+7. Explorer: verify preflight inventory can show `refreshing` / `stale` / `error` state without freezing the tab while deep scan work continues.
+8. Library/Approvals: if backend endpoints are not enabled, confirm the UI shows a clear error state (no crashes).
+9. If you simulate/fake a stream failure in dev tools, confirm Planner/Refiner retry through the classic non-stream path without duplicate submits or broken loading state.

 ## E2E (Playwright) Checks

@@ -1,7 +1,7 @@
 openapi: "3.0.3"
 info:
  title: "ComfyUI-OpenClaw API"
-  version: "1.0.5"
+  version: "1.0.6"
  description: "Generated from docs/release/api_contract.md (R66 baseline)."
 servers:
  - url: "/openclaw"
@@ -156,6 +156,21 @@ paths:
      security:
        - OpenClawObservabilityToken:
            []
+  /preflight/inventory:
+    get:
+      operationId: "get_preflight_inventory"
+      summary: "Snapshot-first inventory of nodes/models for operator diagnostics, including refresh-state metadata."
+      responses:
+        200:
+          description: "OK"
+      x-openclaw-auth: "Admin"
+      x-openclaw-section: "1.1 Core Observability & System"
+      description: "Inventory responses may return cached snapshot diagnostics (`snapshot_ts`, `scan_state`, `stale`, `last_error`) while a background refresh continues."
+      x-openclaw-legacy-path: "/moltbot/preflight/inventory"
+      x-openclaw-auth-tier: "admin"
+      security:
+        - OpenClawAdminToken:
+            []
  /webhook:
    post:
      operationId: "post_webhook"
@@ -1,8 +1,8 @@
 # OpenClaw API Contract (v1)

 > **Status**: normative
-> **Version**: 1.0.5
-> **Date**: 2026-03-12
+> **Version**: 1.0.6
+> **Date**: 2026-03-27

 This document defines the public API contract for OpenClaw. It serves as the authoritative baseline for client compatibility and breaking change policies.

@@ -46,6 +46,7 @@ All new integrations should use the `/openclaw/` prefix. Use of `/moltbot/` is d
 | `GET` | `/config` | `/moltbot/config` | Observability | Read-only view of sanitized provider config. |
 | `PUT` | `/config` | `/moltbot/config` | Admin | Update system configuration. |
 | `GET` | `/jobs` | `/moltbot/jobs` | Observability | List recent jobs (Stub/Not Implemented). |
+| `GET` | `/preflight/inventory` | `/moltbot/preflight/inventory` | Admin | Snapshot-first inventory of nodes/models for operator diagnostics, including refresh-state metadata. |

 Reasoning-content redaction contract:

@@ -59,6 +60,11 @@ Reasoning-content redaction contract:
  - deployment profile `local` or `lan`
 - clients MUST treat reveal behavior as debug-only and MUST NOT depend on reasoning payload presence in normal operation

+Inventory diagnostics contract:
+
+- `/preflight/inventory` is snapshot-first and may return before deep scan work finishes
+- clients SHOULD treat `snapshot_ts`, `scan_state`, `stale`, and `last_error` as first-class diagnostics fields rather than assuming a blocking full-rescan model
+
 ### 1.2 Webhooks & Triggers

 **Auth**: Requires configured webhook secret or Admin Token.
@@ -244,6 +250,10 @@ Tenant-boundary error notes:
  - normalized limit/offset/cursor values
  - stale/future cursor resets
  - bounded scan truncation or malformed-record skips
+- `GET /openclaw/preflight/inventory` may return snapshot-state diagnostics so clients/operators can detect:
+  - whether the response came from a previous cached snapshot
+  - whether a background refresh is currently running
+  - whether the current snapshot is stale or the last deep scan failed
 - Backend/runtime errors outside pagination normalization are still surfaced explicitly (not silently swallowed).

 ---
@@ -38,6 +38,12 @@ python scripts/operator_doctor.py
 python scripts/operator_doctor.py --json
 ```

+Explorer / inventory note:
+
+- `/openclaw/preflight/inventory` is snapshot-first on current builds.
+- A response showing `scan_state=refreshing` or `stale=true` does not necessarily mean the inventory path is broken; it can mean the cached snapshot was returned quickly while a deeper model scan continues in the background.
+- Treat `last_error` as the primary signal that the background scan actually failed.
+
 ## Webhooks return `403 auth_not_configured`

 Set webhook auth environment variables as described in the README quick-start section, then restart ComfyUI.