Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
5c8fa24
Add the admission line model
josephschorr Nov 10, 2026
c63b761
Model node headroom for whole-set admission
josephschorr Nov 10, 2026
b60e847
Decide admissions in order with fair share between agents
josephschorr Nov 10, 2026
c088254
Compute a session's whole pod demand before creating it
josephschorr Nov 10, 2026
bb11f5d
Share the bundle session builder between reconcile and demand
josephschorr Nov 10, 2026
8acf65a
Gate session pods on admission and release it on reclaim
josephschorr Nov 10, 2026
b17fe18
Admit sessions from a single leader-only pass
josephschorr Nov 10, 2026
108cbe0
Scope the admitter's session list to the watched namespaces
josephschorr Nov 10, 2026
a412bf4
Re-queue admitted sessions the scheduler could not place
josephschorr Nov 10, 2026
42e7d57
Add burst admission scenario to bronzethread
josephschorr Nov 10, 2026
f62e3a1
Keep unscoped transcript steps unscoped
josephschorr Nov 10, 2026
d57412e
Bound the misfit release and pin status.admission
josephschorr Nov 10, 2026
426fbec
Plan early reclaim of warm idle sessions
josephschorr Nov 10, 2026
45ecac6
Reclaim warm idle sessions early when their agent's line is waiting
josephschorr Nov 10, 2026
b33286c
Credit in-flight reclaims before planning more
josephschorr Nov 10, 2026
09bad9a
Cap concurrent sessions per agent; let delegated children through
josephschorr Nov 10, 2026
28f0453
Tell queued sessions where they are in line
josephschorr Nov 10, 2026
a1d1131
Queue a session in line when it reaches the admission gate
josephschorr Nov 10, 2026
38fc471
Order the line by last wake, not by admission transitions
josephschorr Nov 10, 2026
b53444b
Adopt sessions whose pods predate admission
josephschorr Nov 10, 2026
3f39e34
Stop the misfit release looping on an optimistic capacity model
josephschorr Nov 10, 2026
6669f35
Reclaim a warm idle session when its line is blocked by the cap
josephschorr Nov 10, 2026
ad681f9
Release admission when a forensic hold reaps a session's pods
josephschorr Nov 10, 2026
1640274
Match a session's sandbox pods by label, not by name
josephschorr Nov 10, 2026
a623bac
Tidy admission minors from the branch review
josephschorr Nov 10, 2026
2841733
Queue sessions slept or held before admission when they resume
josephschorr Nov 11, 2026
5cb8027
Use neutral fixture names in admission tests
josephschorr Nov 11, 2026
dfa9fc3
Exempt only operator-recorded delegated children from the admission cap
josephschorr Nov 11, 2026
6db6471
Cover the admission branches the review found untested and document t…
josephschorr Nov 11, 2026
5eae717
Defer an admission pass when delegation records cannot be read
josephschorr Nov 11, 2026
a8d5174
Finish renaming admitter test fixtures
josephschorr Nov 11, 2026
26f16fa
Charge the e2e capacity model one set per session, not per reservation
josephschorr Nov 11, 2026
005e40f
Describe the deferred pass in the delegation list's comment and log
josephschorr Nov 11, 2026
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
8 changes: 8 additions & 0 deletions config/crds/agentprimitives.authzed.com_agentclasses.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -1542,6 +1542,14 @@ spec:
required:
- prompt
type: object
maxConcurrentSessions:
description: |-
MaxConcurrentSessions: at most this many of this agent's sessions hold
capacity at once. Delegated child sessions are not counted and are
never blocked by it. Unset means no limit.
format: int32
minimum: 1
type: integer
mcpServers:
description: |-
MCPServers references MCPServer CRs in the same namespace whose
Expand Down
27 changes: 27 additions & 0 deletions config/crds/agentprimitives.authzed.com_agentsessions.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -432,6 +432,33 @@ spec:
- artifactID
type: object
type: array
admission:
description: |-
Admission is where this session stands in its AgentClass's admission
line while it waits for its pod set to be admitted. Written by the
operator's admitter only when the position changes, and cleared when the
session is admitted. Nil when the session is not waiting.
properties:
joinedAt:
description: |-
JoinedAt is when the session took its place in line: its creation, or
the wake that re-queued it.
format: date-time
type: string
lineLength:
description: LineLength is how many sessions are waiting in the
line.
format: int32
type: integer
position:
description: Position is the session's 1-based place in its line.
format: int32
type: integer
required:
- joinedAt
- lineLength
- position
type: object
agentWakeCredit:
description: |-
AgentWakeCredit is how many further AGENT-DRIVEN wakes this session will
Expand Down
45 changes: 45 additions & 0 deletions internal/cmd/operator/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,12 @@ import (
"github.com/google/uuid"
"io"
"log/slog"
"maps"
"net"
"net/http"
"os"
runtimedebug "runtime/debug"
"slices"
"strings"
"sync/atomic"
"time"
Expand Down Expand Up @@ -102,6 +104,8 @@ import (
_ "github.com/authzed/openagentprimitives/pkg/channels/channelkinds/onepassword" // register onepassword relsync.Kind for the relationshipsource controller (relsync.Get); also reachable transitively via the relsource/imports blank import above, but this is the explicit wiring site for THIS aspect, not an accident of that one
_ "github.com/authzed/openagentprimitives/pkg/channels/channelkinds/slack" // register slack kind for channel-controller validation
"github.com/authzed/openagentprimitives/pkg/cli/clikit"
sessionadmission "github.com/authzed/openagentprimitives/pkg/controllers/admission"
"github.com/authzed/openagentprimitives/pkg/controllers/admission/admitter"
agentclassctrl "github.com/authzed/openagentprimitives/pkg/controllers/agentclass"
"github.com/authzed/openagentprimitives/pkg/controllers/agentidentity"
agentsessionctrl "github.com/authzed/openagentprimitives/pkg/controllers/agentsession"
Expand Down Expand Up @@ -757,6 +761,13 @@ type config struct {
idleStorageReclaimAfter time.Duration
failedSandboxReapGrace time.Duration
capacityHoldTimeout time.Duration
// sessionAdmission gates every booting AgentSession's pods on the
// admitter's whole-set, fair-share decision; false admits at once.
sessionAdmission bool
// admissionMinWarm is how long an idle session keeps its admission (and
// warm pods) before the admitter may reclaim it early for a session of its
// AgentClass waiting in line.
admissionMinWarm time.Duration
oauthRefreshThreshold time.Duration
workspaceStorageClass string
workspaceSize string
Expand Down Expand Up @@ -882,6 +893,10 @@ func newCommand() *cobra.Command {
"How long a Failed session's sandbox pods (bundle SpiceboxSessions + runner pod) are kept for debugging before teardown. The AgentSession itself is kept either way. Set to 0 (or negative) to disable reaping entirely (keep everything, for debugging).")
fs.DurationVar(&cfg.capacityHoldTimeout, "capacity-hold-timeout", time.Hour,
"How long a booting AgentSession whose sandbox/detector pods are Pending on a cluster capacity shortfall (Insufficient cpu/memory, too many pods) is HELD — queued with a notice in its channel, resuming by itself once the scheduler places the pod — instead of failing at the ordinary readiness deadline. Measured from provisioning start. Pods that can never fit, or are blocked by a taint or volume affinity, still fail at the ordinary deadline. Set to a negative value to disable holding.")
fs.BoolVar(&cfg.sessionAdmission, "session-admission", true,
"Admit each booting AgentSession's whole pod set against node capacity before any of its pods is created, in join order with fair share between AgentClasses; sessions that do not fit wait in line. Set to false to admit every session at once (pods then queue in the scheduler as before).")
fs.DurationVar(&cfg.admissionMinWarm, "admission-min-warm", 5*time.Minute,
"Minimum time an idle AgentSession keeps its admission (and warm pods) before the admitter may put it to sleep early, ahead of its sleepAfter grace, to make room for a session of the same AgentClass waiting in line. A held (SessionHold) session is never reclaimed. Only applies with --session-admission.")
fs.DurationVar(&cfg.oauthRefreshThreshold, "oauth-refresh-threshold", 5*time.Minute,
"Default refresh threshold for type=oauth AgentIdentity credentials. AgentIdentities with spec.refreshThreshold override this per-identity.")
fs.StringVar(&cfg.workspaceStorageClass, "workspace-storage-class", "",
Expand Down Expand Up @@ -2668,6 +2683,7 @@ func run(cfg *config) {
DefaultSessionSleepAfter: cfg.defaultSessionSleepAfter,
FailedSandboxReapGrace: cfg.failedSandboxReapGrace,
CapacityHoldTimeout: cfg.capacityHoldTimeout,
AdmissionEnabled: cfg.sessionAdmission,
DefaultSessionStorageRetention: cfg.sessionStorageRetention,
SessionGCAfter: cfg.sessionGCAfter,
NodePinnedStorageReclaimGrace: cfg.nodePinnedStorageReclaimGrace,
Expand Down Expand Up @@ -2748,6 +2764,35 @@ func run(cfg *config) {
}
log.Info("registered controller", "name", "AgentSession", "operatorURL", operatorURL)

// The admitter decides which booting sessions the reconciler above may
// create pods for. Leader-only (the controller-runtime default), so one
// operator admits against the free space at a time. Capacity is declared
// as the interface and assigned a concrete value, never a typed-nil
// pointer (see the repo conventions on nil interfaces).
//
// The capacity snapshot reads nodes and pods from the cached client while
// sessions are listed through the APIReader. Only the session list must
// see the admitter's own last writes (a lagging cache would show an
// admitted session still waiting and admit a second into its space);
// node and pod state the admitter never writes, so a cache a moment
// behind costs at most one pass's accuracy, and an uncached list of every
// pod on each pass would be a full apiserver read per wake.
var admissionCapacity sessionadmission.CapacitySource = sessionadmission.KubeCapacitySource{Reader: mgr.GetClient()}
if err := (&admitter.Reconciler{
Client: mgr.GetClient(),
APIReader: mgr.GetAPIReader(),
// The same namespace set the manager cache is scoped to, so the
// uncached session list stays inside the RBAC a watch set grants.
Namespaces: slices.Sorted(maps.Keys(cacheNamespaces(cfg.watchNamespaces, operatorNamespace(cfg.podNamespace)))),
Capacity: admissionCapacity,
Enabled: cfg.sessionAdmission,
MinWarm: cfg.admissionMinWarm,
}).SetupWithManager(mgr); err != nil {
log.Error(err, "unable to register admission controller")
os.Exit(1)
}
log.Info("registered controller", "name", "Admission", "enabled", cfg.sessionAdmission)

// Workshop provisions/tears down a builder session's isolated namespace,
// exact RBAC, SpiceDB tuple and bearer token (spec §1.2/§1.3). spiceDBClient
// is a real, non-nil *spicedb.Client here (construction failure exits
Expand Down
1 change: 1 addition & 0 deletions internal/cmd/operator/main_controllers_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ func TestOperatorRegistersExpectedControllers(t *testing.T) {
"AgentClass": true,
"Channel": true,
"AgentSession": true,
"Admission": true,
"GuardianAgentSessionGrants": true,
"MonitoringWatchers": true,
"UserIdentity": true,
Expand Down
7 changes: 7 additions & 0 deletions pkg/apis/v1alpha1/agentclass_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,13 @@ type AgentClassSpec struct {
// +optional
Budget *BudgetConfig `json:"budget,omitempty"`

// MaxConcurrentSessions: at most this many of this agent's sessions hold
// capacity at once. Delegated child sessions are not counted and are
// never blocked by it. Unset means no limit.
// +optional
// +kubebuilder:validation:Minimum=1
MaxConcurrentSessions *int32 `json:"maxConcurrentSessions,omitempty"`

// BoundEntities is the PRE-RENAME spelling of spec.authz.slots.
//
// Still deserialized on purpose. This is an AUTHZ field: dropping it from
Expand Down
8 changes: 5 additions & 3 deletions pkg/apis/v1alpha1/agentsession_ownership.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,11 @@ var operatorOwnedStatusFields = map[string]bool{
// Stamped by the operator when it acts on a UI-serve request, exactly as
// lastWakeAt is for a conversation wake. Separate fields because the two
// requests must not consume each other — see AnnotationUIServeRequestedAt.
"lastUIServeAt": true,
"lastIdleAt": true,
"sleptAt": true,
"lastUIServeAt": true,
"lastIdleAt": true,
"sleptAt": true,
// admission is the admitter's view of a waiting session's place in line.
"admission": true,
"awaitingUserInputSince": true,
// parentExchange is written by the RUNNER of a delegated child (the
// ask_parent meta tool, and the loop's two answer-arrived clears), like
Expand Down
18 changes: 18 additions & 0 deletions pkg/apis/v1alpha1/agentsession_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,13 @@ type AgentSessionStatus struct {
// +optional
EstimatedCost *EstimatedSessionCost `json:"estimatedCost,omitempty"`

// Admission is where this session stands in its AgentClass's admission
// line while it waits for its pod set to be admitted. Written by the
// operator's admitter only when the position changes, and cleared when the
// session is admitted. Nil when the session is not waiting.
// +optional
Admission *AdmissionStatus `json:"admission,omitempty"`

// AwaitingUserInputSince is set when the agent yields via
// await_user_message and cleared on resume or terminal. It is the durable
// floor under the at-most-once turn_activity yield event: a non-nil value
Expand Down Expand Up @@ -1598,3 +1605,14 @@ type GoalExecutionReference struct {
GoalRevision int64 `json:"goalRevision"`
ConsentDigest string `json:"consentDigest"`
}

// AdmissionStatus is a waiting session's place in its admission line.
type AdmissionStatus struct {
// Position is the session's 1-based place in its line.
Position int32 `json:"position"`
// LineLength is how many sessions are waiting in the line.
LineLength int32 `json:"lineLength"`
// JoinedAt is when the session took its place in line: its creation, or
// the wake that re-queued it.
JoinedAt metav1.Time `json:"joinedAt"`
}
48 changes: 48 additions & 0 deletions pkg/apis/v1alpha1/conditions.go
Original file line number Diff line number Diff line change
Expand Up @@ -511,6 +511,45 @@ const (
ReasonCapacityHoldExpired = "HoldExpired"
)

// AgentSession admission.
const (
// AgentSessionConditionAdmitted is True while the operator has admitted the
// session's whole pod set against its AgentClass's line, and False once the
// session has been released back to the line (reclaimed, or a placement
// misfit). Absent until the session first joins a line.
AgentSessionConditionAdmitted = "Admitted"
)

// AgentSessionConditionAdmitted reasons.
const (
ReasonAdmitted = "Admitted"
// ReasonAdmissionQueued marks a session that has reached the admission
// gate and is waiting in line. Its transition time is the moment it
// arrived, which the waiting timeout is measured from; the admitter
// considers only sessions carrying it, so a session parked at an earlier
// gate never reserves anything.
ReasonAdmissionQueued = "Queued"
// ReasonAdmissionAdopted marks a session whose pods were created before
// admission was switched on: the admitter adopts it as admitted, so it is
// counted as a holder rather than gated with its pods already up.
ReasonAdmissionAdopted = "Adopted"
// ReasonAdmittedUnknownCapacity marks a session admitted while the
// admitter had no reliable view of cluster capacity (no node data, a
// failed snapshot, or a namespace-scoped operator that cannot see other
// namespaces' pods). Nothing proved its set fits, so a stall is not
// treated as a misfit: its pods keep the ordinary pod-level hold.
ReasonAdmittedUnknownCapacity = "AdmittedUnknownCapacity"
// ReasonAdmissionReclaimed marks a session released so a session ahead of
// it in line could be admitted.
ReasonAdmissionReclaimed = "Reclaimed"
// ReasonAdmissionMisfit marks a session released because its pods did not
// fit where they were placed.
ReasonAdmissionMisfit = "PlacementMismatch"
// ReasonCapacityHoldWaitingAdmission is the CapacityHold reason while a
// session waits in line to be admitted.
ReasonCapacityHoldWaitingAdmission = "WaitingForAdmission"
)

// Settings reasons (shared by AgentClass + AgentSession SettingsAccepted and the
// Settings CR SelfConsistent conditions).
const (
Expand Down Expand Up @@ -1028,6 +1067,15 @@ const (
// coalesces rather than duplicating.
AnnotationUIServeRequestedAt = "agentprimitives.authzed.com/ui-serve-requested-at"

// AnnotationReclaimRequested asks the operator to put a warm Idle session
// to sleep now, ahead of its sleepAfter grace, because a session of the
// same AgentClass is waiting in the admission line and freeing this one's
// pods lets it in. Written by the admitter (RFC3339 of the pass that asked;
// left alone if already present); the AgentSession reconciler's sleep path
// honors it — still behind the SessionHold guard — and removes it once the
// session is slept, or as stale once the session has left Idle.
AnnotationReclaimRequested = "agentprimitives.authzed.com/reclaim-requested"

// AnnotationSidecarFailureReported carries, as a JSON object, the
// sidecar-name → failure-fingerprint map the runner has already reported to
// the user — the durable half of its once-per-failure contract, since a
Expand Down
26 changes: 26 additions & 0 deletions pkg/apis/v1alpha1/zz_generated.deepcopy.go

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

19 changes: 19 additions & 0 deletions pkg/bronzethread/bundle.go
Original file line number Diff line number Diff line change
Expand Up @@ -275,6 +275,11 @@ type Bundle struct {
// raises a warning naming what stopped running.
MetaToolReplies map[string]MetaToolReply `json:"metaToolReplies,omitempty"`

// Admission runs the bundle with whole-set session admission on, against
// a fixed capacity. Absent — every bundle but the admission scenarios —
// sessions are ungated, as before. See sessions.go.
Admission *Admission `json:"admission,omitempty"`

// LLM is the model's side, POSITIONAL: the nth Send gets the nth entry.
LLM []LLMStep `json:"llm"`

Expand Down Expand Up @@ -361,6 +366,10 @@ func (b Bundle) Validate() error {
return err
}

if err := b.validateSessions(); err != nil {
return err
}

return b.ValidateToolOutputs()
}

Expand Down Expand Up @@ -632,6 +641,12 @@ type LLMStep struct {
// position. Steps for one class stay positional among themselves.
AgentClass string `json:"agentClass,omitempty"`

// Thread scopes the step to the session a named userTurns thread opened,
// for the case AgentClass cannot tell apart: several sessions of ONE class
// at once. A request belongs to the thread whose opening text is its first
// user message. Steps for one thread stay positional among themselves.
Thread string `json:"thread,omitempty"`

// Expect is the divergence check. It is verified against the actual request
// BEFORE the reply is returned, so a system that took a different path
// fails loudly instead of being handed an answer to a question it did not
Expand Down Expand Up @@ -883,6 +898,10 @@ type Assertions struct {
// Channel asserts on the posts the bound output channel received.
Channel *ChannelAssertions `json:"channel,omitempty"`

// Admission claims the order the line admitted and finished the run's
// sessions in. Requires Bundle.Admission. See sessions.go.
Admission *AdmissionAssertions `json:"admission,omitempty"`

// ToolsCalled names tools the run must have DISPATCHED, read back off the
// replayed session's own transcript.
//
Expand Down
Loading
Loading