From 486e94d2e055d75749207e5a5791fd704bbdfffb Mon Sep 17 00:00:00 2001 From: rookiestar28 Date: Sat, 11 Jul 2026 02:33:23 +0800 Subject: [PATCH] docs: refresh jobs and output guidance --- README.md | 22 ++++++++++++++++++++-- docs/connector.md | 22 ++++++++++++++++++++++ docs/release/recent_updates.md | 19 +++++++++++++++++++ docs/release/threat_model.md | 8 ++++++-- docs/troubleshooting.md | 22 ++++++++++++++++++++++ 5 files changed, 89 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 06d1833..14ec9db 100644 --- a/README.md +++ b/README.md @@ -91,8 +91,18 @@ Deployment profiles and hardening references:
-Host compatibility, output previews, media safety, and graph guards refreshed +Secure jobs visibility, host compatibility, output previews, and graph guards refreshed +- `GET /openclaw/jobs` now provides an Admin-only, versioned jobs view with bounded + status/workflow filtering, sorting, pagination, and privacy-minimized summaries across + pending, in-progress, completed, failed, and cancelled work. +- Jobs listing distinguishes an authoritative empty snapshot from unsupported or + unavailable host contracts and never returns raw prompts, workflows, execution errors, + tracebacks, current inputs/outputs, tenant/client/trace identifiers, or reasoning text. +- Authorized connector operators can use `/jobs` (plus `jobs` or `queue`) for a bounded + authoritative summary. The connector validates the response contract, displays only + aggregate counts and short job IDs, and uses a coarse queue-count fallback only for + explicit host-contract/backend unavailability. - Published host compatibility notes now pin the current ComfyUI, standalone frontend, and Desktop reference anchors while keeping Desktop embedded-frontend lag explicit. - Output previews keep filename-backed refs first-class, accept optional `asset_hash` / `hash` metadata when present, and leave asset-service-only identifiers as explicit fallback states. - LINE and WhatsApp connector media URLs now force dangerous active content such as SVG/HTML/JS/CSS/XML to download with no-sniff response headers while preserving safe image delivery. @@ -516,6 +526,8 @@ Base path notes: Main API families: - Observability: health, capabilities, logs, traces, event feeds +- Jobs visibility: Admin-only, bounded and privacy-minimized list/filter/sort/pagination + over the in-process ComfyUI queue and history snapshot - Admin diagnostics: preflight inventory snapshot/status, doctor-facing readiness views - Config + LLM: effective config, provider tests, model lists, assist planner/refiner - Connector diagnostics: installation state, resolution, callback/tenant binding evidence, audit views, extraction seam metadata, and static service-env SecretRef propagation policy @@ -536,6 +548,10 @@ Primary references: Key operational notes: - Observability remains token-gated for remote access and redacts provider reasoning-like content plus marked internal maintenance/helper content by default. +- `GET /openclaw/jobs` is Admin-only and returns contract version 1 with bounded job + summaries and pagination. Treat HTTP 200 with `jobs: []` as an authoritative empty + snapshot, HTTP 501 as an unsupported host contract, and HTTP 503 as backend + unavailability; neither failure is an empty success. - Event/model-download polling and preflight inventory are snapshot/cursor-driven contracts; clients should consume `snapshot_ts`, `scan_state`, `stale`, and cursor metadata instead of assuming full-refresh polling. - Model Manager and preflight consumers should use current ComfyUI folder keys for model types where possible, including `text_encoders`, `diffusion_models`, `gligen`, `latent_upscale_models`, `hypernetworks`, `photomaker`, `model_patches`, `geometry_estimation`, and `detection`; compatibility aliases such as `clip`, `unet`, `ckpt`, and plural legacy names are normalized before lookup/import. - Output/history-facing consumers should keep using the bounded `/history` + `/view` contract; current previewable output groups include `images`, `video`, `audio`, `3d`, and bounded `text`, while optional hash-backed refs are used only when host metadata is present and refs that only upstream asset services can resolve remain explicit `asset_api_required` compatibility states. @@ -745,7 +761,9 @@ OpenClaw includes a standalone **Connector** process that allows you to control The connector currently remains an **optional attached subsystem inside this repo/package boundary**. Current builds expose extraction diagnostics for maintainers, but do **not** treat a standalone connector package or separate-repo distribution as a supported release shape. -- **Status & Queue**: Check job progress remotely. +- **Status & Queue**: Authorized operators can use `/jobs` for a bounded authoritative + jobs summary; public `/status` remains a coarse health/queue view and does not receive + the Admin-only jobs payload. - **Run Jobs**: Submit templates via chat commands. - **Targeted cancellation**: `/stop`, `/cancel`, and `/interrupt` without job IDs send an explicit global interrupt; supplying one or more job IDs requests targeted ComfyUI job cancellation. - **Approvals**: Approve/Reject paused workflows from your phone. diff --git a/docs/connector.md b/docs/connector.md index 9b09ff2..ef6d7c6 100644 --- a/docs/connector.md +++ b/docs/connector.md @@ -289,6 +289,28 @@ OPENCLAW_COMMAND_ALLOW_FROM_RUN=alice_id,ops_bot_id If a class-level `OPENCLAW_COMMAND_ALLOW_FROM_*` list is set and non-empty, only listed IDs can run that class. +### Authoritative jobs summary + +`/jobs` and its `jobs` / `queue` aliases are Admin-class commands. They require both an +authorized connector admin user and a configured `OPENCLAW_CONNECTOR_ADMIN_TOKEN` before +the connector calls `GET /openclaw/jobs`. + +The connector validates jobs contract version 1 before rendering any reply: + +- output contains aggregate snapshot/page counts plus at most five job IDs and statuses; +- displayed job IDs are capped at 24 characters and the complete reply is capped at 1,000 + characters; +- raw job records, prompts, workflows, outputs, errors, tracebacks, tenant identifiers, + and the upstream payload are never sent to the chat LLM or copied into error messages; +- HTTP 401/403 returns a fixed authorization message without fallback; +- only explicit HTTP 501 `jobs_host_contract_unsupported` or HTTP 503 + `jobs_backend_unavailable` responses may fall back to a bounded coarse queue count; +- malformed, unknown-version, oversized, or inconsistent success payloads fail to a fixed + content-free message. + +Public `/status` remains separate: it can summarize health and the coarse ComfyUI queue, +but it does not fetch or forward the Admin-only jobs snapshot. + ### 3. Usage #### Running the Connector diff --git a/docs/release/recent_updates.md b/docs/release/recent_updates.md index 0fba27f..7951bab 100644 --- a/docs/release/recent_updates.md +++ b/docs/release/recent_updates.md @@ -7,6 +7,25 @@ Newest entries appear first.
+Secure jobs visibility and connector summaries completed + +- Replaced the placeholder jobs listing with an Admin-only, versioned in-process read + model over current ComfyUI queue/history state, including five lifecycle states and + bounded status/workflow filters, sorting, pagination, and source/scan diagnostics. +- Reduced every listed job to an allowlisted summary and excluded raw prompts, workflows, + execution errors, tracebacks, current inputs/outputs, tenant/client/trace identifiers, + reasoning, and internal content from successful responses and audit details. +- Preserved authoritative empty snapshots while distinguishing unsupported host contracts + (HTTP 501) from unavailable or malformed snapshots (HTTP 503), so failures cannot look + like an empty queue. +- Added an Admin-class connector `/jobs` summary that validates contract version 1, + renders bounded aggregate counts and short IDs, keeps the raw payload out of the chat + LLM, and permits only a coarse queue-count fallback for explicit 501/503 conditions. + +
+ +
+ Host compatibility reference anchors refreshed - Refreshed the active compatibility baseline to ComfyUI `1377a2f7` (`v0.27.0-47-g1377a2f7`, pyproject `0.27.0`) and standalone frontend `1.48.1` (`ceb5ae1eba`, `v1.48.1-1-gceb5ae1eba`). diff --git a/docs/release/threat_model.md b/docs/release/threat_model.md index 5133545..3613aa2 100644 --- a/docs/release/threat_model.md +++ b/docs/release/threat_model.md @@ -25,9 +25,13 @@ Operators should use this to understand the risks of deployment. * **Who**: Chat users (Telegram/Discord/LINE). * **Access**: * **User**: `submit_job` (via Allowlisted templates), `query_status`. - * **Admin (Chat)**: `approve_request`, `cancel_job`, `trace`. + * **Admin (Chat)**: `approve_request`, `cancel_job`, `trace`, and privacy-minimized + `list_jobs` summaries. * **Mechanism**: Chat platform auth + OpenClaw User Allowlist (or `require_approval` policy). -* **Risk**: Spam/DoS (mitigated by Budgets + Rate Limits), or Prompt Injection (mitigated by Template Constraints). +* **Risk**: Spam/DoS (mitigated by Budgets + Rate Limits), Prompt Injection (mitigated by + Template Constraints), or job metadata disclosure (mitigated by Admin-only authorization, + allowlisted bounded fields, content-free errors, and keeping raw jobs payloads out of the + chat LLM). --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e7dd2ea..259a499 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -63,6 +63,28 @@ Explorer / inventory note: - 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. +## Jobs list or connector `/jobs` reports authorization or backend errors + +`GET /openclaw/jobs` is an Admin-only bounded read model. For direct API/browser calls, +send the configured Admin token and use only the documented `status`, `workflow_id`, +`sort_by`, `sort_order`, `limit`, and `offset` query fields. + +Interpret results as follows: + +- HTTP 200 with `jobs: []` is an authoritative empty snapshot. +- HTTP 401/403 means Admin authentication or tenant authorization failed; verify + `OPENCLAW_ADMIN_TOKEN`, and for connector commands also verify + `OPENCLAW_CONNECTOR_ADMIN_TOKEN` plus the sender's Admin allowlist/class policy. +- HTTP 501 `jobs_host_contract_unsupported` means the active ComfyUI host does not expose + the required queue/history helper contract. +- HTTP 503 `jobs_backend_unavailable` means the host snapshot was unavailable or malformed; + it must not be treated as an empty queue. + +The connector `/jobs` command returns fixed, content-free failures. It can show a bounded +coarse queue-count fallback only for the explicit 501/503 conditions above; authorization, +unknown-version, malformed, or oversized responses do not fall back and never echo the raw +upstream payload. + ## External tool execution is disabled or fails with sandbox diagnostics External tools are disabled by default and require an admin boundary plus an explicit feature flag.