From 963073088d41e900df2ecb5a879a5d1500f1f6a6 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 5 May 2026 21:47:24 -0700 Subject: [PATCH] docs: audit and fix 5 pages (sentence-case headings + Related/title) --- docs/concepts/mantis.md | 22 ++++++------- docs/concepts/message-lifecycle-refactor.md | 36 ++++++++++----------- docs/plugins/sdk-channel-message.md | 22 ++++++------- docs/providers/deepinfra.md | 8 +++-- docs/security/incident-response.md | 2 -- 5 files changed, 45 insertions(+), 45 deletions(-) diff --git a/docs/concepts/mantis.md b/docs/concepts/mantis.md index 0f8682f084f..e87ae37f189 100644 --- a/docs/concepts/mantis.md +++ b/docs/concepts/mantis.md @@ -33,7 +33,7 @@ browser UI where humans can visually confirm what the transport showed. - Post concise status to an operator Discord channel when the run is blocked, needs manual VNC help, or finishes. -## Non Goals +## Non goals - Mantis is not a replacement for unit tests. A Mantis run should usually become a smaller regression test after the fix is understood. @@ -62,7 +62,7 @@ Mantis lives in the OpenClaw QA stack. This boundary keeps transport knowledge in OpenClaw, machine scheduling in Crabbox, and maintainer workflow glue in ClawSweeper. -## Command Shape +## Command shape The first local command verifies the Discord bot, guild, channel, message send, reaction send, and artifact path: @@ -317,7 +317,7 @@ The first command is explicit and scenario-focused. The second can later map a P or issue to recommended Mantis scenarios from labels, changed files, and ClawSweeper review findings. -## Run Lifecycle +## Run lifecycle 1. Acquire credentials. 2. Allocate or reuse a VM. @@ -412,7 +412,7 @@ polls the real Discord triggering message and expects the observed sequence `discord-status-reactions-tool-only-timeline.html`, and `discord-status-reactions-tool-only-timeline.png`. -## Existing QA Pieces +## Existing QA pieces Mantis should build on the existing private QA stack instead of starting from zero: @@ -430,7 +430,7 @@ zero: The first Mantis implementation can be a thin before/after runner over these pieces, plus one visual evidence layer. -## Evidence Model +## Evidence model Every run writes a stable artifact directory: @@ -473,7 +473,7 @@ private channel names, user names, or message content may appear. For public PRs prefer GitHub Actions artifact links over inline images until the redaction story is stronger. -## Browser And VNC +## Browser and VNC The browser lane has two modes: @@ -561,7 +561,7 @@ guild, channel, and message ids. The GitHub smoke workflow enables If a token is accidentally pasted into an issue, PR, chat, or log, rotate it after the new secret has been stored. -## GitHub Artifacts And PR Comments +## GitHub artifacts and PR comments Mantis workflows should upload the full evidence bundle as a short-lived Actions artifact. When the workflow is run for a bug report or fix PR, it should also @@ -600,7 +600,7 @@ candidate showed the expected queued -> thinking -> done sequence. When the run fails because the harness failed, the comment must say that instead of implying the candidate failed. -## Private Deployment Notes +## Private deployment notes A private deployment may already have a Mantis Discord application. Reuse that application instead of creating another app when it has the right bot @@ -614,7 +614,7 @@ Do not put guild ids, channel ids, bot tokens, browser cookies, or VNC passwords in this document. Store them in GitHub secrets, the credential broker, or the operator's local secret store. -## Adding A Scenario +## Adding a scenario A Mantis scenario should declare: @@ -643,7 +643,7 @@ Scenarios should prefer small, typed oracles: Vision checks should be additive. If a platform API can prove the bug, use the API as the pass/fail oracle and keep screenshots for human confidence. -## Provider Expansion +## Provider expansion After Discord, the same runner can add: @@ -657,7 +657,7 @@ After Discord, the same runner can add: Each transport should have one cheap smoke scenario and one or more bug-class scenarios. Expensive visual scenarios should stay opt-in. -## Open Questions +## Open questions - Which Discord bot should be the driver, and which should be the SUT, when the existing Mantis bot is reused? diff --git a/docs/concepts/message-lifecycle-refactor.md b/docs/concepts/message-lifecycle-refactor.md index ce55c30425e..edc57c23776 100644 --- a/docs/concepts/message-lifecycle-refactor.md +++ b/docs/concepts/message-lifecycle-refactor.md @@ -75,7 +75,7 @@ non-durable policy. - Structured OpenClaw-origin metadata for operational/system output so visible gateway failures do not re-enter shared bot-enabled rooms as fresh prompts. -## Non Goals +## Non goals - Do not remove `runtime.channel.turn.*` in the first phase. - Do not force every channel into the same native transport behavior. @@ -84,7 +84,7 @@ non-durable policy. - Do not publish all internal migration helpers as stable SDK API. - Do not make retries replay completed non-idempotent platform operations. -## Reference Model +## Reference model Vercel Chat has a good public mental model: @@ -114,7 +114,7 @@ What OpenClaw needs beyond that model: `thread.post()` style promises are not enough for OpenClaw. They hide the transaction boundary that decides whether a send is recoverable. -## Core Model +## Core model The new domain should live under an internal core namespace such as `src/channels/message/*`. @@ -137,7 +137,7 @@ core.messages.state(...) `state` owns durable intent storage, receipts, idempotency, recovery, locks, and dedupe. -## Message Terms +## Message terms ### Message @@ -284,7 +284,7 @@ A receipt can describe one platform message or a multi-part delivery. Chunked text, media plus text, voice plus text, and card fallbacks must preserve all platform ids while still exposing a primary id for threading and later edits. -## Receive Context +## Receive context Receiving should not be a bare helper call. The core needs a context that knows dedupe, routing, session recording, and platform ack policy. @@ -382,7 +382,7 @@ source if we need platform-level redelivery beyond OpenClaw's restart watermark. Webhook platforms may need immediate HTTP ack, but they still need inbound dedupe and durable outbound send intents because webhooks can redeliver. -## Send Context +## Send context Sending is also context based: @@ -504,7 +504,7 @@ fallback with no durable record for the remaining payloads. Recovery must know which units already have receipts and either replay only missing units or mark the batch `unknown_after_send` until the adapter reconciles it. -## Live Context +## Live context Preview, edit, progress, and stream behavior should be one opt-in lifecycle. @@ -552,7 +552,7 @@ This should cover current behavior: - Teams native progress stream. - QQ Bot stream or accumulated fallback. -## Adapter Surface +## Adapter surface The public SDK target should be one subpath: @@ -651,7 +651,7 @@ type MessageCapabilities = { }; ``` -## Public SDK Reduction +## Public SDK reduction The new public surface should absorb or deprecate these conceptual areas: @@ -672,7 +672,7 @@ Bundled plugins may keep internal helper imports through reserved runtime subpaths while migrating. Public docs should steer plugin authors to `plugin-sdk/channel-message` once it exists. -## Relationship To Channel Turn +## Relationship to channel turn `runtime.channel.turn.*` should stay during migration. @@ -699,7 +699,7 @@ After all bundled plugins and known third-party compatibility paths are bridged, published SDK migration path and contract tests proving old plugins still work or fail with a clear version error. -## Compatibility Guardrails +## Compatibility guardrails During migration, generic durable delivery is opt-in for any channel whose existing delivery callback has side effects beyond "send this payload". @@ -775,7 +775,7 @@ Concrete migration hazards to preserve: Channels must not implement this with visible-text prefix filters except as a short emergency stopgap; the durable contract is structured origin metadata. -## Internal Storage +## Internal storage The durable queue should store message send intents, not reply payloads. @@ -822,7 +822,7 @@ load pending or sending intents The queue should keep enough identity to replay through the same account, thread, target, formatting policy, and media rules after restart. -## Failure Classes +## Failure classes Channel adapters classify transport failures into closed categories: @@ -852,7 +852,7 @@ Core policy: commit becomes `unknown_after_send` unless the adapter can prove the platform operation did not happen. -## Channel Mapping +## Channel mapping | Channel | Target migration | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -879,7 +879,7 @@ Core policy: | Zalo | Simple receive plus send adapter. | | Zalo Personal | Simple receive plus send adapter. | -## Migration Plan +## Migration plan ### Phase 1: Internal Message Domain @@ -984,7 +984,7 @@ messages". - Remove or hide old internal helpers only after no bundled plugin needs them and third-party contracts have a stable replacement. -## Test Plan +## Test plan Unit tests: @@ -1067,7 +1067,7 @@ Validation: - Live or qa-channel smoke for at least one edit-capable channel and one simple send-only channel before removing compatibility wrappers. -## Open Questions +## Open questions - Whether Telegram should eventually replace the grammY runner source with a fully durable polling source that can control platform-level redelivery, not @@ -1086,7 +1086,7 @@ Validation: - Which channels have native origin metadata, which need persisted outbound registries, and which cannot offer reliable cross-bot echo suppression. -## Acceptance Criteria +## Acceptance criteria - Every bundled message channel sends final visible output through `messages.send`. diff --git a/docs/plugins/sdk-channel-message.md b/docs/plugins/sdk-channel-message.md index 3186ba85a28..2502bf17fd2 100644 --- a/docs/plugins/sdk-channel-message.md +++ b/docs/plugins/sdk-channel-message.md @@ -7,8 +7,6 @@ read_when: - You are migrating from legacy reply pipeline or inbound reply dispatch helpers --- -# Channel Message API - Channel plugins should expose one `message` adapter from `openclaw/plugin-sdk/channel-message`. The adapter describes the native message lifecycle that the platform supports: @@ -33,7 +31,7 @@ Runtime delivery helpers are available from `openclaw/plugin-sdk/channel-message-runtime` for monitor/send code paths that are already doing asynchronous message I/O. -## Minimal Adapter +## Minimal adapter Most new channel plugins can start with a small adapter: @@ -93,7 +91,7 @@ export const demoPlugin = createChatChannelPlugin({ Only declare capabilities that the adapter really preserves. Every declared capability should have a contract test. -## Outbound Bridge +## Outbound bridge If the channel already has a compatible `outbound` adapter, prefer deriving the message adapter instead of duplicating send code: @@ -116,7 +114,7 @@ uses `manual` receive acknowledgement policy. That makes plugin-owned platform acknowledgement explicit without changing channels that acknowledge webhooks, sockets, or polling offsets outside generic receive context. -## Message Tool Sends +## Message tool sends The shared `message(action="send")` path should use the same core delivery lifecycle as final replies. If a channel needs provider-specific shaping for the @@ -167,7 +165,7 @@ keep the prepared send path best-effort; core will still try the write-ahead queue, but queue persistence or uncertain crash recovery is not part of the required delivery contract. -## Durable Final Capabilities +## Durable final capabilities Durable final delivery is opt in per side effect. Core will only use generic durable delivery when the adapter declares every capability needed by the @@ -217,7 +215,7 @@ const requiredCapabilities = deriveDurableFinalDeliveryRequirements({ `messageSendingHooks` is required by default. Set `messageSendingHooks: false` only for a path that intentionally cannot run global message-sending hooks. -## Durable Send Contract +## Durable send contract A durable final send has stricter semantics than legacy channel-owned delivery: @@ -266,7 +264,7 @@ becomes the final receipt. Avoid adding new owner-local `messageIds` fields. Legacy `ChannelDeliveryResult.messageIds` is still produced at compatibility edges. -## Live Preview +## Live preview Channels that stream draft previews or progress updates should declare live capabilities: @@ -300,7 +298,7 @@ finalizer decides whether the final reply edits the preview in place, sends a normal fallback, discards pending preview state, keeps an ambiguous failed edit without duplicating the message, and returns the final receipt. -## Receive Ack Policy +## Receive ack policy Inbound receivers that control platform acknowledgement timing should declare receive policy: @@ -344,7 +342,7 @@ Use `createMessageReceiveContext(...)` in receivers that defer ack state, and `shouldAckMessageAfterStage(...)` when the receiver needs to test whether a stage has satisfied the configured policy. -## Contract Tests +## Contract tests Capability declarations are part of the plugin contract. Back them with tests: @@ -387,7 +385,7 @@ Add live and receive proof suites when the adapter declares those features. A missing proof should fail the test rather than silently widening the durable surface. -## Deprecated Compatibility APIs +## Deprecated compatibility APIs These APIs remain importable for third-party compatibility. Do not use them for new channel code. @@ -409,7 +407,7 @@ Compatibility dispatchers can still use `createReplyPrefixContext(...)`, message facade. New lifecycle code should avoid the old `channel-reply-pipeline` subpath. -## Migration Checklist +## Migration checklist 1. Add `message: defineChannelMessageAdapter(...)` or `message: createChannelMessageAdapterFromOutbound(...)` to the channel plugin. diff --git a/docs/providers/deepinfra.md b/docs/providers/deepinfra.md index 391f6292b2a..66963a0a06e 100644 --- a/docs/providers/deepinfra.md +++ b/docs/providers/deepinfra.md @@ -3,10 +3,9 @@ summary: "Use DeepInfra's unified API to access the most popular open source and read_when: - You want a single API key for the top open source LLMs - You want to run models via DeepInfra's API in OpenClaw +title: "DeepInfra" --- -# DeepInfra - DeepInfra provides a **unified API** that routes requests to the most popular open source and frontier models behind a single endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL. @@ -81,3 +80,8 @@ deepinfra/zai-org/GLM-5.1 - Default model: `deepinfra/deepseek-ai/DeepSeek-V3.2` - Base URL: `https://api.deepinfra.com/v1/openai` - Native video generation uses `https://api.deepinfra.com/v1/inference/`. + +## Related + +- [Model providers](/concepts/model-providers) +- [All providers](/providers/index) diff --git a/docs/security/incident-response.md b/docs/security/incident-response.md index fedde0c2f15..d0b38e97085 100644 --- a/docs/security/incident-response.md +++ b/docs/security/incident-response.md @@ -7,8 +7,6 @@ read_when: - Reviewing post-incident follow-up expectations --- -# Incident Response - ## 1. Detection and triage We monitor security signals from: