Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions api/genpb/session_grpc.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 8 additions & 4 deletions api/session.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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

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.

// 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?

// 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.
Expand Down
8 changes: 8 additions & 0 deletions changelog/unreleased/approval-error-reasons.md
Original file line number Diff line number Diff line change
@@ -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.
12 changes: 8 additions & 4 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -1750,15 +1750,19 @@ flattened lifecycle enum, because collapsing them loses which axis actually move
<a name="agentsessions-v1-Sessions"></a>

### Sessions
Exec, Resume, Suspend and Fork attach google.rpc.ErrorInfo for recognized lifecycle and
compute-start failures. The domain is &#34;agentsessions&#34;, with no metadata:
Recognized lifecycle and compute-start failures attach google.rpc.ErrorInfo with domain
&#34;agentsessions&#34; 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.
Expand Down
2 changes: 1 addition & 1 deletion session/approval.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down
49 changes: 45 additions & 4 deletions session/approval_error_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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, "")
})
}
}
}

Expand Down
24 changes: 20 additions & 4 deletions session/approval_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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 {
Expand Down
14 changes: 9 additions & 5 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading