Skip to content

fix: Compose OAuth behavior annotations with current catalog - #1252

Merged
sswiftdrtv merged 5 commits into
mainfrom
codex/oauth-annotations-current-main
Nov 17, 2026
Merged

sswiftdrtv merged 5 commits into
mainfrom
codex/oauth-annotations-current-main

Conversation

@sidneyswift

@sidneyswift sidneyswift commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem and result

OAuth tool annotations must describe side effects consistently across full and limited discovery. This successor preserves candidate #1238 and normally composes it with current main 10fce9198fc4bacf184405e7792563fec90f7496. Current head: c7e2a2e70c75602cb781f9b6ce6bfd91666ea080.

Explicit read-only, destructive and open-world policy covers the full and limited registries, including three current social tools. Discovery tests verify 94 full registrations / 93 model-visible tools and 7 limited registrations / 6 model-visible tools. Standard-only catalog preparation and ingestion remain excluded. Handler behavior, schemas, authentication and scopes are unchanged.

Validation and reviews

Focused discovery/annotation tests passed (3 files, 7 tests), as did local lint, production types and contract checks on the original successor. The 12 contribution files and complete contribution patch remain byte-identical through both normal main merges. Incoming Sites files match accepted main exactly. Fresh final-head required CI is tracked below by GitHub.

Independent exact-head Spec: 0 findings. Standards: 0 findings. Codex completed with zero findings and Cubic reviewed 12/12 files at 50cad80d (reported coverage 94%); Cubic skipped subsequent merge-only commits. Those automated reviews cover the unchanged contribution, not an exact-head automated composition review.

CodeRabbit's pre-merge warning uses stale 60af5644 base. Catalog/LinkedIn refactors it attributes to this PR are already in main. The catalog annotation mismatch was subsequently corrected narrowly in standard registration without granting delegated access. Repeated policy triples are an intentional audit inventory. Independent triage found no actionable in-scope correction; this does not erase the warning or claim a completed full CodeRabbit review.

Release boundary

Both deployment guards remain false: fix/mcp-oauth-behavior-annotations and codex/oauth-annotations-current-main. Original draft #1238 is untouched. Ready status allows automated review only. Coordinator owns merge/release approval. The source-release decision below authorizes the normal main merge and its normal deployment; plugin resubmission remains unapproved.

For deployed metadata acceptance and broader client release sign-off, verify authenticated tools/list on the exact endpoint in both existing OAuth modes and the four standard Catalog metadata tuples through an already authorized client. Deployed database settlement and native-client behavior remain separate owning-epic acceptance. No business tool execution, new grant, migration or credential discovery is authorized by this source release.

New exact-head review corrections

The later Cubic findings on 4e5b1ee were inspected separately from prior triage. Corrected export settlement/refund wording (4605071264), image generation rationale (4605071310), six combined source links (4605071333), and explicit limited-tool visibility assertions (4605071324). For 4605071285, catalog saves retain history but replace the current revision: retained destructive:true and aligned standard registration with shared metadata. Added discovery-only standard assertions; all four catalog tools remain delegated:false and excluded from OAuth.

Style comments 4605071230/1243/1257/1296: no tracked universal100-line file cap was found. Retained cohesive policy inventories and regression coverage. The existing long registration function remains maintainability debt under the actual function-length guidance; no auth/schema refactor was added.

Independent fix-diff Spec and Standards reviews: zero actionable findings. Focused tests passed4files/8tests after reproducing the standard annotation mismatch; local lint and OAuth types passed. Exact-head format, lint, compatibility and test workflows all pass. Cubic completed review of the five-file correction with zero new issues (5/5 confidence). Five earlier GitHub threads remain unresolved: the four style suggestions and the catalog metadata suggestion; their reasoned dispositions above require coordinator review, not an auto-approval claim. Guards and original1238 remain untouched.

Coordinator source-release decision

Recoup OS accepts exact c7e2a2e70c75602cb781f9b6ce6bfd91666ea080 for a normal metadata source release under the October 19 standing delivery authority. Required exact-head checks passed; independent source, Catalog-contract and reconciliation release-scope reviews found no unresolved blocking defect. Discovery hints/descriptions and the narrow standard Catalog metadata projection change; handlers, schemas, authentication, scopes, delegated exclusions and business permissions remain unchanged. The two feature-branch deployment guards remain intact.

