Repository navigation
doc: add contract doc for rfc 1299 #1361
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next
Next commit
add contract doc
- Loading branch information
commit 68f9e7198e1dd05f43d711a7df5a11600556bc5e
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| --- | ||
| title: Host-visible diagnostics contract | ||
| description: Contract for the host-visible integration diagnostics RFC. | ||
| --- | ||
|
|
||
| # Host-visible diagnostics contract | ||
|
|
||
| This page records the contract introduced by the host-visible integration diagnostics RFC. It covers the diagnostic | ||
| slice only; shared service state, service lifecycle, installation, and platform adapter contracts belong to their | ||
| respective RFCs and implementation slices. | ||
|
|
||
| The contract currently applies to Codex, Claude Code, DeepSeek Harness (DSH), OpenClaw, Pi, and Hermes. Bub is out of | ||
| scope until it has a host channel, implementation, tests, and support qualification. | ||
|
|
||
| The words **MUST**, **SHOULD**, and **MAY** are normative requirements for plugin implementation and review. | ||
|
|
||
| This contract is derived from [RFC 1299: Local Server availability and service installation](../rfcs/1299_local_server_availability_and_service_installation.md). | ||
| The original [RFC PR #1299](https://github.com/oceanbase/powercontext/pull/1299) is tracked by [issue #1298](https://github.com/oceanbase/powercontext/issues/1298). | ||
|
|
||
| ## What a plugin must report | ||
|
|
||
| A plugin MUST report a PowerContext failure when a host-visible operation cannot complete because of one of the | ||
| classified backend failures. The operation may be context preparation, recall, capture, flush, a direct tool or slash | ||
| command, or a health/status check. | ||
|
|
||
| The plugin MUST use typed client errors to make the classification. It MUST NOT classify failures by matching text in | ||
| an exception message. | ||
|
|
||
| | Outcome | Classification | | ||
| | --- | --- | | ||
| | `authentication_failed` | HTTP 401. | | ||
| | `version_mismatch` | HTTP 404, normally an incompatible or missing endpoint. | | ||
| | `server_unavailable` | Connection failure, timeout, aborted request, or HTTP 503. | | ||
| | `invalid_response` | Other HTTP failures, malformed JSON, invalid response shape, or decoding/schema failures. | | ||
|
|
||
| An empty but valid result is not a failure diagnostic. In particular, an empty memory result MUST NOT be reported as | ||
| `server_unavailable`. | ||
|
|
||
| ## Diagnostic event format | ||
|
|
||
| Each diagnostic MUST be one JSON object written as one line through the host's supported channel: | ||
|
|
||
| ```json | ||
| { | ||
| "component": "powercontext.openclaw", | ||
| "event": "context_prepare", | ||
| "outcome": "server_unavailable", | ||
| "recovery": "powercontext doctor" | ||
| } | ||
| ``` | ||
|
|
||
| ### Fields | ||
|
|
||
| | Field | Requirement | | ||
| | --- | --- | | ||
| | `component` | Stable host-qualified name, such as `powercontext.dsh` or `powercontext.claude_code.recall`. | | ||
| | `event` | Short lower-snake-case event, such as `context_prepare`, `capture_source`, `tool_call`, or `status`. It MUST NOT contain a prompt, query, URL, or identifier. | | ||
| | `outcome` | One of the four outcomes defined above. | | ||
| | `http_status` | Optional integer for an HTTP response. It MUST NOT be fabricated for a transport failure. | | ||
| | `recovery` | MUST equal `powercontext doctor` for `server_unavailable`; normally omitted for other outcomes. | | ||
|
|
||
| Additional fields MAY be included only when they are bounded, non-sensitive, and useful to interpret the lifecycle | ||
| event. For example, a numeric `content_bytes` or a bounded `context_status` is acceptable. | ||
|
|
||
| ### Examples | ||
|
|
||
| ```json | ||
| {"component":"powercontext.codex.recall","event":"context_prepare","outcome":"authentication_failed","http_status":401} | ||
| {"component":"powercontext.pi","event":"context_prepare","outcome":"version_mismatch","http_status":404} | ||
| {"component":"powercontext.hermes","event":"tool_call","outcome":"server_unavailable","recovery":"powercontext doctor"} | ||
| {"component":"powercontext.dsh","event":"capture_source","outcome":"invalid_response","http_status":500} | ||
| ``` | ||
|
|
||
| ## Host presentation contract | ||
|
|
||
| Each plugin MUST use the native host channel. Diagnostics MUST NOT be inserted into model content, recalled context, | ||
| or a successful tool result. | ||
|
|
||
| | Host | Channel | Component prefix | | ||
| | --- | --- | --- | | ||
| | Codex | Hook `stderr` | `powercontext.codex.recall` | | ||
| | Claude Code | Hook `stderr` | `powercontext.claude_code.recall` | | ||
|
This conversation was marked as resolved.
Resolved
|
||
| | DSH | Host logger warning | `powercontext.dsh` | | ||
| | OpenClaw | Plugin API logger warning | `powercontext.openclaw` | | ||
| | Pi | Host terminal warning (`console.warn`) | `powercontext.pi` | | ||
| | Hermes | Plugin logger warning | `powercontext.hermes` | | ||
|
|
||
| The host-facing operation result MAY remain a generic error such as `PowerContext operation failed`. The structured | ||
| diagnostic is the recovery signal; the generic result is only for host/model control flow. | ||
|
|
||
| ## Fail-open, privacy, and presentation bounds | ||
|
|
||
| When a PowerContext operation fails: | ||
|
|
||
| - recall/context preparation MUST return no recalled context rather than partial or fabricated context; | ||
| - capture and flush MUST not terminate or block the host session indefinitely; | ||
| - direct tools and commands MUST return a generic failure result without exposing request details; | ||
| - diagnostic emission itself MUST be best effort and MUST NOT turn a backend failure into a host failure. | ||
|
|
||
| Diagnostics MUST NOT contain endpoint URLs, authorization headers, tokens, cookies, filesystem paths, prompts, queries, | ||
| captured text, recalled text, response bodies, or stack traces. | ||
|
|
||
| Repeated failures MUST have bounded presentation. Long-lived plugins SHOULD deduplicate by `outcome` for 60 seconds. | ||
| Short-lived hooks MAY deduplicate within one invocation, but MUST NOT emit an unbounded stream for one failure. The | ||
|
This conversation was marked as resolved.
Resolved
|
||
| deduplication key is the outcome, not user input or the request payload. | ||
|
|
||
| ## Plugin implementation conventions for this RFC | ||
|
|
||
| Every plugin implementation in this RFC MUST: | ||
|
|
||
| 1. Reuse the shared client error types and the outcome mapping above. | ||
| 2. Attach diagnostics to every relevant failure exit, including lifecycle callbacks and direct tool/command paths. | ||
| 3. Use a stable component and event name; never put user or request data in either field. | ||
| 4. Keep the diagnostic formatter independent from model-facing content formatting. | ||
| 5. Preserve the host's normal behavior when PowerContext is unavailable. | ||
| 6. Add or update documentation and tests in the same implementation slice. | ||
|
|
||
| The plugin MAY choose its language and internal helper shape. It MUST preserve the observable JSON contract and the | ||
| host channel listed above. | ||
|
|
||
| ## Required test matrix | ||
|
|
||
| Each plugin PR that implements this RFC MUST test the following observable behavior: | ||
|
|
||
| 1. Transport failure or timeout produces `server_unavailable` and `powercontext doctor`. | ||
| 2. HTTP 503 produces `server_unavailable` with `http_status: 503`. | ||
| 3. HTTP 401 produces `authentication_failed`. | ||
| 4. HTTP 404 produces `version_mismatch`. | ||
| 5. Other HTTP failures and malformed responses produce `invalid_response`. | ||
| 6. Repeated failures are deduplicated within the documented bound. | ||
| 7. Recall, capture, flush, direct tool, slash command, and status paths remain fail-open where the host exposes them. | ||
| 8. The diagnostic contains no URL, token, prompt, query, response body, or stack trace. | ||
| 9. The matching host runner, type checker, or smoke test passes. | ||
|
|
||
| Tests SHOULD assert the parsed event and the host-visible channel. They SHOULD NOT freeze private call order or | ||
| internal helper names. | ||
|
|
||
| ## Out of scope | ||
|
|
||
| This contract does not define: | ||
|
|
||
| - shared service state or native service lifecycle; | ||
| - service installation, ownership, restart policy, or platform support qualification; | ||
| - a common UI for every host; | ||
| - the Bub integration. | ||
|
|
||
| Those decisions require their own implementation evidence and review boundary. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,135 @@ | ||
| --- | ||
| title: 宿主可见诊断契约 | ||
| description: 宿主可见集成诊断 RFC 的契约。 | ||
| --- | ||
|
|
||
| # 宿主可见诊断契约 | ||
|
|
||
| 本文记录 Host-visible integration diagnostics RFC 引入的契约,只覆盖本次诊断切片。共享 service state、service lifecycle、安装方式和平台 adapter | ||
| 契约属于各自的 RFC 与实现切片,不在本文定义。 | ||
|
|
||
| 当前契约适用于 Codex、Claude Code、DeepSeek Harness(DSH)、OpenClaw、Pi 和 Hermes。Bub 尚未具备宿主通道、实现、测试和支持资格,暂不在范围内。 | ||
|
|
||
| 文中的“必须(MUST)”“应该(SHOULD)”和“可以(MAY)”是插件实现与评审的规范性要求。 | ||
|
|
||
| 本契约来源于 [RFC 1299:Local Server availability and service installation](../rfcs/1299_local_server_availability_and_service_installation.md)。 | ||
| 原始 [RFC PR #1299](https://github.com/oceanbase/powercontext/pull/1299) 对应的跟踪 issue 是 [#1298](https://github.com/oceanbase/powercontext/issues/1298)。 | ||
|
|
||
| ## 插件必须报告什么 | ||
|
|
||
| 当宿主可见操作因为下列已分类的 backend failure 无法完成时,插件必须报告 PowerContext failure。适用操作包括 context preparation、recall、capture、flush、 | ||
| direct tool、slash command 以及 health/status check。 | ||
|
|
||
| 插件必须使用 typed client error 进行分类,不能通过匹配 exception message 文本来分类。 | ||
|
|
||
| | Outcome | 分类规则 | | ||
| | --- | --- | | ||
| | `authentication_failed` | HTTP 401。 | | ||
| | `version_mismatch` | HTTP 404,通常表示 endpoint 不兼容或不存在。 | | ||
| | `server_unavailable` | 连接失败、超时、请求中止或 HTTP 503。 | | ||
| | `invalid_response` | 其他 HTTP failure、JSON 损坏、响应结构错误或解码/schema failure。 | | ||
|
|
||
| 合法但为空的结果不是失败诊断。尤其是空的 memory 结果不能报告为 `server_unavailable`。 | ||
|
|
||
| ## 诊断事件格式 | ||
|
|
||
| 每条诊断必须通过宿主支持的通道写出一个单行 JSON object: | ||
|
|
||
| ```json | ||
| { | ||
| "component": "powercontext.openclaw", | ||
| "event": "context_prepare", | ||
| "outcome": "server_unavailable", | ||
| "recovery": "powercontext doctor" | ||
| } | ||
| ``` | ||
|
|
||
| ### 字段 | ||
|
|
||
| | 字段 | 要求 | | ||
| | --- | --- | | ||
| | `component` | 稳定且包含宿主名称,例如 `powercontext.dsh` 或 `powercontext.claude_code.recall`。 | | ||
| | `event` | 简短的 lower-snake-case 事件,例如 `context_prepare`、`capture_source`、`tool_call` 或 `status`。不能包含 prompt、query、URL 或 identifier。 | | ||
| | `outcome` | 必须是上面定义的四种 outcome 之一。 | | ||
| | `http_status` | HTTP 响应可以携带的整数。传输失败不能伪造该字段。 | | ||
| | `recovery` | `server_unavailable` 时必须为 `powercontext doctor`;其他 outcome 通常省略。 | | ||
|
|
||
| 可以增加 bounded、非敏感且有助于解释生命周期事件的字段,例如数字类型的 `content_bytes` 或受限的 `context_status`。 | ||
|
|
||
| ### 示例 | ||
|
|
||
| ```json | ||
| {"component":"powercontext.codex.recall","event":"context_prepare","outcome":"authentication_failed","http_status":401} | ||
| {"component":"powercontext.pi","event":"context_prepare","outcome":"version_mismatch","http_status":404} | ||
| {"component":"powercontext.hermes","event":"tool_call","outcome":"server_unavailable","recovery":"powercontext doctor"} | ||
| {"component":"powercontext.dsh","event":"capture_source","outcome":"invalid_response","http_status":500} | ||
| ``` | ||
|
|
||
| ## 宿主展示契约 | ||
|
|
||
| 每个插件必须使用宿主原生通道。诊断不能插入 model content、recalled context 或成功的 tool result。 | ||
|
|
||
| | 宿主 | 通道 | Component 前缀 | | ||
| | --- | --- | --- | | ||
| | Codex | Hook `stderr` | `powercontext.codex.recall` | | ||
| | Claude Code | Hook `stderr` | `powercontext.claude_code.recall` | | ||
| | DSH | 宿主 logger warning | `powercontext.dsh` | | ||
| | OpenClaw | Plugin API logger warning | `powercontext.openclaw` | | ||
| | Pi | 宿主终端 warning(`console.warn`) | `powercontext.pi` | | ||
| | Hermes | Plugin logger warning | `powercontext.hermes` | | ||
|
|
||
| 宿主侧 operation result 可以继续返回 `PowerContext operation failed` 这类通用错误。结构化诊断是恢复信号,通用错误只服务于 host/model 控制流。 | ||
|
|
||
| ## Fail-open、隐私和展示边界 | ||
|
|
||
| PowerContext operation 失败时: | ||
|
|
||
| - recall/context preparation 必须返回空的 recalled context,不能返回 partial 或伪造的 context; | ||
| - capture 和 flush 不能终止宿主 session,也不能无限期阻塞宿主; | ||
| - direct tool 和 command 必须返回不包含请求细节的通用 failure result; | ||
| - 诊断发送本身必须是 best effort,日志失败不能把 backend failure 变成宿主 failure。 | ||
|
|
||
| 诊断不能包含 endpoint URL、authorization header、token、cookie、filesystem path、prompt、query、capture text、recall text、response body 或 stack trace。 | ||
|
|
||
| 重复失败必须有展示边界。长生命周期插件应该按 `outcome` 去重 60 秒。短生命周期 hook 可以在一次 invocation 内去重,但不能为一个失败无限输出诊断。 | ||
| 去重 key 是 outcome,不能使用 user input 或 request payload。 | ||
|
|
||
| ## 本 RFC 的插件实现约定 | ||
|
|
||
| 本 RFC 中的每个插件实现都必须: | ||
|
|
||
| 1. 复用 shared client 的 typed error 和上面的 outcome mapping。 | ||
| 2. 在所有相关 failure exit 接入诊断,包括 lifecycle callback 和 direct tool/command path。 | ||
| 3. 使用稳定的 component 和 event name;不能把用户数据或请求数据放进字段。 | ||
| 4. 让 diagnostic formatter 与 model-facing content formatter 解耦。 | ||
| 5. PowerContext 不可用时保持宿主的正常行为。 | ||
| 6. 在同一个 implementation slice 中同步更新文档和测试。 | ||
|
|
||
| 插件可以选择语言和内部 helper 结构,但必须保持可观察的 JSON 契约和上表中的宿主通道。 | ||
|
|
||
| ## 必须覆盖的测试矩阵 | ||
|
|
||
| 实现本 RFC 的每个插件 PR 都必须测试以下可观察行为: | ||
|
|
||
| 1. 传输失败或超时产生 `server_unavailable` 和 `powercontext doctor`。 | ||
| 2. HTTP 503 产生带有 `http_status: 503` 的 `server_unavailable`。 | ||
| 3. HTTP 401 产生 `authentication_failed`。 | ||
| 4. HTTP 404 产生 `version_mismatch`。 | ||
| 5. 其他 HTTP failure 和 malformed response 产生 `invalid_response`。 | ||
| 6. 重复失败在约定边界内去重。 | ||
| 7. 在宿主提供这些入口时,recall、capture、flush、direct tool、slash command 和 status path 都保持 fail-open。 | ||
| 8. 诊断不包含 URL、token、prompt、query、response body 或 stack trace。 | ||
| 9. 对应的宿主 runner、type checker 或 smoke test 通过。 | ||
|
|
||
| 测试应该断言解析后的 event 和宿主可见通道,不应该冻结 private call order 或内部 helper name。 | ||
|
|
||
| ## 不在范围内 | ||
|
|
||
| 本文不定义: | ||
|
|
||
| - shared service state 或 native service lifecycle; | ||
| - service 安装、ownership、restart policy 或平台支持资格; | ||
| - 所有宿主共用的 UI; | ||
| - Bub 集成。 | ||
|
|
||
| 这些决定需要独立的实现证据和评审边界。 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
fixed