Skip to content

fix: attach consistent approval error reasons - #285

Open
Tom Gamble (gambtho) wants to merge 1 commit into
agent-primitives:mainfrom
gambtho:fix/approval-error-reasons
Open

Tom Gamble (gambtho) wants to merge 1 commit into
agent-primitives:mainfrom
gambtho:fix/approval-error-reasons

Conversation

@gambtho

Copy link
Copy Markdown
Member

Approve and CloseApproval now attach the existing SESSION_BUSY, CHECKPOINT_IN_PROGRESS, STALE_CURSOR and FENCED reasons, so clients can choose a recovery path without parsing messages. Status codes, messages and reasonless preconditions stay unchanged.

The spec and generated API reference describe condition-based reasons, including approval methods and harness registration.

Root race/shuffle tests, focused race tests repeated 50 times, generator drift checks, Buf lint and compatibility checks, doccheck, integrity audits, fuzz targets and local release builds passed.

Fixes #261.

AI use: AI-assisted implementation and tests.

@gambtho
Tom Gamble (gambtho) requested a review from a team as a code owner November 18, 2026 14:53
Copilot AI balanced review requested due to automatic review settings November 18, 2026 14:53

Copilot AI 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.

🟢 Approval recommended

No active review issues block the structured approval-error changes.

No open issues 🎉

1 file not reviewed
  • api/genpb/session_grpc.pb.go: Generated file
What changed in this PR

Makes approval errors consistent with the existing structured error contract, addressing #261 so clients can choose recovery actions without parsing messages. Status codes, messages, and reasonless preconditions remain unchanged.

Changes:

  • Attaches existing busy, checkpoint, stale-cursor, and fencing reasons to classified approval failures.
  • Expands tests for reason precedence, cause preservation, reasonless errors, and contention on both approval methods.
  • Documents condition-based reasons across approval methods, deletion admission, and harness registration.
File Description
spec.md Clarifies where condition-based error reasons apply.
session/​approval.go Uses the shared status constructor to attach approval error reasons.
session/​approval_test.go Checks structured busy errors for both approval RPCs.
session/​approval_error_test.go Tests classified reasons, precedence, preserved causes, and reasonless failures.
docs/​api-reference.md Updates generated documentation for the broader reason contract.
changelog/​unreleased/​approval-error-reasons.md Records the additive approval error details and documentation changes.
api/​session.proto Updates service comments describing error reason applicability.
api/​genpb/​session_grpc.pb.go Reflects the updated service comments in generated Go interfaces.

Review effort: Balanced

@aramase Anish Ramasekar (aramase) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

nit: Approve's RPC comment (api/session.proto:440) lists ABORTED as "local contention, append-CAS conflict or superseded fence", but Approve now also reports CHECKPOINT_IN_PROGRESS while a stateful Fork holds the checkpoint mark. Could it mention the checkpoint case the way CloseApproval's comment does?

Comment thread api/session.proto
// RESOURCE_EXHAUSTED: COMPUTE_RESOURCE_EXHAUSTED.
// DeleteSession also reports SESSION_BUSY and SESSION_DELETED for the matching conditions.
// DeleteSession reports SESSION_BUSY and SESSION_DELETED; mutation deletion-admission probes
// also report SESSION_BUSY. HarnessRegistry.RegisterHarness and HarnessRegistry.CreateHarness

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

nit: This is the only place that documents HARNESS_UNAVAILABLE for RegisterHarness/CreateHarness. The HarnessRegistry comments in harness_registry.proto still list only ALREADY_EXISTS and FAILED_PRECONDITION. Could UNAVAILABLE (HARNESS_UNAVAILABLE) go on those RPC comments too, since registry clients will look there?

Comment thread api/session.proto
// UNAVAILABLE: CHECKPOINT_PENDING, HARNESS_UNAVAILABLE, COMPUTE_UNAVAILABLE.
// RESOURCE_EXHAUSTED: COMPUTE_RESOURCE_EXHAUSTED.
// DeleteSession also reports SESSION_BUSY and SESSION_DELETED for the matching conditions.
// DeleteSession reports SESSION_BUSY and SESSION_DELETED; mutation deletion-admission probes

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

nit: "mutation deletion-admission probes" is internal vocabulary, and every RPC that runs the probe is already named in this paragraph. Could this clause be dropped, or say "with authorization enabled, Exec, Resume, Suspend, Fork, Approve, CloseApproval and DeleteSession also report SESSION_BUSY while the session is being deleted"? The same sentence is in spec.md.

This branch has not been deployed

No deployments
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.

Which methods should carry ErrorInfo reasons?

3 participants