MAQPNADocs

AgentSession

AgentSession (maqpna.com/v1alpha1): every field, type, default and validation rule, generated from the CRD schema.

AgentSession is one sandboxed, identity-bound run of an Agent.

At a glance#

Property Value
API version maqpna.com/v1alpha1
Kind AgentSession
Scope Namespaced
Plural agentsessions
Short names asess, as, sess
Categories maqpna
Status subresource yes 
kubectl get agentsessions -A
kubectl get asess <name> -o yaml
kubectl explain agentsessions.spec

Columns in kubectl get#

Column Type From
Agent string .spec.agentRef
Phase string .status.phase
Sandbox string .status.sandboxName
User string .spec.user
Outcome string .status.outcome.result
Ready-In string .status.readyIn
Age date .metadata.creationTimestamp

Example#

From config/samples/agentsession-coder.yaml:

apiVersion: maqpna.com/v1alpha1
kind: AgentSession
metadata:
  name: coder-alice-1
  namespace: team-a
spec:
  agentRef: coder
  user: [email protected]
  scopes:
  - tools:github
  # models:team-a.coder is granted automatically (gateway model route).
  ttl: 2h
  input:
    # Mounted at /var/run/maqpna/input/task (MAQPNA_TASK_FILE); tasks of at
    # most 4KiB are also passed as MAQPNA_TASK. Alternatively use
    # configMapRef: {name: ..., key: ...}.
    task: |
      Fix issue #4821 in acme/app: the CSV export drops the last row.
      Open a pull request with a regression test.
    env:
      REPO: acme/app
      BASE_BRANCH: main

Spec fields#

AgentSessionSpec requests a sandboxed run of an Agent on behalf of a user. The agent, the on-behalf-of principal (user, userGroups, userAssertionRef) and the scopes cannot change after creation.

Field Type Required Description
agentRef string yes agentRef is the name of the Agent (same namespace); immutable. Min length: 1.
fork object fork starts the session from another session's (or a snapshot's) state; immutable. Rule: set exactly one of fromSession and fromSnapshot.
fork.fromSession string fromSession is the name of the session to fork from (same namespace). Max length: 253.
fork.fromSnapshot string fromSnapshot is the name of an AgentSessionSnapshot (same namespace). Max length: 253.
input object input is the task (and extra env) handed to the agent. Rule: set at most one of task and configMapRef.
input.configMapRef object configMapRef reads the task from a ConfigMap key instead of spec.input.task. The content is read once, when the session is provisioned.
input.configMapRef.key string yes key within the ConfigMap's data. Min length: 1. Max length: 253. Pattern: ^[-._a-zA-Z0-9]+$.
input.configMapRef.name string yes name of the ConfigMap (same namespace as the session). Min length: 1. Max length: 253.
input.env map[string]string env is extra environment for the agent container. Keys must match ^[A-Z][A-Z0-9_]*$ and must not start with MAQPNA_ (validated by the operator).
input.task string task is the prompt / task description (at most 64KiB). Max length: 65536.
scopes []string scopes requested; must be a subset of the agent's scopes. Defaults to all agent scopes.
suspend boolean suspend pauses the sandbox while keeping its state.
ttl string ttl of the session; clamped to min(tier.maxSessionTTL, agent.maxSessionTTL).
user string yes user is the email / subject the agent acts on behalf of. Min length: 1.
userAssertionRef object userAssertionRef points to a Secret key (same namespace) holding an OIDC ID token of the user. The operator verifies it against --user-oidc-issuer and requires its subject to be spec.user; the session fails with PrincipalUnverified otherwise.
userAssertionRef.key string yes Min length: 1. Max length: 253. Pattern: ^[-._a-zA-Z0-9]+$.
userAssertionRef.name string yes Min length: 1. Max length: 253.
userGroups []string userGroups are the on-behalf-of user's groups, passed to tools and policies as the maqpna_groups token claim. The principal-binding admission policy requires them to be a subset of the requester's own groups unless the requester is a trusted creator. Max items: 32.
  • Rule on spec: spec.agentRef is immutable
  • Rule on spec: spec.user is immutable
  • Rule on spec: spec.scopes is immutable
  • Rule on spec: spec.userGroups is immutable
  • Rule on spec: spec.userAssertionRef is immutable
  • Rule on spec: spec.fork is immutable

Status fields#

AgentSessionStatus is the observed state of an AgentSession.

The operator writes status; do not set it yourself.

