Skip to content

Commit c594e1c

Browse files
docs(spec): reconnect_required docblock names every way the grant stops working (#28862)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi91xQWB7H4w3nbGA1ZCTvmfK)_ Fixes #28614 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:只改 `packages/spec/src/contracts/automation-service.ts` 中 `ConnectorConnectionState.status` 注释里 `reconnect_required` 那一条,外加一条 `@objectstack/spec` patch changeset;不改任何代码。 - 为什么改:旧注释说"需重连"只表示授权服务器拒绝了授权。实际有三条路径会把连接标成需重连:刷新被拒、连接里没有可用来续期的东西(没发刷新令牌或没有客户端)、MCP 服务器在列工具时拒收了这个连接的令牌。注释现在把三条都写出来,并指向 `statusReason`。 - 风险与回滚:零运行时风险(仅注释,随 `dist` 的 `.d.ts` 发布);回滚即 revert 本 PR。 - 先看:`packages/spec/src/contracts/automation-service.ts` 的 `status` 文档块。 - 两分钟验证:`git diff origin/main...HEAD -- packages/spec/src/contracts/automation-service.ts`,预期只见注释行变动、无一行代码变化。 - 需要你做的:无,席位落地。 ## What changes Comments only, plus a `patch` changeset for `@objectstack/spec`. The JSDoc ships in the built declaration file (`packages/spec/dist/contracts/index.d.ts` carries the new text after `pnpm --filter @objectstack/spec build`), so the published bytes change and `skip-changeset` does not apply. The `reconnect_required` bullet said "the authorization server refused the grant". It now reads: the grant stopped working: the authorization server refused it on refresh, the connection keeps nothing to renew an expired access token with (no refresh token was issued, or no client to refresh with), or the upstream refused the connection's token while an `mcp` instance discovered its tools. `statusReason` says which. The wording is measured from the callers of `ConnectorConnectionStore#markReconnectRequired` on origin/main `7e60dc23` (two call sites, four triggers): - `oauth2-grant/grant-handle.ts` `grantRefused`, reached from `refreshOnce` three ways: the stored refresh token resolves to nothing (reason: `reconnectRequiredReason` plus "Its authorization server issued no refresh token, so an expired access token cannot be renewed"); `endpointOf` finds no client (reason plus "Its connection keeps no client to refresh it with"); the token endpoint answers `OAuth2GrantRefusedError` (bare `reconnectRequiredReason`). - `plugin.ts` `holdConnectorForRefusedConnection` (the discovery path): an `mcp` instance's server refused the borrowed token while it listed its tools (reason: `discoveryTokenRefusedReason`, naming the HTTP status). No forced test edits. ## Tests - `pnpm --filter @objectstack/spec typecheck && pnpm --filter @objectstack/spec test` under the verify lock at `12e4f349`: VERDICT command-exit 0; Test Files 788 passed (788); Tests 23295 passed, 1 todo. ## Acceptance notes - `connector-connections.ts` `markReconnectRequired`'s own docblock and the `status` field description in `sys-connector-connection.object.ts` still say only "the authorization server refused it (revoked, or expired with no usable refresh)". Outside this card's file surface; reported to the seat. - `reconnectRequiredReason` opens with "its authorization server refused the grant" even on the two grant-handle paths where no server was asked (no refresh token, no client). Those paths append the true cause, so the stored `statusReason` first claims a refusal and then says what really happened. Reported to the seat. ## Verification <details><summary>Derived gates at 12e4f34 (73 commands)</summary> `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran FILE` (each line recorded with its exit code): "73 derived, 72 run, 1 NOT-MEASURED, 0 UNRUN". - 69 commands exited 0 on the first pass. - Three exited 3 (prerequisite not met) and exited 0 after the prerequisite was supplied: `check-plugin-teardown-shape.mjs --self-test` (fetched its pinned fixture commit), `@objectstack/lint check:doc-formula-expressions` and `check:lean-entry-closure` (built lint, formula and objectql). - NOT MEASURED: `pnpm check:dual-build-cjs-loads`, reason: it needs `pnpm build` of every package (91 dists absent); the diff is one comment in spec. CI's Lint & Repo Gates runs it. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmTNNzkgjLj7uqRpPnk)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 76bf6c5 commit c594e1c

2 files changed

Lines changed: 13 additions & 1 deletion

File tree

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
Clause-②: no
6+
Metadata-protocol: none
7+
8+
`ConnectorConnectionState.status`'s docblock no longer says `reconnect_required` means only that the authorization server refused the grant. It now names every way the grant stops working: the authorization server refused it on refresh, the connection keeps nothing to renew an expired access token with (no refresh token was issued, or no client to refresh with), or the upstream refused the connection's token while an `mcp` instance discovered its tools; `statusReason` says which. Comment only; no behaviour change.

‎packages/spec/src/contracts/automation-service.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1134,7 +1134,11 @@ export interface ConnectorConnectionState {
11341134
/**
11351135
* `not_connected` — no administrator connected it here yet (the instance
11361136
* dispatches nothing for this organization); `connected`; or
1137-
* `reconnect_required` — the authorization server refused the grant.
1137+
* `reconnect_required` — the grant stopped working: the authorization
1138+
* server refused it on refresh, the connection keeps nothing to renew an
1139+
* expired access token with (no refresh token was issued, or no client to
1140+
* refresh with), or the upstream refused the connection's token while an
1141+
* `mcp` instance discovered its tools. `statusReason` says which.
11381142
*/
11391143
status: 'not_connected' | 'connected' | 'reconnect_required';
11401144
/** Why the grant stopped working, when `status` is `reconnect_required`. */

0 commit comments

Comments
 (0)