Summary

• Fix classification: root-cause provider streaming compatibility fix for opencode-go OpenAI Chat Completions streams.
• Maintainer-ready confidence: high; the transport and legacy stream consumers now have focused regression coverage for terminal finish reasons, trailing usage-only chunks, and request-level abort on terminal usage grace expiry.
• Root cause: the OpenAI-compatible stream lifecycle contract only treated natural async iterator close as the completion source, so an opencode-go terminal finish_reason mapped to no OpenClaw completion state when the SSE socket stayed open.
• Why this is root-cause fix: the patch adds an explicit provider compat contract for terminal finish_reason stream completion, preserves trailing usage chunks when configured, and aborts the underlying SDK request when the configured terminal usage grace expires.
• What did NOT change: scope boundary is unchanged for existing providers; no unrelated provider receives terminal-finish completion or a terminal usage cutoff unless its compat config opts into finishReasonTerminatesStream and terminalUsageGraceMs.

Linked context

• Fixes [Bug]: opencode-go provider streaming — API calls complete on provider side but gateway never receives stream termination signal #93610
• Related: opencode-go DeepSeek Chat Completions streaming can leave OpenClaw sessions stuck in stream progress after the provider has already reported completion.
• Was this requested by a maintainer or owner? No direct maintainer request; this addresses the linked user-reported provider streaming bug.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: opencode-go OpenAI-compatible streams now complete after a terminal finish_reason even when the socket stays open, continue through trailing usage-only chunks when present, and abort the request-level stream when the configured terminal usage grace expires without usage.
• Real environment tested: OpenClaw test runtime exercising the real OpenAI-compatible transport/parser code paths and opencode-go extension metadata in this patch; provider network access was not used.
• Exact steps or command run after this patch: pnpm test src/llm/providers/openai-completions.test.ts; pnpm test src/agents/openai-transport-stream.test.ts; pnpm --filter @openclaw/model-catalog-core test model-catalog-normalize.test.ts; pnpm test src/config/zod-schema.models.test.ts src/config/config-misc.test.ts -t compat; pnpm test extensions/opencode-go/index.test.ts.
• Evidence after fix (terminal capture):

$ pnpm test src/llm/providers/openai-completions.test.ts
Exit code: 0
Test Files  1 passed (1)
Tests  30 passed (30)

$ pnpm test src/agents/openai-transport-stream.test.ts
Exit code: 0
Test Files  1 passed (1)
Tests  275 passed (275)

$ pnpm --filter @openclaw/model-catalog-core test model-catalog-normalize.test.ts
Exit code: 0

$ pnpm test src/config/zod-schema.models.test.ts src/config/config-misc.test.ts -t compat
Exit code: 0
Test Files  2 passed (2)
Tests  5 passed | 86 skipped (91)

$ pnpm test extensions/opencode-go/index.test.ts
Exit code: 0
Test Files  1 passed (1)
Tests  12 passed (12)

• Observed result after fix: the regression suite now covers the reported stuck-stream shape, verifies the stream finalizes after terminal finish signals, verifies trailing usage-only chunks are retained, verifies timeout cleanup aborts the request-level signal, and verifies opencode-go DeepSeek metadata carries the opt-in compat settings.
• What was not tested: live opencode-go or DeepSeek provider network calls were not run because the issue-specific stream behavior is reproduced with deterministic OpenAI-compatible stream fixtures.

Gateway startup, /readyz, /healthz, listener, or generic status output is setup/smoke evidence only. Unless the linked issue is specifically a startup/readiness/health/liveness bug, this section must exercise the issue-specific runtime path and show the corrected post-fix behavior.

Tests and validation

• Commands run: pnpm test src/llm/providers/openai-completions.test.ts; pnpm test src/agents/openai-transport-stream.test.ts; pnpm --filter @openclaw/model-catalog-core test model-catalog-normalize.test.ts; pnpm test src/config/zod-schema.models.test.ts src/config/config-misc.test.ts -t compat; pnpm test extensions/opencode-go/index.test.ts.
• Regression coverage added or updated: transport and legacy OpenAI-compatible stream tests for terminal finish on a hanging socket, trailing usage-only chunks after stop/tool-call finish, and request-level abort when terminal usage grace expires.
• Extension-specific test lane: pnpm test extensions/opencode-go/index.test.ts verifies the bundled opencode-go extension exposes the DeepSeek compat fields.
• Contract test coverage: pnpm --filter @openclaw/model-catalog-core test model-catalog-normalize.test.ts and config compat schema tests cover the shared model catalog/config contract for the new compat fields.
• What failed before this fix, if known: a stream with terminal finish_reason and no socket close could remain pending indefinitely; a terminal usage grace timeout could finish locally without aborting the already-pending SDK stream read.
• If no test was added, why not: tests were added for the production behavior and compat metadata paths changed here.

Risk checklist

• Did user-visible behavior change? Yes; opencode-go DeepSeek streams can now finish when a terminal provider finish signal arrives even if the SSE socket remains open.
• Did config, environment, or migration behavior change? Yes; new optional compat fields were added to the model/config/catalog schema, with opencode-go DeepSeek models opting in.
• Did security, auth, secrets, network, or tool execution behavior change? Yes; terminal usage grace expiry now aborts the request-level SDK stream signal instead of only closing the iterator.
• Highest-risk area: OpenAI-compatible provider stream completion semantics and usage accounting.
• How is that risk mitigated: the behavior is opt-in per provider, delayed usage-only chunks remain supported, providers without terminalUsageGraceMs do not receive a new implicit cutoff, and both stream implementations have regression coverage.
• Plugin/shared surface boundary: this changes bundled extension metadata and shared compat schema only; no plugin runtime dependency or SDK import boundary changed.

Current review state

• Next action: submit the PR and wait for the remote CI and mergeability verdict.
• What is still waiting on author, maintainer, CI, or external proof: no known code review finding is open; remote CI and maintainer review are pending after PR creation.
• Which bot or reviewer comments were addressed: Codex diff review findings about trailing usage, legacy stream behavior, configurable terminal usage grace, iterator cleanup, and request-level abort on timeout were addressed; the latest Codex diff review found no blocking regression.