dsh-codex-community 0.0.1

package/dist/internal/session-preference-command.mjs

@@ -0,0 +1,52 @@
+const USAGE = "用法：/codex [status|reset|set fast on|off|set transport auto|sse|websocket|websocket-cached] / Usage: /codex [status|reset|set fast on|off|set transport auto|sse|websocket|websocket-cached]"
+const TRANSPORTS = new Set(["auto", "sse", "websocket", "websocket-cached"])
+
+/** Register the TUI/Web command surface for process-local session preferences. */
+export function registerCodexSessionCommand(ctx, preferences, options = {}) {
+  const resetSession = options.resetSession ?? (() => undefined)
+  if (typeof resetSession !== "function") throw new TypeError("resetSession must be a function")
+  return ctx.commands.register({
+    name: "codex",
+    description: "管理当前会话的 Codex 请求偏好 / Manage Codex request preferences for this session",
+    input: { hint: "[status|reset|set fast on|off|set transport auto|sse|websocket|websocket-cached]" },
+    recordInput: false,
+    handler: async ({ rawInput, agent }) => {
+      const parts = String(rawInput).trim().split(/\s+/u).filter(Boolean)
+      const action = parts.length === 0 ? ["status"] : parts
+      try {
+        if (action.length === 1 && action[0] === "status") {
+          return success(preferences.resolve(String(agent.id)))
+        }
+        if (action.length === 1 && action[0] === "reset") {
+          const sessionId = String(agent.id)
+          preferences.remove(sessionId)
+          resetSession(sessionId)
+          return success(preferences.resolve(sessionId), "已重置当前会话。 / Session preferences reset. ")
+        }
+        if (action.length === 3 && action[0] === "set" && action[1] === "fast") {
+          if (action[2] !== "on" && action[2] !== "off") return { kind: "error", text: USAGE }
+          return success(preferences.configure(String(agent.id), { fast: action[2] === "on" }))
+        }
+        if (action.length === 3 && action[0] === "set" && action[1] === "transport") {
+          if (!TRANSPORTS.has(action[2])) return { kind: "error", text: USAGE }
+          return success(preferences.configure(String(agent.id), { transport: action[2] }))
+        }
+        return { kind: "error", text: USAGE }
+      } catch {
+        return {
+          kind: "error",
+          text: "Codex 会话偏好暂时不可用。 / Codex session preferences are temporarily unavailable.",
+        }
+      }
+    },
+  })
+}
+
+function success(snapshot, prefix = "") {
+  const fast = snapshot.fast ? "on" : "off"
+  const fastZh = snapshot.fast ? "开启" : "关闭"
+  return {
+    kind: "success",
+    text: `${prefix}Fast: ${fast} · Transport: ${snapshot.transport} / Fast：${fastZh} · 传输：${snapshot.transport}`,
+  }
+}

package/dist/internal/session-preferences.mjs