This explicitly separates the present metadata correction from the earlier broad “before any release” wording. Authenticated deployed discovery, native-client acceptance, Pack settlement correctness and whole-epic completion remain unproven and open. They are not claimed by source tests or this decision. Observe normal post-merge CI/deployment and exact revision readback; do not use mutating Pack reads/exports as smoke tests. No manual deployment, business activation, provider call, spending, database apply or plugin resubmission is included.

sswiftdrtv and others added 2 commits November 9, 2026 09:35
Require explicit behavioral hints, cover full and limited catalogs, document classifications, and disable preview deployments for this review branch.
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Pre-merge checks: Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Solid & Clean Code Warning The standing FAIL is still supported at HEAD c7e2a2e70c75602cb781f9b6ce6bfd91666ea080. I checked each of its claims against the current files. None is resolved. **1. Long function changed by this PR… Before merge, address these items: 1. Split the register closure in lib/mcp/oauth/registerFullOAuthTools.ts (lines 33–204) into units of about 20 lines or less. Candidates are a policy-to-annotation mapper, an input-schema rewriter, a d…
Full details: Solid & Clean Code

Explanation

The standing FAIL is still supported at HEAD c7e2a2e70c75602cb781f9b6ce6bfd91666ea080. I checked each of its claims against the current files. None is resolved. 1. Long function changed by this PR (SRP, clean code). lib/mcp/oauth/registerFullOAuthTools.ts (229 lines) contains the register closure. It starts at line 33 and ends at line 204, about 172 lines. The limit in the check is 20 lines. The closure still combines exclusion lists, schema rewriting, description building, policy lookup, registerTool wiring, auth checks, execution, and error mapping. The PR edits this closure. It changes the operation parameter type (lines 37–43), the policy lookup (lines 87–94), and the annotation wiring (lines 151–156). The PR adds to this function. It does not split it. 2. Repeated inline behavior shape (DRY). The destructive: boolean; openWorld: boolean shape is still written inline in four places: contextToolOperations.ts (lines 215–216), evidenceToolOperations.ts (lines 38–39), catalogCaseToolOperations.ts (lines 47–48), and registerFullOAuthTools.ts (lines 41–42). fullOAuthToolPolicy.ts defines a fifth shape, ToolPolicy (lines 1–6). That interface is not exported and is not reused. No shared behavior-policy type exists. The PR adds these fields to each copy. 3. Repeated literal triples (DRY, copy-paste values). fullOAuthToolPolicy.ts (222 lines) repeats readOnly/destructive/openWorld literals across about 68 entries. The PR adds about 203 lines to this file. The header comment calls the table an explicit audit inventory. That explains the intent. It does not remove the copy-paste pattern. No helper, default, or readOnlyTool()/writeTool() style builder exists. Expected-annotation data also repeats across the OAuth test files. No shared expected-annotation fixture exists in lib/mcp/oauth/__tests__. Mitigating points. The PR removes the hardcoded destructiveHint and openWorldHint defaults. The policy table is explicit and documented. Regression tests are added. These points do not meet the 20-line function limit, the shared-abstraction expectation, or the copy-paste rule. Verdict. The changed code matches the SRP function-length rule and the DRY copy-paste rule. The required remediation from the standing FAIL is not applied. The check does not allow the inventory rationale to waive these rules. Prior failure disposition. Not refuted and not addressed. Every named claim checks out at HEAD.

Resolution

Before merge, address these items: 1. Split the register closure in lib/mcp/oauth/registerFullOAuthTools.ts (lines 33–204) into units of about 20 lines or less. Candidates are a policy-to-annotation mapper, an input-schema rewriter, a description builder, and an authorized execution wrapper. Name each new file after its single exported function. 2. Export one shared behavior-policy type, for example ToolBehaviorPolicy with readOnly, destructive, openWorld, and optional delegated and notice. Reuse it in contextToolOperations.ts, evidenceToolOperations.ts, catalogCaseToolOperations.ts, fullOAuthToolPolicy.ts, and the operation parameter in registerFullOAuthTools.ts. Remove the inline copies and the unexported ToolPolicy. 3. Reduce repeated literals. Use helpers such as readOnlyTool() and writeTool({ destructive, openWorld }), or set shared defaults in one table. Each entry should state only its non-default values. Keep the explicit inventory if the audit requires it. 4. Move the shared expected-annotation data into one test fixture. Have fullOAuthCatalog.test.ts, limitedOAuthCatalog.test.ts, standardCatalogAnnotations.test.ts, and registerOAuthTools.test.ts import it. 5. Re-run the discovery tests. Confirm the counts remain 94 full / 93 model-visible and 7 limited / 6 model-visible.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@sswiftdrtv
sswiftdrtv marked this pull request as ready for review November 17, 2026 19:58
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T20:01:31.654137Z 50cad80 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7 issues found and verified against the latest diff