Field Type Required Description
attestation object attestation describes attestation-gated token release, when required.
attestation.nonce string nonce bound to the release (not secret; freshness only).
attestation.releaseId string releaseId registered with the attestation service; the in-pod attest agent redeems it (with evidence + nonce) for the session token.
attestation.renewUntil string (date-time) renewUntil is the time until which the in-pod renewer sidecar may re-attest for fresh tokens (the session expiry).
attestation.required boolean yes
bootstrap object bootstrap is set for SandboxClaim (warm-pool) sessions: what the identity broker hands the adopted pod (late binding).
bootstrap.bootstrappedAt string (date-time) bootstrappedAt is when the broker released the session to the pod (microsecond precision). A claim-mode session is Running only once bootstrapped, and its readyAt is this time.
bootstrap.env []object env is the non-secret session environment (MAQPNA_*, spec.input.env, MAQPNA_TASK; attested: MAQPNA_ATTEST_URL / MAQPNA_RELEASE_ID / MAQPNA_NONCE). It never contains a token.
bootstrap.env[].name string yes
bootstrap.env[].value string yes
bootstrap.pod string pod / podUID name the pod that bootstrapped this session (set by the identity broker); any other pod is refused.
bootstrap.podUID string
bootstrap.tier string yes tier is the session's TrustTier (token claim).
conditions []object
conditions[].lastTransitionTime string (date-time) yes lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
conditions[].message string yes message is a human readable message indicating details about the transition. This may be an empty string. Max length: 32768.
conditions[].observedGeneration integer (int64) observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. Minimum: 0.
conditions[].reason string yes reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. Min length: 1. Max length: 1024. Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$.
conditions[].status string yes status of the condition, one of True, False, Unknown. One of: True, False, Unknown.
conditions[].type string yes type of condition in CamelCase or in foo.example.com/CamelCase. Max length: 316. Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$.
expiresAt string (date-time)
fork object fork records the parent of a forked session (F-22).
fork.inheritedTaints []string inheritedTaints are the parent's taint labels at capture time.
fork.parentSession string yes parentSession is the session the state was captured from.
fork.rootSession string rootSession is the first session of the lineage (budget roll-up).
fork.snapshot string snapshot is the AgentSessionSnapshot restored.
fork.strategy string strategy used to restore (SandboxSnapshot or VolumeSnapshot).
lastActivity string (date-time)
message string
modelRoute string modelRoute is the gateway model route (., sanitised); the sandbox reaches the model at {gateway}/llm/{modelRoute}/v1.
outcome object outcome records how the session ended (set once).
outcome.exitCode integer (int32) exitCode of the agent container, when it terminated and was observed.
outcome.finishedAt string (date-time) yes finishedAt is when the session ended.
outcome.reason string reason is a CamelCase machine-readable cause (AgentReported, ExitCode, PodSucceeded, PodFailed, TTLExpired, Revoked, Deleted, or the failure reason such as ScopeEscalation). Max length: 128.
outcome.result string yes result: Succeeded, Failed, Expired, Revoked or Cancelled. One of: Succeeded, Failed, Expired, Revoked, Cancelled.
outcome.summary string summary is the agent's own summary of the run (at most 1 KiB). Max length: 1024.
outcome.usageReport string usageReport is Recorded once the gateway recorded the session's sandbox time (POST /v1/usage/sandbox, audit ledger kind sandbox_usage), or Lost when reporting kept failing for an hour (a UsageReportFailed event records it). Empty: not reported yet, or never ready (no usage). One of: Recorded, Lost.
phase string SessionPhase is the lifecycle phase of an AgentSession. One of: Pending, Provisioning, Running, Suspended, Completed, Failed.
principal object principal is the verified on-behalf-of user (set once, at provisioning).
principal.groups []string groups passed to the token (maqpna_groups).
principal.user string user is spec.user as verified.
principal.verifiedBy string verifiedBy: requester (admission bound spec.user to the requesting user, or a trusted creator vouched), trustedCreator (only trusted creators may create sessions), idToken (userAssertionRef verified) or unverified (principal binding off). One of: requester, trustedCreator, idToken, unverified.
readyAt string (date-time) readyAt is when the session first became Running (sandbox Ready and, in SandboxClaim mode, the adopted pod bootstrapped).
readyIn string readyIn is readyAt - metadata.creationTimestamp: the session start latency (metric maqpna_session_ready_seconds).
sandboxKind string sandboxKind is Sandbox or SandboxClaim.
sandboxName string sandboxName is the upstream Sandbox (or SandboxClaim) name.
scopes []string scopes actually granted.
spiffeID string
startedAt string (date-time)
tokenExpiresAt string (date-time)
tokenIssuedAt string (date-time) tokenIssuedAt / tokenExpiresAt drive token refresh at 80% lifetime.
tokenSecretName string