@@ -0,0 +1,93 @@
+const MAX_SESSION_ID_CHARS = 256
+const DEFAULT_MAX_SESSIONS = 512
+const MAX_MAX_SESSIONS = 4_096
+const TRANSPORTS = new Set(["auto", "sse", "websocket", "websocket-cached"])
+const PREFERENCE_KEYS = new Set(["fast", "transport"])
+
+const SAFE_DEFAULTS = Object.freeze({ fast: false, transport: "auto" })
+
+/**
+ * Process-local, per-session request preferences.
+ *
+ * Callers see one immutable snapshot and never learn how entries are bounded or
+ * merged. The provider may resolve with no session id for direct/diagnostic
+ * calls; those always use safe defaults. Lifecycle owners remove an entry when
+ * its agent is disposed.
+ */
+export function createSessionPreferences(options = {}) {
+  const input = plainObject(options, "options")
+  assertOnlyKeys(input, ["defaultFast", "defaultTransport", "maxSessions"], "option")
+  const maxSessions = input.maxSessions ?? DEFAULT_MAX_SESSIONS
+  if (!Number.isSafeInteger(maxSessions) || maxSessions < 1 || maxSessions > MAX_MAX_SESSIONS) {
+    throw new TypeError(`maxSessions must be an integer from 1 to ${MAX_MAX_SESSIONS}`)
+  }
+  const defaults = snapshot({
+    fast: input.defaultFast ?? SAFE_DEFAULTS.fast,
+    transport: input.defaultTransport ?? SAFE_DEFAULTS.transport,
+  })
+  const entries = new Map()
+  let disposed = false
+
+  return Object.freeze({
+    resolve(sessionId) {
+      if (disposed || sessionId === undefined) return defaults
+      return entries.get(validSessionId(sessionId)) ?? defaults
+    },
+
+    configure(sessionId, patch) {
+      if (disposed) throw new Error("session preferences are disposed")
+      const id = validSessionId(sessionId)
+      const change = plainObject(patch, "preference patch")
+      const keys = Object.keys(change)
+      if (keys.length === 0 || keys.some((key) => !PREFERENCE_KEYS.has(key))) {
+        throw new TypeError("preference patch must set only fast and/or transport")
+      }
+      if (!entries.has(id) && entries.size >= maxSessions) {
+        throw new Error("session preference capacity reached")
+      }
+      const next = snapshot({ ...(entries.get(id) ?? defaults), ...change })
+      entries.set(id, next)
+      return next
+    },
+
+    remove(sessionId) {
+      if (disposed) return false
+      return entries.delete(validSessionId(sessionId))
+    },
+
+    dispose() {
+      if (disposed) return
+      disposed = true
+      entries.clear()
+    },
+  })
+}
+
+function snapshot(value) {
+  if (typeof value.fast !== "boolean") throw new TypeError("fast must be a boolean")
+  if (!TRANSPORTS.has(value.transport)) {
+    throw new TypeError("transport must be auto, sse, websocket, or websocket-cached")
+  }
+  return Object.freeze({ fast: value.fast, transport: value.transport })
+}
+
+function validSessionId(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_SESSION_ID_CHARS) {
+    throw new TypeError(`session id must contain 1 to ${MAX_SESSION_ID_CHARS} characters`)
+  }
+  return value
+}
+
+function plainObject(value, label) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`)
+  }
+  return value
+}
+
+function assertOnlyKeys(value, allowed, label) {
+  const accepted = new Set(allowed)
+  if (Object.keys(value).some((key) => !accepted.has(key))) {
+    throw new TypeError(`unknown ${label}`)
+  }
+}

package/dist/internal/stream-resilience.mjs

@@ -0,0 +1,273 @@
+import { normalizeCodexFailure } from "./failure-normalizer.mjs"
+import { CODEX_ROUTE_ID } from "./codex-identifiers.mjs"
+
+const PARTIAL_RECOVERABLE_CODES = new Set([
+  "QUOTA",
+  "RATE_LIMIT",
+  "SERVER",
+  "TIMEOUT",
+  "TRANSPORT",
+  "EMPTY_RESPONSE",
+  "QUOTA_OR_RATE_LIMIT",
+])
+
+const SUCCESSFUL_FINISH_KINDS = new Set(["stop", "tool-calls", "max-tokens"])
+
+const DIRECTLY_HANDLED_FAILURE_KINDS = new Set([
+  "account-quota",
+  "ambiguous-limit",
+  "transport",
+])
+
+function createTracker() {
+  return {
+    blocks: new Map(),
+    indexes: new Set(),
+    hasVisibleText: false,
+    hasToolCall: false,
+  }
+}
+
+function rememberChunk(tracker, chunk) {
+  if ("index" in chunk && Number.isSafeInteger(chunk.index)) tracker.indexes.add(chunk.index)
+  switch (chunk.type) {
+    case "block-start":
+      tracker.blocks.set(chunk.index, {
+        type: chunk.blockType,
+        text: "",
+        open: true,
+      })
+      if (chunk.blockType === "tool-call") tracker.hasToolCall = true
+      break
+    case "text-delta": {
+      const block = tracker.blocks.get(chunk.index)
+      if (block?.type === "text") block.text += chunk.text
+      if (chunk.text.length > 0) tracker.hasVisibleText = true
+      break
+    }
+    case "reasoning-delta": {
+      const block = tracker.blocks.get(chunk.index)
+      if (block?.type === "reasoning") block.text += chunk.text
+      break
+    }
+    case "tool-call-delta":
+      tracker.hasToolCall = true
+      break
+    case "block-end": {
+      const block = tracker.blocks.get(chunk.index)
+      if (block !== undefined) {
+        block.open = false
+        if (chunk.block.type === "text") {
+          block.text = chunk.block.text
+          if (chunk.block.text.length > 0) tracker.hasVisibleText = true
+        }
+      }
+      if (chunk.block.type === "tool-call") tracker.hasToolCall = true
+      break
+    }
+  }
+}
+
+function safeToRecover(tracker) {
+  if (!tracker.hasVisibleText || tracker.hasToolCall) return false
+  for (const block of tracker.blocks.values()) {
+    if (!block.open) continue
+    if (block.type !== "text" && block.type !== "reasoning") return false
+  }
+  return true
+}
+
+function nextIndex(tracker) {
+  if (tracker.indexes.size === 0) return 0
+  const index = Math.max(...tracker.indexes) + 1
+  if (!Number.isSafeInteger(index)) throw new RangeError("no safe block index remains for recovery notice")
+  return index
+}
+
+function closeOpenTextBlocks(tracker) {
+  const chunks = []
+  for (const [index, block] of tracker.blocks) {
+    if (!block.open) continue
+    chunks.push({
+      type: "block-end",
+      index,
+      block: { type: block.type, text: block.text },
+    })
+    block.open = false
+  }
+  return chunks
+}
+
+function recoveryNotice(normalized) {
+  if (normalized.failure.code === "QUOTA") {
+    return `⚠️ ${normalized.failure.message} 已保存上方未完成回复。 / The partial response above was preserved.`
+  }
+  return "⚠️ 回复流在完成前中断。为避免重复输出或工具副作用，本插件没有重放整次请求，并已保存上方内容；请发送“继续”。 / The response stream was interrupted. The full request was not replayed; send “continue” to resume."
+}
+
+function recoveredChunks(tracker, normalized) {
+  const chunks = closeOpenTextBlocks(tracker)
+  const index = nextIndex(tracker)
+  const text = recoveryNotice(normalized)
+  chunks.push(
+    { type: "block-start", index, blockType: "text" },
+    { type: "text-delta", index, text },
+    { type: "block-end", index, block: { type: "text", text } },
+  )
+  return chunks
+}
+
+function partialFailure(failure) {
+  return Object.freeze({
+    message: "Codex 在产生部分输出后失败；已禁用整次请求重放，以避免重复输出或工具副作用。 / Codex failed after partial output; full-request replay was disabled to prevent duplicate output or tool side effects.",
+    code: "PARTIAL_RESPONSE",
+  })
+}
+
+function prematureEndFailure() {
+  return Object.freeze({
+    message: "Codex stream ended before a terminal finish chunk",
+    code: "TRANSPORT",
+  })
+}
+
+function* finishWithFailure({
+  tracker,
+  chunk,
+  pendingUsage,
+  options,
+  config,
+  partialResponseRecovery,
+}) {
+  const normalized = normalizeCodexFailure(chunk.reason.failure)
+  const failure = normalized.failure
+  if (failure.code === "QUOTA") {
+    notify(config.onQuota, {
+      provider: options.provider,
+      model: options.model,
+      ...(normalized.facts.reset?.epochMs === undefined
+        ? {}
+        : { resetAt: normalized.facts.reset.epochMs }),
+    })
+  }
+  const canRecover = partialResponseRecovery
+    && PARTIAL_RECOVERABLE_CODES.has(failure.code)
+    && safeToRecover(tracker)
+
+  if (canRecover) {
+    yield* recoveredChunks(tracker, normalized)
+    if (pendingUsage !== undefined) yield pendingUsage
+    notify(config.onRecovery, {
+      provider: options.provider,
+      model: options.model,
+      code: failure.code,
+      requestId: failure.requestId,
+    })
+    yield { type: "finish", reason: { kind: "stop" } }
+    return
+  }
+
+  if (pendingUsage !== undefined) yield pendingUsage
+  const finalFailure = failure.code !== "QUOTA"
+    && (tracker.hasVisibleText || tracker.hasToolCall)
+    && PARTIAL_RECOVERABLE_CODES.has(failure.code)
+    ? partialFailure(failure)
+    : failure
+  yield {
+    ...chunk,
+    reason: { kind: "error", failure: finalFailure },
+  }
+}
+
+function notify(callback, detail) {
+  if (typeof callback !== "function") return
+  try {
+    callback(Object.freeze(detail))
+  } catch {
+    // Observation hooks must never turn a completed provider stream into a failure.
+  }
+}
+
+/**
+ * Stabilize one Codex stream without replaying a request that already emitted
+ * content. Safe text is closed and persisted; tool-bearing streams fail closed.
+ */
+export async function* stabilizeCodexStream(options, next, config = {}) {
+  if (options?.provider !== CODEX_ROUTE_ID) {
+    yield* next()
+    return
+  }
+
+  const tracker = createTracker()
+  const partialResponseRecovery = config.partialResponseRecovery !== false
+  let pendingUsage
+
+  try {
+    for await (const chunk of next()) {
+      if (chunk.type === "usage") {
+        if (pendingUsage !== undefined) yield pendingUsage
+        pendingUsage = chunk
+        continue
+      }
+
+      if (chunk.type !== "finish") {
+        if (pendingUsage !== undefined) {
+          yield pendingUsage
+          pendingUsage = undefined
+        }
+        rememberChunk(tracker, chunk)
+        yield chunk
+        continue
+      }
+
+      if (chunk.reason.kind !== "error") {
+        if (pendingUsage !== undefined) yield pendingUsage
+        if (SUCCESSFUL_FINISH_KINDS.has(chunk.reason.kind)) {
+          notify(config.onSuccess, {
+            provider: options.provider,
+            model: options.model,
+          })
+        }
+        yield chunk
+        return
+      }
+
+      yield* finishWithFailure({
+        tracker,
+        chunk,
+        pendingUsage,
+        options,
+        config,
+        partialResponseRecovery,
+      })
+      return
+    }
+  } catch (failure) {
+    const normalized = normalizeCodexFailure(failure)
+    if (!DIRECTLY_HANDLED_FAILURE_KINDS.has(normalized.facts.kind)) throw failure
+    yield* finishWithFailure({
+      tracker,
+      chunk: {
+        type: "finish",
+        reason: { kind: "error", failure },
+      },
+      pendingUsage,
+      options,
+      config,
+      partialResponseRecovery,
+    })
+    return
+  }
+
+  yield* finishWithFailure({
+    tracker,
+    chunk: {
+      type: "finish",
+      reason: { kind: "error", failure: prematureEndFailure() },
+    },
+    pendingUsage,
+    options,
+    config,
+    partialResponseRecovery,
+  })
+}

package/docs/README.en.md

@@ -0,0 +1,15 @@
+# Documentation index
+
+[简体中文](README.md) | [English](README.en.md)
+
+- [Architecture and module boundaries](architecture.en.md)
+- [Configuration reference](configuration.en.md)
+- [Compatibility and acceptance status](compatibility.en.md)
+- [Troubleshooting](troubleshooting.en.md)
+- [Contribution and licensing rules](contribution-sources.en.md)
+- [Testing strategy](testing.en.md)
+- [Release process](releasing.en.md)
+- [GitHub About and topics](github-about.md)
+- [v0.0.1 Release copy](releases/v0.0.1.md)
+
+Every “verified” claim must point to repository tests, CI, or release-artifact evidence. “Wired” and “planned” must not be presented as “supported.”

package/docs/README.md

@@ -0,0 +1,15 @@
+# 文档索引
+
+[简体中文](README.md) | [English](README.en.md)
+
+- [架构与模块边界](architecture.md)
+- [配置参考](configuration.md)
+- [兼容性与验收状态](compatibility.md)
+- [故障排查](troubleshooting.md)
+- [贡献与许可规范](contribution-sources.md)
+- [测试策略](testing.md)
+- [发布流程](releasing.md)
+- [GitHub About 与 Topics](github-about.md)
+- [v0.0.1 Release 文案](releases/v0.0.1.md)
+
+文档中的“已验证”必须能指向仓库内测试、CI 或发布产物证据；“已接线”和“计划中”不能写成“已支持”。

package/docs/architecture.en.md

@@ -0,0 +1,106 @@
+# Architecture
+
+[简体中文](architecture.md) | [English](architecture.en.md)
+
+## Responsibilities
+
+This plugin registers the Codex route, settings namespace, OAuth flow, session preferences, and reliability policy. Message conversion, model protocols, tool permissions, session persistence, and OAuth protocol behavior use public interfaces from DSH, `@deepseek-ai/dsh-llm-pi-ai`, and pi-ai.
+
+```text
+DSH Web settings ── loopback RPC ── AuthorizationBridge
+                                           │
+                              dsh-codex/openai-codex
+                                           │
+                              CodexCredentialStore
+                                           │
+                                  ChatGPT OAuth grant
+
+Harness Agent Loop
+        │
+        ├── SessionPreferences ── Fast / transport
+        │
+        ▼
+StreamResilience ── CodexRouteAdapter (`dsh-codex`)
+                              │
+                              ▼
+                PiAiAdapter (`openai-codex`) ── CodexPiProvider
+        ▲
+        └── attachment service ── ImagePolicy
+```
+
+## ProviderRuntime
+
+`ProviderRuntime` creates the `dsh-codex` route and OAuth flow under the `dsh-codex` settings namespace. The outer `CodexRouteAdapter` maps the DSH route to PiAiAdapter's internal canonical `openai-codex` provider, then restores the external route at provider-info, model, stream-history-source, and error boundaries. This preserves pi-ai semantics for response IDs, reasoning signatures, tool-call IDs, and replay envelopes.
+
+Each operation obtains an immutable profile from current settings. A concurrent settings update cannot alter an operation already in progress; the next operation receives the new configuration while the outer adapter instance remains stable.
+
+The model catalog comes from the installed pi-ai version. Model selection, image budgets, cache policy, timeout, and bounded retry are resolved once at the profile boundary. Unknown or duplicate model selections fail before network I/O; an absent `models` value advertises the complete catalog, while an explicit empty array advertises none.
+
+## CodexCredentialStore
+
+The credential record key is `dsh-codex/openai-codex`. The adapter reads and modifies only that record and accepts OAuth grants only. API keys, records belonging to another provider, and structurally invalid data fail closed. Writes and deletion use the DSH credentials service's serialized interfaces: a deletion that acquires the lock first prevents refresh from starting, while a refresh already holding the lock completes before deletion becomes the final state. Credentials therefore cannot be resurrected after sign-out.
+
+The Web settings page receives only sign-in methods, sanitized notices, an authorization-page URL, a verification code, and completion state. Access tokens, refresh tokens, complete grants, and complete provider errors do not cross the loopback RPC or enter command output.
+
+## AuthorizationBridge
+
+The Host starts, cancels, and observes sign-in through the DSH authorization service. It uses the credentials service to inspect configured-state metadata or sign out. The RPC bounds concurrent attempts, long-poll waiters, event counts, string lengths, and accepted URLs. After login returns, the plugin checks cancellation again while the credentials service holds the serialized write lock for this record. That mutate callback is the cancellation linearization point: cancellation before it selects the grant prevents the write; after selection the write completes, and the plugin does not issue a compensating delete that could erase a newer sign-in already queued by another DSH process. A generation tracker that contains no credential material holds the commit phase through the matching `authorization/settled` event. The settings page and `/codex-login cancel` reject a post-linearization cancel in the same synchronous call stack and keep observing the final `authorized` state. Sign-out bypasses that barrier, aborts active attempts, and then explicitly deletes the credential through the same serialized record path, so an older in-progress write cannot resurrect the credential after sign-out completes. A completed attempt ID retained briefly for status retrieval cannot cancel a newer sign-in.
+
+`/codex-login status|cancel|logout` uses the same boundary and prevents command input from entering conversation history.
+
+## SessionPreferences
+
+`/codex` changes only the session that receives the command:
+
+- `fast on|off` controls whether the priority service tier is requested and defaults to off;
+- `transport` accepts `auto`, `sse`, `websocket`, or `websocket-cached` and defaults to `auto`;
+- `reset` restores that session's defaults.
+
+Preferences live in a capacity-bounded in-memory table that returns immutable snapshots; they do not change global provider settings. A failed Fast request is not replayed automatically on another service tier, avoiding duplicate tool side effects. Real account entitlement for this tier must be confirmed by release acceptance.
+
+The raw DSH session ID is used only for preference lookup and message/replay provenance. The transport/cache session ID passed to pi-ai is namespaced with `dsh-codex:`. `/codex reset`, `agent/disposed`, and runtime disposal use pi-ai's public exact-session APIs to clear only this plugin's WebSocket connection, fallback, and debug state. They never invoke no-argument global cleanup and do not affect sessions owned by another in-process pi-ai consumer. The namespace enters only pi-ai stream options; it does not rewrite history messages or replay envelopes.
+
+## ModelEnablement
+
+This plugin's settings page uses `llm.discoverModels` to display requestable models from the current pi-ai catalog and stores its selection under the `dsh-codex` settings namespace. The runtime registers only a direct discovery handler for that namespace, not a general configurable-provider directory, avoiding interference with DSH's general model editor.
+
+The settings page requires at least one selected model. Selecting all removes the `models` override only when entries have no custom fields, allowing the directory to follow pi-ai version updates. Partial selections, extra fields, and custom parameters retain explicit configuration. Catalog filtering affects discovery only; exact hidden models remain resolvable, so older sessions are not invalidated merely because a model is hidden.
+
+## ImagePolicy
+
+Optional settings resolve to one immutable policy with no optional numeric fields. The attachment contract receives only `{ maxPixels, maxBytes }`. Zero, negative, fractional, `NaN`, and unsafe integers fail at the configuration boundary.
+
+Remote images extend the existing `read_image` tool through a `tools/execute` middleware. Local paths delegate unchanged. HTTP(S) URLs pass public-DNS validation, address pinning, per-hop redirect checks, one total timeout, a MIME allowlist, and byte limits both before and after decompression. Accepted content is committed to the DSH attachment store before the middleware returns the original tool's output schema.
+
+Each plugin instance runs at most two remote-image jobs and queues at most 32; a full queue returns `TOO_MANY_REQUESTS`. Cancellation while queued removes the job, and cancellation during download aborts network work. Plugin disposal first closes the limiter, atomically rejects every queued job, and aborts active model-resolution or network work through a separate lifetime signal; Context cleanup waits for jobs that already entered `saveImage` to settle. The current public DSH `saveImage` interface has no `AbortSignal` or rollback contract, so cancellation after persistence begins guarantees only that success is not returned to the caller; it cannot guarantee deletion of an attachment that may already have been stored. The execution slot also remains occupied until `saveImage` settles. The bounded queue and lifecycle closure prevent new post-disposal work and unbounded memory growth.
+
+## FailureNormalizer and QuotaObserver
+
+`FailureNormalizer` converts a DSH `LlmFailure`, including embedded structured JSON, into a stable classification. Only verifiable structured `code`/`type` values such as `AccountQuotaExceeded` or `insufficient_quota`, or narrowly scoped account-level text confirming exhausted usage, become `QUOTA`; an ordinary 429 remains `RATE_LIMIT`. Multiple embedded JSON objects retain independent provenance: reset, request ID, and status may come only from the failure's top level or one `error` envelope that independently proves quota, never by combining envelopes. pi-ai `0.82.1` collapses distinct 429 responses into one ChatGPT usage-limit message and no longer exposes the original code/body. That evidence-free result becomes non-retryable `QUOTA_OR_RATE_LIMIT` instead of being mislabeled as confirmed account quota.
+
+`QUOTA`, `QUOTA_OR_RATE_LIMIT`, and confirmed transport failures are rebuilt as minimal failures containing a fixed sanitized message, code, and optional valid HTTP status/safe-character request ID. Arbitrary provider fields and WebSocket close reasons are never reflected. `QUOTA_OR_RATE_LIMIT` is not written to `QuotaObserver`: it fails without retry when no partial output exists and only preserves already safe plain text when partial output exists.
+
+`QuotaObserver` records only successful completion, `QUOTA`, and a reset timestamp accepted by strict format and bounded-horizon checks. Snapshots have three states: `unknown`, `recent-success`, and `exhausted`. It does not poll an account, display a balance or percentage, or call undocumented plan-quota endpoints.
+
+## StreamResilience
+
+This module runs on the `llm/stream` waterfall:
+
+1. forward provider chunks while tracking open blocks;
+2. apply narrow classification when a terminal error, directly thrown confirmed quota/usage-limit/transport, public `STREAM_CLOSED`/WebSocket failure, or EOF without a terminal chunk arrives;
+3. if plain text exists and no tool call was emitted, close open blocks, append a recovery notice, and finish with `stop`;
+4. if a tool call exists, including a tool-only stream with no text, return a non-retryable failure without replaying the complete request.
+
+The module does not execute tools or add a hidden pre-stream retry loop. Only a pre-output `RATE_LIMIT`, `SERVER`, `TIMEOUT`, or confirmed `TRANSPORT` that matches the retry policy is eligible for at most two upper-layer retries. Directly thrown confirmed failures use the same sanitization and recovery path, while unrelated exceptions still propagate unchanged. Fast and transport selection never triggers service-tier downgrade or full-request replay.
+
+## Profile composition
+
+`codex-community.patch.yml` inserts authorization and `dsh-codex` without modifying the general `llm-pi-ai` Cordis row. Other pi-ai providers remain available in the same profile.
+
+This plugin's external route is `dsh-codex`, and its credential key is `dsh-codex/openai-codex`; routes and credential scopes belonging to the general plugin remain unchanged. If a user enables both Codex routes, the model selector shows two provider groups. Every DSH upgrade must rerun bundle coexistence, replay, and isolated-profile-load tests.
+
+## Other capability boundaries
+
+- Session compaction uses DSH's built-in automatic compaction and `/compact`; this plugin does not rewrite the compaction protocol.
+- Web search uses DSH tools and their corresponding credentials; it does not reuse ChatGPT OAuth.
+- Image generation or editing requires a separate model, credentials, and billing boundary and is not provided by `0.0.1`.