Confidence score: 4/5

  • The OAuth registration and policy modules exceed the 100-line limit, and the operation registry grows further past it. Split the cohesive logic and operation descriptors into smaller modules.
  • catalogCaseToolOperations.ts marks save_catalog_case as destructive even though it saves a revision without deleting data. Set the flag to false to match the tool’s behavior and hint.
  • In docs/mcp-oauth-annotations.md, the migration source cells combine two URLs into one link, and the generate_image justification describes editing instead of generating. Make each URL separately clickable and update the justification.
  • registerOAuthTools.test.ts now exceeds the 100-line limit. Trim the test or split out the new annotations coverage.
Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/mcp/oauth/contextToolOperations.ts">

<violation number="1" location="lib/mcp/oauth/contextToolOperations.ts:15">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

This change grows an already 158-line operation registry to 219 lines, further exceeding the rule’s 100-line limit. Move operation descriptors into focused modules and keep this composition file under 100 lines.</violation>
</file>

<file name="docs/mcp-oauth-annotations.md">

<violation number="1" location="docs/mcp-oauth-annotations.md:44">
P3: These source cells put two URLs inside one Markdown link, so the migration evidence is not separately clickable. Split each source cell into two links.</violation>

<violation number="2" location="docs/mcp-oauth-annotations.md:47">
P3: The `generate_image` justification refers to "edit", copied from the `edit_image` row. Replace that clause with a generation-specific description so the inventory is accurate for this tool.</violation>
</file>

<file name="lib/mcp/oauth/catalogCaseToolOperations.ts">

<violation number="1" location="lib/mcp/oauth/catalogCaseToolOperations.ts:19">
P2: `save_catalog_case` is marked `destructive: true`, but it only saves a new revision with server-maintained history and deletes nothing. Set it to `false` to match the other context writes and the `destructiveHint: false` that `registerCatalogCaseTools` actually emits. Otherwise this metadata contradicts the registered annotation.</violation>
</file>

<file name="lib/mcp/oauth/fullOAuthToolPolicy.ts">

<violation number="1" location="lib/mcp/oauth/fullOAuthToolPolicy.ts:221">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

These policy additions bring `fullOAuthToolPolicy.ts` to 222 lines, more than twice the 100-line limit. Split the inventory into cohesive modules under 100 lines each.</violation>
</file>

<file name="lib/mcp/oauth/__tests__/registerOAuthTools.test.ts">

<violation number="1" location="lib/mcp/oauth/__tests__/registerOAuthTools.test.ts:94">
P3: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

This file is now 103 lines, over the 100-line cap in the code-style rules, and the new annotations test is what pushed it past the limit. Trim the added test or fixture lines so the file stays under 100 lines (at or below 99).</violation>
</file>

<file name="lib/mcp/oauth/registerFullOAuthTools.ts">

<violation number="1" location="lib/mcp/oauth/registerFullOAuthTools.ts:91">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

This 229-line module is more than twice Rule 3’s 100-line limit, and this change expands its registration-policy logic further. Split a cohesive responsibility into a separate module to bring this file under the limit.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

