diff --git a/api/genpb/session_grpc.pb.go b/api/genpb/session_grpc.pb.go index a765d00d..e32b97ca 100644 --- a/api/genpb/session_grpc.pb.go +++ b/api/genpb/session_grpc.pb.go @@ -42,15 +42,19 @@ const ( // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. // -// Exec, Resume, Suspend and Fork attach google.rpc.ErrorInfo for recognized lifecycle and -// compute-start failures. The domain is "agentsessions", with no metadata: +// Recognized lifecycle and compute-start failures attach google.rpc.ErrorInfo with domain +// "agentsessions" and no metadata. Reasons follow the classified condition, not the method: +// they apply to Exec, Resume, Suspend, Fork, Approve and CloseApproval wherever that condition +// is classified. // ABORTED: STALE_CURSOR, SESSION_BUSY, COMPUTE_BUSY, CHECKPOINT_IN_PROGRESS, FENCED, // SNAPSHOT_SUPERSEDED (Fork only). // FAILED_PRECONDITION: SESSION_DELETED, MEMORY_STATE_LOST, CHECKPOINT_INVALID, // COMPUTE_CONFIG_INVALID. -// UNAVAILABLE: CHECKPOINT_PENDING, HARNESS_UNAVAILABLE (Exec/Resume/Fork), COMPUTE_UNAVAILABLE. +// 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 +// also report SESSION_BUSY. HarnessRegistry.RegisterHarness and HarnessRegistry.CreateHarness +// report HARNESS_UNAVAILABLE when placement admission cannot reach the harness. // Unknown failures and caller CANCELED/DEADLINE_EXCEEDED have no reason. Other preconditions // retain their codes without a reason; this is not an exhaustive taxonomy of failures. // Clients must match both domain and reason; see spec.md section 11.9 for precedence and recovery. @@ -340,15 +344,19 @@ func (c *sessionsClient) Fork(ctx context.Context, in *ForkRequest, opts ...grpc // All implementations must embed UnimplementedSessionsServer // for forward compatibility. // -// Exec, Resume, Suspend and Fork attach google.rpc.ErrorInfo for recognized lifecycle and -// compute-start failures. The domain is "agentsessions", with no metadata: +// Recognized lifecycle and compute-start failures attach google.rpc.ErrorInfo with domain +// "agentsessions" and no metadata. Reasons follow the classified condition, not the method: +// they apply to Exec, Resume, Suspend, Fork, Approve and CloseApproval wherever that condition +// is classified. // ABORTED: STALE_CURSOR, SESSION_BUSY, COMPUTE_BUSY, CHECKPOINT_IN_PROGRESS, FENCED, // SNAPSHOT_SUPERSEDED (Fork only). // FAILED_PRECONDITION: SESSION_DELETED, MEMORY_STATE_LOST, CHECKPOINT_INVALID, // COMPUTE_CONFIG_INVALID. -// UNAVAILABLE: CHECKPOINT_PENDING, HARNESS_UNAVAILABLE (Exec/Resume/Fork), COMPUTE_UNAVAILABLE. +// 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 +// also report SESSION_BUSY. HarnessRegistry.RegisterHarness and HarnessRegistry.CreateHarness +// report HARNESS_UNAVAILABLE when placement admission cannot reach the harness. // Unknown failures and caller CANCELED/DEADLINE_EXCEEDED have no reason. Other preconditions // retain their codes without a reason; this is not an exhaustive taxonomy of failures. // Clients must match both domain and reason; see spec.md section 11.9 for precedence and recovery. diff --git a/api/session.proto b/api/session.proto index 4308bbb9..a7ee12e4 100644 --- a/api/session.proto +++ b/api/session.proto @@ -338,15 +338,19 @@ message Delta { bool done = 4; // last delta for this part } -// Exec, Resume, Suspend and Fork attach google.rpc.ErrorInfo for recognized lifecycle and -// compute-start failures. The domain is "agentsessions", with no metadata: +// Recognized lifecycle and compute-start failures attach google.rpc.ErrorInfo with domain +// "agentsessions" and no metadata. Reasons follow the classified condition, not the method: +// they apply to Exec, Resume, Suspend, Fork, Approve and CloseApproval wherever that condition +// is classified. // ABORTED: STALE_CURSOR, SESSION_BUSY, COMPUTE_BUSY, CHECKPOINT_IN_PROGRESS, FENCED, // SNAPSHOT_SUPERSEDED (Fork only). // FAILED_PRECONDITION: SESSION_DELETED, MEMORY_STATE_LOST, CHECKPOINT_INVALID, // COMPUTE_CONFIG_INVALID. -// UNAVAILABLE: CHECKPOINT_PENDING, HARNESS_UNAVAILABLE (Exec/Resume/Fork), COMPUTE_UNAVAILABLE. +// 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 +// also report SESSION_BUSY. HarnessRegistry.RegisterHarness and HarnessRegistry.CreateHarness +// report HARNESS_UNAVAILABLE when placement admission cannot reach the harness. // Unknown failures and caller CANCELED/DEADLINE_EXCEEDED have no reason. Other preconditions // retain their codes without a reason; this is not an exhaustive taxonomy of failures. // Clients must match both domain and reason; see spec.md section 11.9 for precedence and recovery. diff --git a/changelog/unreleased/approval-error-reasons.md b/changelog/unreleased/approval-error-reasons.md new file mode 100644 index 00000000..fd59a7ad --- /dev/null +++ b/changelog/unreleased/approval-error-reasons.md @@ -0,0 +1,8 @@ +--- +category: Fixed +--- + +- `Approve` and `CloseApproval` attach the existing `SESSION_BUSY`, `CHECKPOINT_IN_PROGRESS`, + `STALE_CURSOR` and `FENCED` error reasons for matching classified conditions. Status codes and + messages are unchanged; error details remain additive. The API reference also documents reasons + on approval methods, mutation deletion admission and harness registration. diff --git a/docs/api-reference.md b/docs/api-reference.md index dfa655f5..12b5413a 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -1750,15 +1750,19 @@ flattened lifecycle enum, because collapsing them loses which axis actually move ### Sessions -Exec, Resume, Suspend and Fork attach google.rpc.ErrorInfo for recognized lifecycle and -compute-start failures. The domain is "agentsessions", with no metadata: +Recognized lifecycle and compute-start failures attach google.rpc.ErrorInfo with domain +"agentsessions" and no metadata. Reasons follow the classified condition, not the method: +they apply to Exec, Resume, Suspend, Fork, Approve and CloseApproval wherever that condition +is classified. ABORTED: STALE_CURSOR, SESSION_BUSY, COMPUTE_BUSY, CHECKPOINT_IN_PROGRESS, FENCED, SNAPSHOT_SUPERSEDED (Fork only). FAILED_PRECONDITION: SESSION_DELETED, MEMORY_STATE_LOST, CHECKPOINT_INVALID, COMPUTE_CONFIG_INVALID. -UNAVAILABLE: CHECKPOINT_PENDING, HARNESS_UNAVAILABLE (Exec/Resume/Fork), COMPUTE_UNAVAILABLE. +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 +also report SESSION_BUSY. HarnessRegistry.RegisterHarness and HarnessRegistry.CreateHarness +report HARNESS_UNAVAILABLE when placement admission cannot reach the harness. Unknown failures and caller CANCELED/DEADLINE_EXCEEDED have no reason. Other preconditions retain their codes without a reason; this is not an exhaustive taxonomy of failures. Clients must match both domain and reason; see spec.md section 11.9 for precedence and recovery. diff --git a/session/approval.go b/session/approval.go index 24c00fa3..2f9559b0 100644 --- a/session/approval.go +++ b/session/approval.go @@ -79,7 +79,7 @@ func approvalError(err error) error { case errors.Is(err, controller.ErrInvalidApprovalDecision), errors.Is(err, controller.ErrInvalidExecutionLog), errors.Is(err, controller.ErrReplayDiverged), errors.Is(err, controller.ErrApprovalUnavailable): return status.Error(codes.FailedPrecondition, err.Error()) case errors.Is(err, placement.ErrSessionBusy), errors.Is(err, placement.ErrCheckpointing), errors.Is(err, eventlog.ErrConflict), errors.Is(err, eventlog.ErrFenced): - return status.Error(codes.Aborted, err.Error()) + return withStatusCause(codes.Aborted, err) default: return hostInternalError("approve: %v", err) } diff --git a/session/approval_error_test.go b/session/approval_error_test.go index 441da9aa..b47cb83c 100644 --- a/session/approval_error_test.go +++ b/session/approval_error_test.go @@ -14,10 +14,51 @@ import ( "github.com/agent-primitives/sessions/placement" ) -func TestApprovalCheckpointRefusalIsAborted(t *testing.T) { - err := approvalError(fmt.Errorf("checkpoint: %w", placement.ErrCheckpointing)) - if status.Code(err) != codes.Aborted { - t.Fatalf("Approve checkpoint refusal=%v, want ABORTED", err) +func TestApprovalErrorReasons(t *testing.T) { + for _, tc := range []struct { + name string + cause error + code codes.Code + reason string + }{ + {"busy", placement.ErrSessionBusy, codes.Aborted, "SESSION_BUSY"}, + {"checkpoint", placement.ErrCheckpointing, codes.Aborted, "CHECKPOINT_IN_PROGRESS"}, + {"conflict", eventlog.ErrConflict, codes.Aborted, "STALE_CURSOR"}, + {"fence", eventlog.ErrFenced, codes.Aborted, "FENCED"}, + {"checkpoint before fence", errors.Join(placement.ErrCheckpointing, eventlog.ErrFenced), codes.Aborted, "CHECKPOINT_IN_PROGRESS"}, + {"conflict before busy", errors.Join(eventlog.ErrConflict, placement.ErrSessionBusy), codes.Aborted, "STALE_CURSOR"}, + {"deleted", eventlog.ErrDeleted, codes.FailedPrecondition, "SESSION_DELETED"}, + } { + for name, mapper := range map[string]func(error) error{"Approve": approvalError, "CloseApproval": closeApprovalError} { + t.Run(name+"/"+tc.name, func(t *testing.T) { + cause := fmt.Errorf("approval: %w", tc.cause) + got := mapper(cause) + assertErrorInfo(t, got, tc.code, tc.reason) + if !errors.Is(got, cause) || status.Convert(got).Message() != cause.Error() { + t.Fatalf("lost cause or changed message: %v", got) + } + }) + } + } +} + +func TestApprovalReasonlessErrors(t *testing.T) { + for _, tc := range []struct { + cause error + code codes.Code + }{ + {controller.ErrInvalidApprovalDecision, codes.FailedPrecondition}, + {controller.ErrInvalidExecutionLog, codes.FailedPrecondition}, + {controller.ErrReplayDiverged, codes.FailedPrecondition}, + {controller.ErrApprovalUnavailable, codes.FailedPrecondition}, + {errors.New("storage"), codes.Internal}, + {status.Error(codes.Aborted, "foreign status"), codes.Internal}, + } { + for name, mapper := range map[string]func(error) error{"Approve": approvalError, "CloseApproval": closeApprovalError} { + t.Run(name+"/"+tc.cause.Error(), func(t *testing.T) { + assertErrorInfo(t, mapper(fmt.Errorf("approval: %w", tc.cause)), tc.code, "") + }) + } } } diff --git a/session/approval_test.go b/session/approval_test.go index aa2c7343..da52b903 100644 --- a/session/approval_test.go +++ b/session/approval_test.go @@ -11,6 +11,7 @@ import ( "testing" "time" + "google.golang.org/genproto/googleapis/rpc/errdetails" "google.golang.org/grpc/codes" "google.golang.org/grpc/status" "google.golang.org/protobuf/proto" @@ -690,16 +691,31 @@ func TestApprovalBusyVersusBackendAborted(t *testing.T) { c := serveRegistry(t, store, r) uid := mustCreate(t, c) b.snapshotErr = status.Error(codes.Aborted, "backend conflict") + assertBusy := func(t *testing.T, err error) { + t.Helper() + st := status.Convert(err) + if st.Code() != codes.Aborted || len(st.Details()) != 1 { + t.Fatalf("local busy=%v, details=%v; want ABORTED with one reason", err, st.Details()) + } + info, ok := st.Details()[0].(*errdetails.ErrorInfo) + if !ok || info.Domain != "agentsessions" || info.Reason != "SESSION_BUSY" || len(info.Metadata) != 0 { + t.Fatalf("local busy detail=%v, want agentsessions/SESSION_BUSY without metadata", st.Details()[0]) + } + } b.beforeSnapshot = func() { info, err := store.SessionInfo(uid) if err != nil { t.Fatal(err) } ref := info.PendingApproval - _, err = c.Approve(t.Context(), &v1.ApproveRequest{Session: uid, ExecutionId: ref.ExecutionID, ToolCallId: ref.ToolCallID, RequestSeq: ref.RequestSeq, Approved: proto.Bool(false)}) - if status.Code(err) != codes.Aborted { - t.Errorf("local busy=%v", err) - } + t.Run("Approve", func(t *testing.T) { + _, err := c.Approve(t.Context(), &v1.ApproveRequest{Session: uid, ExecutionId: ref.ExecutionID, ToolCallId: ref.ToolCallID, RequestSeq: ref.RequestSeq, Approved: proto.Bool(false)}) + assertBusy(t, err) + }) + t.Run("CloseApproval", func(t *testing.T) { + _, err := c.CloseApproval(t.Context(), &v1.CloseApprovalRequest{Session: uid, ExecutionId: ref.ExecutionID, ToolCallId: ref.ToolCallID, RequestSeq: ref.RequestSeq}) + assertBusy(t, err) + }) } frames, err := collectPublicExec(c, &v1.ExecRequest{Session: uid}) if status.Code(err) != codes.Internal || frames[len(frames)-1].GetSession() != nil { diff --git a/spec.md b/spec.md index b0900796..7bb6a8f9 100644 --- a/spec.md +++ b/spec.md @@ -1524,16 +1524,20 @@ does not erase data or reclaim compute. | `Cancel` | `UNIMPLEMENTED` | | Any other failure | `INTERNAL` | -Known lifecycle failures on Exec, Resume, Suspend and Fork carry one `google.rpc.ErrorInfo` -with domain `agentsessions`, the reason below and no metadata. DeleteSession reports only -SESSION_BUSY and SESSION_DELETED from this table. Clients match domain and reason together; -details are additive, and an older server or an unclassified error may supply none. +Recognized lifecycle and compute-start failures carry one `google.rpc.ErrorInfo` with domain +`agentsessions`, the reason below and no metadata. Reasons follow the classified condition, not +the method: they apply to Exec, Resume, Suspend, Fork, Approve and CloseApproval wherever the +corresponding condition is classified. DeleteSession reports SESSION_BUSY and SESSION_DELETED; +mutation deletion-admission probes also report SESSION_BUSY. HarnessRegistry.RegisterHarness and +HarnessRegistry.CreateHarness report HARNESS_UNAVAILABLE when placement admission cannot reach +the harness. Clients match domain and reason together; details are additive, and an older server +or an unclassified error may supply none. | Code | Condition → reason (first matching condition within the code wins) | |---|---| | `ABORTED` | Append-CAS conflict → `STALE_CURSOR`; local session contention → `SESSION_BUSY`; fork snapshot superseded → `SNAPSHOT_SUPERSEDED`; compute contention → `COMPUTE_BUSY`; checkpoint in progress → `CHECKPOINT_IN_PROGRESS`; superseded writer fence → `FENCED` | | `FAILED_PRECONDITION` | Deleted session → `SESSION_DELETED`; lost memory-tier state → `MEMORY_STATE_LOST`; refused checkpoint → `CHECKPOINT_INVALID`; known invalid compute configuration → `COMPUTE_CONFIG_INVALID` | -| `UNAVAILABLE` | Checkpoint uploading → `CHECKPOINT_PENDING`; unreachable harness → `HARNESS_UNAVAILABLE` (Exec/Resume/Fork); compute unavailable → `COMPUTE_UNAVAILABLE` | +| `UNAVAILABLE` | Checkpoint uploading → `CHECKPOINT_PENDING`; unreachable harness → `HARNESS_UNAVAILABLE`; compute unavailable → `COMPUTE_UNAVAILABLE` | | `RESOURCE_EXHAUSTED` | No eligible compute capacity → `COMPUTE_RESOURCE_EXHAUSTED` | A stale cursor requires reading the head before retrying. Session/compute contention can be