Repository navigation
Commit c594e1c
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
- .changeset
- packages/spec/src/contracts
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1134 | 1134 | | |
1135 | 1135 | | |
1136 | 1136 | | |
1137 | | - | |
| 1137 | + | |
| 1138 | + | |
| 1139 | + | |
| 1140 | + | |
| 1141 | + | |
1138 | 1142 | | |
1139 | 1143 | | |
1140 | 1144 | | |
| |||
0 commit comments