@@ -12,147 +12,208 @@ export const contextToolOperations = {
name: "list_music_release_cases",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

This change grows an already 158-line operation registry to 219 lines, further exceeding the rule’s 100-line limit. Move operation descriptors into focused modules and keep this composition file under 100 lines.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At lib/mcp/oauth/contextToolOperations.ts, line 15:

<comment>This change grows an already 158-line operation registry to 219 lines, further exceeding the rule’s 100-line limit. Move operation descriptors into focused modules and keep this composition file under 100 lines.</comment>

<file context>
@@ -12,147 +12,208 @@ export const contextToolOperations = {
     name: "list_music_release_cases",
     description: "List saved release cases and their review status.",
     readOnly: true,
+    destructive: false,
+    openWorld: false,
   },
</file context>

@@ -1,141 +1,222 @@
interface ToolPolicy {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

These policy additions bring fullOAuthToolPolicy.ts to 222 lines, more than twice the 100-line limit. Split the inventory into cohesive modules under 100 lines each.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At lib/mcp/oauth/fullOAuthToolPolicy.ts, line 221:

<comment>These policy additions bring `fullOAuthToolPolicy.ts` to 222 lines, more than twice the 100-line limit. Split the inventory into cohesive modules under 100 lines each.</comment>

<file context>
@@ -1,141 +1,222 @@
+  },
+  publish_site: { readOnly: false, destructive: true, openWorld: true },
+  unpublish_site: { readOnly: false, destructive: true, openWorld: true },
+  delete_site: { readOnly: false, destructive: true, openWorld: true },
 };
</file context>

? {
readOnly: operation.readOnly,
destructive: operation.destructive,
openWorld: operation.openWorld,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

This 229-line module is more than twice Rule 3’s 100-line limit, and this change expands its registration-policy logic further. Split a cohesive responsibility into a separate module to bring this file under the limit.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At lib/mcp/oauth/registerFullOAuthTools.ts, line 91:

<comment>This 229-line module is more than twice Rule 3’s 100-line limit, and this change expands its registration-policy logic further. Split a cohesive responsibility into a separate module to bring this file under the limit.</comment>

<file context>
@@ -79,7 +85,12 @@ export function registerFullOAuthTools(
+      ? {
+          readOnly: operation.readOnly,
+          destructive: operation.destructive,
+          openWorld: operation.openWorld,
+          notice: "",
+        }
</file context>

Comment thread docs/mcp-oauth-tool-qualification.md Resolved
description:
"Save a bounded portable catalog case as a customer assertion. Requires last read revision and an idempotency key. Does not verify rights, authorize provider operations, register music or collect royalties. History is server-maintained; omit local history.",
readOnly: false,
destructive: true,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: save_catalog_case is marked destructive: true, but it only saves a new revision with server-maintained history and deletes nothing. Set it to false to match the other context writes and the destructiveHint: false that registerCatalogCaseTools actually emits. Otherwise this metadata contradicts the registered annotation.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At lib/mcp/oauth/catalogCaseToolOperations.ts, line 19:

<comment>`save_catalog_case` is marked `destructive: true`, but it only saves a new revision with server-maintained history and deletes nothing. Set it to `false` to match the other context writes and the `destructiveHint: false` that `registerCatalogCaseTools` actually emits. Otherwise this metadata contradicts the registered annotation.</comment>

<file context>
@@ -7,30 +7,45 @@ export const catalogCaseToolOperations = {
     description:
       "Save a bounded portable catalog case as a customer assertion. Requires last read revision and an idempotency key. Does not verify rights, authorize provider operations, register music or collect royalties. History is server-maintained; omit local history.",
     readOnly: false,
+    destructive: true,
+    openWorld: false,
     delegated: false,
</file context>
Suggested change
destructive: true,
destructive: false,

).toThrow();
});

it("sets explicit behavior-based annotations for every limited tool", () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Custom agent: Enforce Clear Code Style and Maintainability Practices

This file is now 103 lines, over the 100-line cap in the code-style rules, and the new annotations test is what pushed it past the limit. Trim the added test or fixture lines so the file stays under 100 lines (at or below 99).

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At lib/mcp/oauth/__tests__/registerOAuthTools.test.ts, line 94:

<comment>This file is now 103 lines, over the 100-line cap in the code-style rules, and the new annotations test is what pushed it past the limit. Trim the added test or fixture lines so the file stays under 100 lines (at or below 99).</comment>

<file context>
@@ -86,3 +90,14 @@ it("rejects profile updates with no changed fields", () => {
   ).toThrow();
 });
+
+it("sets explicit behavior-based annotations for every limited tool", () => {
+  const { tools } = fixture();
+  for (const [name, tool] of tools) {
</file context>

Comment thread docs/mcp-oauth-annotations.md Resolved
Comment thread docs/mcp-oauth-annotations.md Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 5 files (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Requires human review: Auto-approval blocked by 5 unresolved issues from previous reviews.

View guided diff | Turn on auto-fix | Re-trigger cubic

@sswiftdrtv
sswiftdrtv merged commit 057b8e2 into main Nov 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants