agentruntime

package
v0.0.0-...-804b954 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package agentruntime defines the stable, Temporal-free Go contract for Agent Runtime.

Index

Constants

View Source 
const (
	// MaxIdempotencyKeyBytes bounds one public idempotency key before transport-specific limits apply.
	MaxIdempotencyKeyBytes = 128
	// MaxInputParts bounds the number of public Input parts accepted in one request.
	MaxInputParts = 32
	// MaxTextPartBytes bounds one public text Input part.
	MaxTextPartBytes = 64 * 1024
	// MaxSessionViewQueuedTurns bounds the queued Turns included in one Session inspection.
	MaxSessionViewQueuedTurns = 100
)
View Source 
const MaxApprovalsPerPage = 64

MaxApprovalsPerPage bounds one owner-scoped approval inbox response.

View Source 
const MaxArtifactBytes int64 = 8 << 20

MaxArtifactBytes is the largest immutable Artifact the public runtime contract can retain and serve. Applications that use ArtifactStreamer must admit this complete contract size by default rather than failing a valid large result at the client boundary.

View Source 
const MaxArtifactsPerSession = 256

MaxArtifactsPerSession bounds one owner-scoped Session Artifact index response.

View Source 
const MaxToolCallsPerTurn = 64

MaxToolCallsPerTurn bounds one public Tool-call inspection response.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentID 

type AgentID string

AgentID identifies an Agent without carrying tenancy or routing information.

func ParseAgentID 

func ParseAgentID(value string) (AgentID, error)

ParseAgentID validates an externally supplied Agent ID.

func (AgentID) LogValue 

func (id AgentID) LogValue() slog.Value

LogValue returns a redacted Agent ID for structured logs.

func (AgentID) MarshalJSON 

func (id AgentID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Agent ID.

func (AgentID) Redacted 

func (id AgentID) Redacted() string

Redacted returns a safe diagnostic Agent ID.

func (AgentID) String 

func (id AgentID) String() string

String returns the canonical Agent ID.

func (*AgentID) UnmarshalJSON 

func (id *AgentID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates an Agent ID.

type AgentRevisionID 

type AgentRevisionID string

AgentRevisionID identifies one immutable Agent specification revision.

func ParseAgentRevisionID 

func ParseAgentRevisionID(value string) (AgentRevisionID, error)

ParseAgentRevisionID validates an externally supplied Agent revision ID.

func (AgentRevisionID) LogValue 

func (id AgentRevisionID) LogValue() slog.Value

LogValue returns a redacted Agent revision ID for structured logs.

func (AgentRevisionID) MarshalJSON 

func (id AgentRevisionID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Agent revision ID.

func (AgentRevisionID) Redacted 

func (id AgentRevisionID) Redacted() string

Redacted returns a safe diagnostic Agent revision ID.

func (AgentRevisionID) String 

func (id AgentRevisionID) String() string

String returns the canonical Agent revision ID.

func (*AgentRevisionID) UnmarshalJSON 

func (id *AgentRevisionID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates an Agent revision ID.

type AgentSpecification 

type AgentSpecification struct {
	ID           AgentID          `json:"id"`
	RevisionID   AgentRevisionID  `json:"revision_id"`
	Revision     uint64           `json:"revision"`
	Name         string           `json:"name"`
	ModelProfile string           `json:"model_profile"`
	Instructions string           `json:"instructions"`
	Tools        []ToolDefinition `json:"tools,omitempty"`
	CreatedAt    time.Time        `json:"created_at"`
}

AgentSpecification is one immutable, versioned definition of Agent behavior.

func (AgentSpecification) Clone 

func (specification AgentSpecification) Clone() AgentSpecification

Clone returns an independent Agent specification snapshot.

type Approval 

type Approval struct {
	ID        ApprovalID `json:"id"`
	SessionID SessionID  `json:"session_id"`
	TurnID    TurnID     `json:"turn_id"`
	// ToolCallID links this decision to the single model Tool call it governs.
	// It is an opaque caller-safe correlation value, never a capability.
	ToolCallID string `json:"tool_call_id"`
	// Requester is the principal that owns the requested effect. It is visible
	// only through the already owner-scoped approval projection.
	Requester string `json:"requester"`
	// PolicyRevision is the immutable policy digest evaluated at admission;
	// clients cannot alter it as part of a decision.
	PolicyRevision string          `json:"policy_revision"`
	State          ApprovalState   `json:"state"`
	Action         *ApprovalAction `json:"action"`
	Scope          *ApprovalScope  `json:"scope"`
	ExpiresAt      time.Time       `json:"expires_at"`
	DecidedAt      *time.Time      `json:"decided_at,omitempty"`
}

Approval is a caller-safe immutable projection of a pending or terminal human decision.

func (Approval) Clone 

func (approval Approval) Clone() Approval

Clone returns an independent Approval snapshot.

type ApprovalAction 

type ApprovalAction struct {
	Verb   string `json:"verb"`
	Target string `json:"target"`
}

ApprovalAction is the fixed, human-readable description of an elevated operation. It deliberately contains no raw model arguments or credentials.

type ApprovalID 

type ApprovalID string

ApprovalID identifies one owner-actionable Approval request.

func ParseApprovalID 

func ParseApprovalID(value string) (ApprovalID, error)

ParseApprovalID validates an externally supplied Approval ID.

func (ApprovalID) LogValue 

func (id ApprovalID) LogValue() slog.Value

LogValue returns a redacted Approval ID for structured logs.

func (ApprovalID) MarshalJSON 

func (id ApprovalID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Approval ID.

func (ApprovalID) Redacted 

func (id ApprovalID) Redacted() string

Redacted returns a safe diagnostic Approval ID.

func (ApprovalID) String 

func (id ApprovalID) String() string

String returns the canonical Approval ID.

func (*ApprovalID) UnmarshalJSON 

func (id *ApprovalID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates an Approval ID.

type ApprovalPage 

type ApprovalPage struct {
	Approvals []Approval `json:"approvals"`
	Truncated bool       `json:"truncated"`
}

ApprovalPage is one bounded owner-scoped Approval inbox projection.

func (ApprovalPage) Clone 

func (page ApprovalPage) Clone() ApprovalPage

Clone returns an independent Approval inbox snapshot.

type ApprovalScope 

type ApprovalScope struct {
	MaximumUses uint32 `json:"maximum_uses"`
}

ApprovalScope is the public bounded-use projection of a proposed capability. Capability bytes and digests never cross this boundary.

type ApprovalState 

type ApprovalState string

ApprovalState is the public lifecycle state of one human decision request. 

const (
	// ApprovalPending awaits an owner decision before any tool execution may be authorized.
	ApprovalPending ApprovalState = "pending"
	// ApprovalApproved records an owner decision that created a bounded internal grant.
	ApprovalApproved ApprovalState = "approved"
	// ApprovalDenied records an owner decision that forbids the requested effect.
	ApprovalDenied ApprovalState = "denied"
	// ApprovalExpired records that the decision window elapsed before a decision.
	ApprovalExpired ApprovalState = "expired"
	// ApprovalCancelled records that its owning Turn was cancelled before a
	// decision. It can never create or preserve a grant.
	ApprovalCancelled ApprovalState = "cancelled"
)

type ArtifactDownload 

type ArtifactDownload struct {
	Artifact ArtifactReference `json:"artifact"`
	Body     []byte            `json:"body"`
}

ArtifactDownload is one authorized immutable artifact read. It contains metadata chosen by runtime state and bounded bytes, never a storage URL.

func (ArtifactDownload) Clone 

func (download ArtifactDownload) Clone() ArtifactDownload

Clone returns an independent authorized artifact read.

type ArtifactID 

type ArtifactID string

ArtifactID identifies an authorized immutable Artifact reference.

func ParseArtifactID 

func ParseArtifactID(value string) (ArtifactID, error)

ParseArtifactID validates an externally supplied Artifact ID.

func (ArtifactID) LogValue 

func (id ArtifactID) LogValue() slog.Value

LogValue returns a redacted Artifact ID for structured logs.

func (ArtifactID) MarshalJSON 

func (id ArtifactID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Artifact ID.

func (ArtifactID) Redacted 

func (id ArtifactID) Redacted() string

Redacted returns a safe diagnostic Artifact ID.

func (ArtifactID) String 

func (id ArtifactID) String() string

String returns the canonical Artifact ID.

func (*ArtifactID) UnmarshalJSON 

func (id *ArtifactID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates an Artifact ID.

type ArtifactPage 

type ArtifactPage struct {
	Artifacts []ArtifactReference `json:"artifacts"`
	Truncated bool                `json:"truncated"`
}

ArtifactPage is one bounded owner-scoped Artifact index for a Session. It exposes immutable metadata only; Artifact bytes require ReadArtifact or OpenArtifact and are authorized again for the exact caller.

func (ArtifactPage) Clone 

func (page ArtifactPage) Clone() ArtifactPage

Clone returns an independent ArtifactPage snapshot.

type ArtifactReference 

type ArtifactReference struct {
	ID        ArtifactID `json:"id"`
	MediaType string     `json:"media_type"`
	SizeBytes int64      `json:"size_bytes"`
	SHA256    string     `json:"sha256"`
}

ArtifactReference identifies immutable content without exposing a storage URL.

type ArtifactStream 

type ArtifactStream struct {
	Artifact ArtifactReference
	Body     io.ReadCloser
}

ArtifactStream is an authorized immutable Artifact transfer. Callers must Close it; reading to EOF verifies the HTTP Digest trailer and exact size.

type ArtifactStreamer 

type ArtifactStreamer interface {
	// OpenArtifact opens a caller-authorized Artifact without buffering it.
	OpenArtifact(context.Context, ArtifactID) (ArtifactStream, error)
}

ArtifactStreamer is the additive streaming Artifact capability. It remains separate from RuntimeClient so existing RuntimeClient implementations keep their v1 source compatibility.

type AuthorizationSink 

type AuthorizationSink interface {
	// SetBearerToken accepts one request-scoped bearer credential.
	SetBearerToken(string) error
}

AuthorizationSink accepts one request-scoped bearer credential.

type CancelSessionRequest 

type CancelSessionRequest struct {
	SessionID      SessionID `json:"session_id"`
	IdempotencyKey string    `json:"idempotency_key"`
}

CancelSessionRequest terminally cancels a drained Session.

type CancelTurnRequest 

type CancelTurnRequest struct {
	SessionID      SessionID `json:"session_id"`
	TurnID         TurnID    `json:"turn_id"`
	IdempotencyKey string    `json:"idempotency_key"`
}

CancelTurnRequest explicitly cancels one active or queued Turn.

type CapabilityGrant 

type CapabilityGrant struct {
	MaximumUses uint32    `json:"maximum_uses"`
	Uses        uint32    `json:"uses"`
	ExpiresAt   time.Time `json:"expires_at"`
}

CapabilityGrant is a caller-safe projection of bounded grant consumption. It deliberately omits capability bytes, policy digests, and grant identity.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the concrete HTTP implementation of RuntimeClient.

func NewClient 

func NewClient(config ClientConfig) (*Client, error)

NewClient validates a bounded, explicit public HTTP client configuration.

func (*Client) CancelSession 

func (client *Client) CancelSession(ctx context.Context, request CancelSessionRequest) (Session, error)

CancelSession terminally cancels a drained Session.

func (*Client) CancelTurn 

func (client *Client) CancelTurn(ctx context.Context, request CancelTurnRequest) (Turn, error)

CancelTurn explicitly requests durable Turn cancellation.

func (*Client) CloseSession 

func (client *Client) CloseSession(ctx context.Context, request CloseSessionRequest) (Session, error)

CloseSession closes Input admission and drains accepted work.

func (*Client) CreateAgent 

func (client *Client) CreateAgent(ctx context.Context, request CreateAgentRequest) (AgentSpecification, error)

CreateAgent creates the first immutable Agent revision through the admin surface.

func (*Client) CreatePolicy 

func (client *Client) CreatePolicy(ctx context.Context, request CreatePolicyRequest) (Policy, error)

CreatePolicy creates the first immutable revision of a tenant Policy.

func (*Client) CreateSession 

func (client *Client) CreateSession(ctx context.Context, request CreateSessionRequest) (Session, error)

CreateSession creates a principal-owned Session pinned to one Agent revision.

func (*Client) DecideApproval 

func (client *Client) DecideApproval(ctx context.Context, request DecideApprovalRequest) (Approval, error)

DecideApproval records one idempotent owner decision for a pending Approval.

func (*Client) Events 

func (client *Client) Events(ctx context.Context, sessionID SessionID, after Cursor, limit int) (EventPage, error)

Events resumes bounded Product-event observation after an opaque Cursor.

func (*Client) GetAgentRevision 

func (client *Client) GetAgentRevision(ctx context.Context, agentID AgentID, revisionID AgentRevisionID) (AgentSpecification, error)

GetAgentRevision reads one immutable Agent revision through the admin surface.

func (*Client) GetPolicy 

func (client *Client) GetPolicy(ctx context.Context, name string, revision uint64) (Policy, error)

GetPolicy reads one immutable Policy revision through the admin surface.

func (*Client) IdempotencyStatus 

func (client *Client) IdempotencyStatus(ctx context.Context, key string) (IdempotencyStatus, error)

IdempotencyStatus reads the caller-scoped durable status of one mutation key.

func (*Client) InspectApproval 

func (client *Client) InspectApproval(ctx context.Context, approvalID ApprovalID) (Approval, error)

InspectApproval returns the caller-authorized state of one Approval.

func (*Client) InspectSession 

func (client *Client) InspectSession(ctx context.Context, sessionID SessionID) (SessionView, error)

InspectSession returns caller-safe Session state without backend identifiers.

func (*Client) InspectToolCalls 

func (client *Client) InspectToolCalls(ctx context.Context, sessionID SessionID, turnID TurnID) (ToolCallPage, error)

InspectToolCalls returns bounded owner-scoped Tool-call lifecycle projections.

func (*Client) InspectTurn 

func (client *Client) InspectTurn(ctx context.Context, sessionID SessionID, turnID TurnID) (Turn, error)

InspectTurn returns one caller-safe Turn snapshot.

func (*Client) ListApprovals 

func (client *Client) ListApprovals(ctx context.Context) (ApprovalPage, error)

ListApprovals returns the caller-authorized bounded Approval inbox.

func (*Client) ListSessionArtifacts 

func (client *Client) ListSessionArtifacts(ctx context.Context, sessionID SessionID) (ArtifactPage, error)

ListSessionArtifacts returns one bounded owner-scoped Artifact index for a Session without downloading artifact bytes or exposing content storage.

func (*Client) OpenArtifact 

func (client *Client) OpenArtifact(ctx context.Context, artifactID ArtifactID) (ArtifactStream, error)

OpenArtifact opens a bounded Artifact response. Reaching EOF verifies its declared Digest trailer; Close permits cancellation before completion.

func (*Client) ReadArtifact 

func (client *Client) ReadArtifact(ctx context.Context, artifactID ArtifactID) (ArtifactDownload, error)

ReadArtifact downloads a Content-Length-bounded immutable response only after the server has authorized the exact tenant/principal/artifact tuple. Call OpenArtifact for a trailer-verified streaming response.

func (*Client) ReviseAgent 

func (client *Client) ReviseAgent(ctx context.Context, request ReviseAgentRequest) (AgentSpecification, error)

ReviseAgent creates another immutable Agent revision through the admin surface.

func (*Client) RevisePolicy 

func (client *Client) RevisePolicy(ctx context.Context, request RevisePolicyRequest) (Policy, error)

RevisePolicy creates the next immutable revision of a tenant Policy.

func (*Client) SendInput 

func (client *Client) SendInput(ctx context.Context, request SendInputRequest) (SendInputResult, error)

SendInput idempotently admits bounded Input into a Session.

type ClientConfig 

type ClientConfig struct {
	BaseURL          string
	HTTPClient       *http.Client
	Credentials      CredentialSource
	RequestIDs       RequestIDSource
	MaxResponseBytes int64
	// MaxArtifactBytes independently bounds binary Artifact reads. Zero admits
	// the public contract maximum, while ordinary JSON responses retain their
	// smaller default limit.
	MaxArtifactBytes int64
}

ClientConfig contains every dependency and finite bound required by Client.

type CloseSessionRequest 

type CloseSessionRequest struct {
	SessionID      SessionID `json:"session_id"`
	IdempotencyKey string    `json:"idempotency_key"`
}

CloseSessionRequest stops new admission and drains already accepted Input.

type ContentPart 

type ContentPart struct {
	Kind     ContentPartKind    `json:"kind"`
	Text     string             `json:"text,omitempty"`
	Artifact *ArtifactReference `json:"artifact,omitempty"`
}

ContentPart carries either bounded text or an Artifact reference.

func (ContentPart) Clone 

func (part ContentPart) Clone() ContentPart

Clone returns an independent content snapshot.

type ContentPartKind 

type ContentPartKind string

ContentPartKind identifies one bounded Input content representation. 

const (
	// ContentText contains bounded UTF-8 text.
	ContentText ContentPartKind = "text"
	// ContentArtifact refers to authorized immutable content by metadata.
	ContentArtifact ContentPartKind = "artifact"
)

type CreateAgentRequest 

type CreateAgentRequest struct {
	IdempotencyKey string           `json:"idempotency_key"`
	Name           string           `json:"name"`
	ModelProfile   string           `json:"model_profile"`
	Instructions   string           `json:"instructions"`
	Tools          []ToolDefinition `json:"tools,omitempty"`
}

CreateAgentRequest registers the first immutable revision of an Agent specification.

type CreatePolicyRequest 

type CreatePolicyRequest struct {
	IdempotencyKey string       `json:"idempotency_key"`
	Name           string       `json:"name"`
	Rules          []PolicyRule `json:"rules"`
}

CreatePolicyRequest creates the first immutable revision of a named Policy.

type CreateSessionRequest 

type CreateSessionRequest struct {
	IdempotencyKey string          `json:"idempotency_key"`
	AgentRevision  AgentRevisionID `json:"agent_revision_id"`
}

CreateSessionRequest creates a Session pinned to one exact Agent revision.

type CredentialSource 

type CredentialSource interface {
	// Authorize applies one request-scoped credential without exposing it to Client diagnostics.
	Authorize(context.Context, AuthorizationSink) error
}

CredentialSource authorizes one request without exposing credential bytes to Client diagnostics.

type Cursor 

type Cursor string

Cursor identifies an opaque Product-event replay position.

func ParseCursor 

func ParseCursor(value string) (Cursor, error)

ParseCursor validates an externally supplied Product-event Cursor.

func (Cursor) LogValue 

func (id Cursor) LogValue() slog.Value

LogValue returns a redacted Product-event Cursor for structured logs.

func (Cursor) MarshalJSON 

func (id Cursor) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Product-event Cursor.

func (Cursor) Redacted 

func (id Cursor) Redacted() string

Redacted returns a safe diagnostic Product-event Cursor.

func (Cursor) String 

func (id Cursor) String() string

String returns the canonical Product-event Cursor.

func (*Cursor) UnmarshalJSON 

func (id *Cursor) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a Product-event Cursor.

type DecideApprovalRequest 

type DecideApprovalRequest struct {
	ApprovalID     ApprovalID    `json:"approval_id"`
	Decision       ApprovalState `json:"decision"`
	IdempotencyKey string        `json:"idempotency_key"`
}

DecideApprovalRequest idempotently records one owner decision for a pending Approval.

type Error 

type Error struct {
	Failure Failure
}

Error is a safe runtime-owned command failure suitable for errors.As.

func (*Error) Error 

func (runtimeError *Error) Error() string

Error returns only the stable code and safe bounded message.

type Event 

type Event struct {
	ID         EventID   `json:"id"`
	Cursor     Cursor    `json:"cursor"`
	Sequence   uint64    `json:"sequence"`
	Kind       EventKind `json:"kind"`
	SessionID  SessionID `json:"session_id"`
	InputID    InputID   `json:"input_id,omitempty"`
	TurnID     TurnID    `json:"turn_id,omitempty"`
	OccurredAt time.Time `json:"occurred_at"`
}

Event is a bounded, ordered, caller-safe Product event.

type EventGap 

type EventGap struct {
	RequestedAfter Cursor `json:"requested_after"`
	Earliest       Cursor `json:"earliest_available,omitempty"`
	InspectSession bool   `json:"inspect_session"`
}

EventGap explicitly says a requested replay position is no longer available.

type EventID 

type EventID string

EventID identifies one Product event.

func ParseEventID 

func ParseEventID(value string) (EventID, error)

ParseEventID validates an externally supplied Product-event ID.

func (EventID) LogValue 

func (id EventID) LogValue() slog.Value

LogValue returns a redacted Product-event ID for structured logs.

func (EventID) MarshalJSON 

func (id EventID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Product-event ID.

func (EventID) Redacted 

func (id EventID) Redacted() string

Redacted returns a safe diagnostic Product-event ID.

func (EventID) String 

func (id EventID) String() string

String returns the canonical Product-event ID.

func (*EventID) UnmarshalJSON 

func (id *EventID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a Product-event ID.

type EventKind 

type EventKind string

EventKind identifies a stable Product-event vocabulary entry. 

const (
	// EventSessionCreated reports durable Session creation.
	EventSessionCreated EventKind = "session.created"
	// EventInputAccepted reports durable idempotent Input admission.
	EventInputAccepted EventKind = "input.accepted"
	// EventTurnQueued reports a Turn ordered behind active work.
	EventTurnQueued EventKind = "turn.queued"
	// EventTurnStarted reports that a Turn became active.
	EventTurnStarted EventKind = "turn.started"
	// EventTurnSucceeded reports one terminal successful outcome.
	EventTurnSucceeded EventKind = "turn.succeeded"
	// EventTurnFailed reports one terminal safe Failure outcome.
	EventTurnFailed EventKind = "turn.failed"
	// EventTurnCancelled reports one terminal cancelled outcome.
	EventTurnCancelled EventKind = "turn.cancelled"
	// EventProducerGap reports that a producer outcome could not be recovered
	// and the following terminal event is the durable finalization boundary.
	EventProducerGap EventKind = "producer.gap"
	// EventApprovalResolved reports a terminal approved or denied approval
	// without exposing an action or capability value.
	EventApprovalResolved EventKind = "approval.resolved"
	// EventApprovalExpired reports a terminal approval expiry without exposing
	// an action or capability value.
	EventApprovalExpired EventKind = "approval.expired"
	// EventApprovalCancelled reports that a pending approval was withdrawn
	// without exposing an action or capability value.
	EventApprovalCancelled EventKind = "approval.cancelled"
	// EventSandboxOperationFinalized reports that a sandbox-backed operation
	// reached a durable terminal outcome. Backend handles remain private.
	EventSandboxOperationFinalized EventKind = "sandbox_operation.finalized"
	// EventSessionClosing reports that no new Input is accepted while queued work drains.
	EventSessionClosing EventKind = "session.closing"
	// EventSessionCompleted reports a terminal drained Session.
	EventSessionCompleted EventKind = "session.completed"
	// EventSessionCancelled reports a terminal caller-requested Session cancellation.
	EventSessionCancelled EventKind = "session.cancelled"
	// EventSessionFailed reports a terminal runtime-owned Session failure.
	EventSessionFailed EventKind = "session.failed"
)

type EventPage 

type EventPage struct {
	Events     []Event   `json:"events"`
	NextCursor Cursor    `json:"next_cursor,omitempty"`
	Gap        *EventGap `json:"gap,omitempty"`
}

EventPage is one bounded replay page and its next opaque position.

type Failure 

type Failure struct {
	Code      FailureCode       `json:"code"`
	Message   string            `json:"message"`
	Retryable bool              `json:"retryable"`
	Details   map[string]string `json:"details,omitempty"`
}

Failure is a bounded, provider-neutral terminal Turn failure.

func (*Failure) Clone 

func (failure *Failure) Clone() *Failure

Clone returns an independent Failure snapshot.

type FailureCode 

type FailureCode string

FailureCode is a stable runtime-owned failure classification. 

const (
	// FailureInvalidInput means a request violated the public contract.
	FailureInvalidInput FailureCode = "invalid_input"
	// FailureConflict means an idempotency key or state transition conflicted.
	FailureConflict FailureCode = "conflict"
	// FailureNotFound safely covers absent or unauthorized resources.
	FailureNotFound FailureCode = "not_found"
	// FailureUnavailable means durable progress may be retried later.
	FailureUnavailable FailureCode = "unavailable"
	// FailureInternal means the runtime failed without exposing backend details.
	FailureInternal FailureCode = "internal"
)

type IdempotencyStatus 

type IdempotencyStatus struct {
	OperationID string     `json:"operation_id"`
	Command     string     `json:"command"`
	SessionID   SessionID  `json:"session_id,omitempty"`
	TurnID      TurnID     `json:"turn_id,omitempty"`
	ArtifactID  ArtifactID `json:"artifact_id,omitempty"`
	AcceptedAt  time.Time  `json:"accepted_at"`
}

IdempotencyStatus is the safe durable outcome lookup for one exact caller scope and idempotency key. It never exposes request bytes or backend IDs.

type Input 

type Input struct {
	ID         InputID       `json:"id"`
	Parts      []ContentPart `json:"parts"`
	AcceptedAt time.Time     `json:"accepted_at"`
}

Input is an immutable accepted Input snapshot.

func (Input) Clone 

func (input Input) Clone() Input

Clone returns an independent Input snapshot.

type InputID 

type InputID string

InputID identifies one accepted Input.

func ParseInputID 

func ParseInputID(value string) (InputID, error)

ParseInputID validates an externally supplied Input ID.

func (InputID) LogValue 

func (id InputID) LogValue() slog.Value

LogValue returns a redacted Input ID for structured logs.

func (InputID) MarshalJSON 

func (id InputID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Input ID.

func (InputID) Redacted 

func (id InputID) Redacted() string

Redacted returns a safe diagnostic Input ID.

func (InputID) String 

func (id InputID) String() string

String returns the canonical Input ID.

func (*InputID) UnmarshalJSON 

func (id *InputID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates an Input ID.

type ModelUsage 

type ModelUsage struct {
	InputTokens  *uint64 `json:"input_tokens,omitempty"`
	OutputTokens *uint64 `json:"output_tokens,omitempty"`
}

ModelUsage retains provider-neutral token accounting for the latest recorded model invocation. Nil values remain unknown; they are never coerced to zero.

func (*ModelUsage) Clone 

func (usage *ModelUsage) Clone() *ModelUsage

Clone returns an independent ModelUsage snapshot.

type Policy 

type Policy struct {
	Name      string       `json:"name"`
	Revision  uint64       `json:"revision"`
	Digest    string       `json:"digest"`
	Rules     []PolicyRule `json:"rules"`
	CreatedAt time.Time    `json:"created_at"`
}

Policy is one immutable, versioned tenant authorization policy. Tool execution consumes its durable revision digest; it never receives policy administration authority.

func (Policy) Clone 

func (policy Policy) Clone() Policy

Clone returns an independent immutable Policy snapshot.

type PolicyDecision 

type PolicyDecision string

PolicyDecision is the closed disposition an immutable Policy revision gives one named Tool. It conveys no credential or executable capability. 

const (
	// PolicyDenied prevents the named Tool from receiving execution authority.
	PolicyDenied PolicyDecision = "denied"
	// PolicyRequiresApproval requires a later durable human decision before the
	// named Tool can receive a bounded capability grant.
	PolicyRequiresApproval PolicyDecision = "requires_approval"
)

type PolicyRule 

type PolicyRule struct {
	ToolName string         `json:"tool_name"`
	Decision PolicyDecision `json:"decision"`
}

PolicyRule is one bounded, model-independent authorization rule for a named Tool.

type RequestID 

type RequestID string

RequestID correlates one HTTP attempt without identifying durable work.

func ParseRequestID 

func ParseRequestID(value string) (RequestID, error)

ParseRequestID validates an externally supplied request correlation ID.

func (RequestID) LogValue 

func (id RequestID) LogValue() slog.Value

LogValue returns a redacted request correlation ID for structured logs.

func (RequestID) MarshalJSON 

func (id RequestID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated request correlation ID.

func (RequestID) Redacted 

func (id RequestID) Redacted() string

Redacted returns a safe diagnostic request correlation ID.

func (RequestID) String 

func (id RequestID) String() string

String returns the canonical request correlation ID.

func (*RequestID) UnmarshalJSON 

func (id *RequestID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a request correlation ID.

type RequestIDSource 

type RequestIDSource interface {
	// NextRequestID creates one fresh opaque correlation ID.
	NextRequestID() (RequestID, error)
}

RequestIDSource creates a fresh opaque correlation ID for each HTTP attempt.

type ReviseAgentRequest 

type ReviseAgentRequest struct {
	AgentID        AgentID          `json:"agent_id"`
	IdempotencyKey string           `json:"idempotency_key"`
	ModelProfile   string           `json:"model_profile"`
	Instructions   string           `json:"instructions"`
	Tools          []ToolDefinition `json:"tools,omitempty"`
}

ReviseAgentRequest creates another immutable revision of an existing Agent.

type RevisePolicyRequest 

type RevisePolicyRequest struct {
	IdempotencyKey   string       `json:"idempotency_key"`
	Name             string       `json:"name"`
	ExpectedRevision uint64       `json:"expected_revision"`
	Rules            []PolicyRule `json:"rules"`
}

RevisePolicyRequest creates the next immutable revision of one named Policy.

type RuntimeClient 

type RuntimeClient interface {
	// CreateAgent creates the first immutable Agent revision through the admin surface.
	CreateAgent(context.Context, CreateAgentRequest) (AgentSpecification, error)
	// ReviseAgent creates another immutable Agent revision through the admin surface.
	ReviseAgent(context.Context, ReviseAgentRequest) (AgentSpecification, error)
	// GetAgentRevision reads one immutable Agent revision through the admin surface.
	GetAgentRevision(context.Context, AgentID, AgentRevisionID) (AgentSpecification, error)
	// CreatePolicy creates the first immutable revision of a tenant Policy.
	CreatePolicy(context.Context, CreatePolicyRequest) (Policy, error)
	// RevisePolicy creates the next immutable revision of a tenant Policy.
	RevisePolicy(context.Context, RevisePolicyRequest) (Policy, error)
	// GetPolicy reads one immutable Policy revision through the admin surface.
	GetPolicy(context.Context, string, uint64) (Policy, error)
	// ReadArtifact downloads one caller-authorized immutable artifact.
	ReadArtifact(context.Context, ArtifactID) (ArtifactDownload, error)
	// InspectApproval returns the caller-authorized state of one Approval.
	InspectApproval(context.Context, ApprovalID) (Approval, error)
	// ListApprovals returns the caller-authorized bounded Approval inbox.
	ListApprovals(context.Context) (ApprovalPage, error)
	// DecideApproval records one idempotent owner decision for a pending Approval.
	DecideApproval(context.Context, DecideApprovalRequest) (Approval, error)
	// IdempotencyStatus reads one retained receipt without re-executing work.
	IdempotencyStatus(context.Context, string) (IdempotencyStatus, error)
	// CreateSession creates a principal-owned Session pinned to one Agent revision.
	CreateSession(context.Context, CreateSessionRequest) (Session, error)
	// SendInput idempotently admits bounded Input into a Session.
	SendInput(context.Context, SendInputRequest) (SendInputResult, error)
	// InspectSession returns caller-safe Session state without backend identifiers.
	InspectSession(context.Context, SessionID) (SessionView, error)
	// InspectTurn returns one caller-safe Turn snapshot.
	InspectTurn(context.Context, SessionID, TurnID) (Turn, error)
	// Events resumes bounded Product-event observation after an opaque Cursor.
	Events(context.Context, SessionID, Cursor, int) (EventPage, error)
	// CancelTurn explicitly requests durable Turn cancellation.
	CancelTurn(context.Context, CancelTurnRequest) (Turn, error)
	// CloseSession closes Input admission and drains accepted work.
	CloseSession(context.Context, CloseSessionRequest) (Session, error)
}

RuntimeClient is the Temporal-free application contract for durable Agent Runtime commands.

type SendInputRequest 

type SendInputRequest struct {
	SessionID      SessionID     `json:"session_id"`
	IdempotencyKey string        `json:"idempotency_key"`
	Parts          []ContentPart `json:"parts"`
}

SendInputRequest idempotently submits bounded content to a Session.

type SendInputResult 

type SendInputResult struct {
	Input Input `json:"input"`
	Turn  Turn  `json:"turn"`
}

SendInputResult identifies both the accepted Input and its exactly-one Turn.

type Session 

type Session struct {
	ID            SessionID       `json:"id"`
	AgentID       AgentID         `json:"agent_id"`
	AgentRevision AgentRevisionID `json:"agent_revision_id"`
	State         SessionState    `json:"state"`
	CreatedAt     time.Time       `json:"created_at"`
	UpdatedAt     time.Time       `json:"updated_at"`
}

Session is an immutable caller snapshot of a durable Session.

type SessionArtifactLister 

type SessionArtifactLister interface {
	// ListSessionArtifacts returns bounded metadata only; bytes require a
	// separate caller-authorized Artifact read.
	ListSessionArtifacts(context.Context, SessionID) (ArtifactPage, error)
}

SessionArtifactLister is the additive public capability for discovering a caller's immutable artifacts for one exact Session.

type SessionCanceller 

type SessionCanceller interface {
	// CancelSession terminally cancels a drained Session.
	CancelSession(context.Context, CancelSessionRequest) (Session, error)
}

SessionCanceller is the additive public capability for caller-owned cancellation of a drained Session. It remains separate from RuntimeClient so existing v1 client implementations keep their source compatibility.

type SessionID 

type SessionID string

SessionID identifies a durable Session.

func ParseSessionID 

func ParseSessionID(value string) (SessionID, error)

ParseSessionID validates an externally supplied Session ID.

func (SessionID) LogValue 

func (id SessionID) LogValue() slog.Value

LogValue returns a redacted Session ID for structured logs.

func (SessionID) MarshalJSON 

func (id SessionID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Session ID.

func (SessionID) Redacted 

func (id SessionID) Redacted() string

Redacted returns a safe diagnostic Session ID.

func (SessionID) String 

func (id SessionID) String() string

String returns the canonical Session ID.

func (*SessionID) UnmarshalJSON 

func (id *SessionID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a Session ID.

type SessionState 

type SessionState string

SessionState is the durable lifecycle state of a Session. 

const (
	// SessionOpen accepts Input and may run a Turn.
	SessionOpen SessionState = "open"
	// SessionClosing drains already accepted Input and rejects new Input.
	SessionClosing SessionState = "closing"
	// SessionCompleted has drained its accepted work.
	SessionCompleted SessionState = "completed"
	// SessionCancelled ended through explicit cancellation.
	SessionCancelled SessionState = "cancelled"
	// SessionFailed ended because the runtime could not safely continue.
	SessionFailed SessionState = "failed"
)

type SessionView 

type SessionView struct {
	Session              Session `json:"session"`
	ActiveTurn           *Turn   `json:"active_turn,omitempty"`
	QueuedTurns          []Turn  `json:"queued_turns,omitempty"`
	QueuedTurnCount      uint64  `json:"queued_turn_count"`
	QueuedTurnsTruncated bool    `json:"queued_turns_truncated"`
	RecentEvents         []Event `json:"recent_events,omitempty"`
}

SessionView contains only runtime-owned public Session state and references.

func (SessionView) Clone 

func (view SessionView) Clone() SessionView

Clone returns an independent Session inspection snapshot.

type StaticBearerCredential 

type StaticBearerCredential struct {
	// contains filtered or unexported fields
}

StaticBearerCredential is a redacted in-memory credential adapter for explicitly supplied tokens.

func NewStaticBearerCredential 

func NewStaticBearerCredential(token string) (*StaticBearerCredential, error)

NewStaticBearerCredential validates and owns a copy of one bearer token.

func (*StaticBearerCredential) Authorize 

func (credential *StaticBearerCredential) Authorize(ctx context.Context, sink AuthorizationSink) error

Authorize applies the credential to one request-scoped sink.

func (*StaticBearerCredential) GoString 

func (credential *StaticBearerCredential) GoString() string

GoString keeps detailed formatter diagnostics secret-safe.

func (*StaticBearerCredential) String 

func (credential *StaticBearerCredential) String() string

String returns a secret-safe credential diagnostic.

type ToolCall 

type ToolCall struct {
	ID        string           `json:"id"`
	Name      string           `json:"name"`
	State     ToolCallState    `json:"state"`
	Approval  *Approval        `json:"approval,omitempty"`
	Grant     *CapabilityGrant `json:"grant,omitempty"`
	Execution *ToolExecution   `json:"execution,omitempty"`
	CreatedAt time.Time        `json:"created_at"`
}

ToolCall is a caller-safe model intent and its derived authorization/execution state.

func (ToolCall) Clone 

func (call ToolCall) Clone() ToolCall

Clone returns an independent ToolCall snapshot.

type ToolCallInspector 

type ToolCallInspector interface {
	// InspectToolCalls returns bounded safe Tool intent, approval, grant, and execution projections.
	InspectToolCalls(context.Context, SessionID, TurnID) (ToolCallPage, error)
}

ToolCallInspector is the additive public capability for owner-scoped Tool-call inspection.

type ToolCallPage 

type ToolCallPage struct {
	Calls     []ToolCall `json:"calls"`
	Truncated bool       `json:"truncated"`
}

ToolCallPage is one bounded owner-scoped Tool-call inspection result.

func (ToolCallPage) Clone 

func (page ToolCallPage) Clone() ToolCallPage

Clone returns an independent ToolCallPage snapshot.

type ToolCallState 

type ToolCallState string

ToolCallState is the safe public lifecycle of one model Tool intent. 

const (
	// ToolCallIntent records model intent without execution authority.
	ToolCallIntent ToolCallState = "intent"
	// ToolCallAwaitingApproval awaits a permitted human decision.
	ToolCallAwaitingApproval ToolCallState = "awaiting_approval"
	// ToolCallAuthorized has a bounded capability grant but no execution outcome.
	ToolCallAuthorized ToolCallState = "authorized"
	// ToolCallExecuting has committed a capability-bound execution intent.
	ToolCallExecuting ToolCallState = "executing"
	// ToolCallSucceeded has a durable terminal successful observation.
	ToolCallSucceeded ToolCallState = "succeeded"
	// ToolCallFailed has a durable terminal safe failure.
	ToolCallFailed ToolCallState = "failed"
	// ToolCallUncertain has an unresolved external-effect outcome.
	ToolCallUncertain ToolCallState = "uncertain"
)

type ToolDefinition 

type ToolDefinition struct {
	Name               string          `json:"name"`
	Description        string          `json:"description"`
	InputSchemaVersion string          `json:"input_schema_version,omitempty"`
	InputSchema        json.RawMessage `json:"input_schema,omitempty"`
}

ToolDefinition describes model-visible intent without granting execution authority.

type ToolExecution 

type ToolExecution struct {
	State ToolCallState `json:"state"`
	// Result is the immutable owner-readable artifact produced by a successful
	// tool execution. It is absent for failed, uncertain, and in-progress work.
	Result      *ArtifactReference `json:"result,omitempty"`
	Failure     *Failure           `json:"failure,omitempty"`
	CreatedAt   time.Time          `json:"created_at"`
	CompletedAt *time.Time         `json:"completed_at,omitempty"`
}

ToolExecution is a caller-safe terminal or in-progress tool observation.

func (*ToolExecution) Clone 

func (execution *ToolExecution) Clone() *ToolExecution

Clone returns an independent ToolExecution snapshot.

type Turn 

type Turn struct {
	ID          TurnID      `json:"id"`
	InputID     InputID     `json:"input_id"`
	Position    uint64      `json:"position"`
	State       TurnState   `json:"state"`
	StartedAt   *time.Time  `json:"started_at,omitempty"`
	CompletedAt *time.Time  `json:"completed_at,omitempty"`
	Failure     *Failure    `json:"failure,omitempty"`
	Usage       *ModelUsage `json:"usage,omitempty"`
	// Output is the owner-readable immutable finalized model output, when the
	// model invocation reached a durable successful terminal outcome.
	Output *ArtifactReference `json:"output,omitempty"`
}

Turn is an immutable snapshot of one durable progression from Input to outcome.

func (Turn) Clone 

func (turn Turn) Clone() Turn

Clone returns an independent Turn snapshot.

type TurnID 

type TurnID string

TurnID identifies one durable Turn.

func ParseTurnID 

func ParseTurnID(value string) (TurnID, error)

ParseTurnID validates an externally supplied Turn ID.

func (TurnID) LogValue 

func (id TurnID) LogValue() slog.Value

LogValue returns a redacted Turn ID for structured logs.

func (TurnID) MarshalJSON 

func (id TurnID) MarshalJSON() ([]byte, error)

MarshalJSON encodes a validated Turn ID.

func (TurnID) Redacted 

func (id TurnID) Redacted() string

Redacted returns a safe diagnostic Turn ID.

func (TurnID) String 

func (id TurnID) String() string

String returns the canonical Turn ID.

func (*TurnID) UnmarshalJSON 

func (id *TurnID) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a Turn ID.

type TurnState 

type TurnState string

TurnState is the durable lifecycle state of one Turn. 

const (
	// TurnQueued is durably ordered behind an active Turn.
	TurnQueued TurnState = "queued"
	// TurnRunning is the only Turn currently allowed to progress a Session.
	TurnRunning TurnState = "running"
	// TurnWaitingForApproval has durably paused one active Turn at a bounded
	// human-approval boundary. It is non-terminal and remains cancellable.
	TurnWaitingForApproval TurnState = "waiting_for_approval"
	// TurnSucceeded completed successfully.
	TurnSucceeded TurnState = "succeeded"
	// TurnFailed completed with a safe Failure.
	TurnFailed TurnState = "failed"
	// TurnCancelled completed after explicit cancellation.
	TurnCancelled TurnState = "cancelled"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.