wire

package
v0.8.1-alpha.12 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package wire defines the internal JSON protocol exchanged by agent runtimes and Airlock. It is not the author-facing Agents SDK API.

Index

Constants

View Source
const (
	SourceStateHeader      = "X-Airlock-Source-State"
	SourceRevisionHeader   = "X-Airlock-Source-Revision"
	SourceGenerationHeader = "X-Airlock-Source-Generation"
	SourceTaskHeader       = "X-Airlock-Task-ID"
)
View Source
const (
	ErrorKindPlatform = "platform"
	ErrorKindAgent    = "agent"
)
View Source
const AppRuntimeProtocol = "airlock.app-runtime.v3"

AppRuntimeProtocol identifies the app capability execution contract, independent of SDK semver and the JavaScript executor's framed protocol.

View Source
const CallerHeader = "X-Airlock-Caller"
View Source
const CandidateConfigHeader = "X-Airlock-Candidate-Config"
View Source
const ConnectionResponseSourceHeader = "X-Airlock-Connection-Response-Source"

ConnectionResponseSourceHeader identifies whether a proxy response was produced by Airlock or received from the configured upstream. Airlock strips this header from upstream responses before setting its own value.

View Source
const EnqueueJobErrorCodeUnavailable = "enqueue_unavailable"
View Source
const ExpectedSourceRevisionHeader = "X-Airlock-Expected-Source-Revision"
View Source
const InvocationTokenHeader = "X-Airlock-Invocation-Token"
View Source
const RuntimeInvokePath = "/__air/runtime/invoke"
View Source
const TestExecutorContentType = "application/vnd.airlock.jsexec"

Variables

This section is empty.

Functions

func AgentDefinitionHash added in v0.7.0

func AgentDefinitionHash(def AgentDefinition) (string, error)

AgentDefinitionHash hashes the entire declaration except ContractHash. JSON object key order and whitespace are canonicalized; array order is significant.

func AgentReviewJobName added in v0.8.1

func AgentReviewJobName(slug string) string

AgentReviewJobName is the deterministic internal delivery contract name.

func CheckAppRuntimeProtocol added in v0.7.0

func CheckAppRuntimeProtocol(reported string) error

func EncodeCallerHeader added in v0.7.0

func EncodeCallerHeader(c Caller) (string, error)

func ResolveDisplayPart

func ResolveDisplayPart(part *DisplayPart)

func ValidateAgentDefinitions added in v0.7.0

func ValidateAgentDefinitions(manifest AgentManifest) error

ValidateAgentDefinitions validates private contracts and their manifest-local references, including exact hashes and a maximum of one child level.

func ValidateRouteTools

func ValidateRouteTools(manifest AgentManifest) error

ValidateRouteTools checks correspondence against the same manifest's app tools. Tool names are app-local identities; access policies are independent.

Types

type Access

type Access string
const (
	AccessAdmin    Access = "admin"
	AccessUser     Access = "user"
	AccessPublic   Access = "public"
	AccessInternal Access = "internal"
)

type Action

type Action struct {
	Type       string    `json:"type"`
	Timestamp  time.Time `json:"timestamp"`
	DurationMs int64     `json:"durationMs"`
	Request    any       `json:"request,omitempty"`
	Response   any       `json:"response,omitempty"`
	Error      string    `json:"error,omitempty"`
}

type AgentArtifact added in v0.8.1

type AgentArtifact struct {
	Path        string `json:"path"`
	ID          string `json:"id,omitempty"`
	ContentID   string `json:"contentId,omitempty"`
	SHA256      string `json:"sha256,omitempty"`
	ContentType string `json:"contentType,omitempty"`
	Size        int64  `json:"size,omitempty"`
}

AgentArtifact is a host-resolved immutable content reference. Model submissions supply only Path and optional ContentID/SHA256 assertions.

type AgentBudget added in v0.7.0

type AgentBudget struct {
	Steps     int64 `json:"steps,omitempty"`
	TimeoutMS int64 `json:"timeoutMs,omitempty"`
	Tokens    int64 `json:"tokens,omitempty"`
}

type AgentCallsRequest added in v0.7.0

type AgentCallsRequest struct {
	IDs []string `json:"ids"`
}

type AgentCancelResult added in v0.7.0

type AgentCancelResult struct {
	Calls []AgentRunInfo `json:"calls"`
}

type AgentCapability added in v0.8.1

type AgentCapability string

AgentCapability is a canonical capability ID, never a JS or direct-tool alias.

const (
	CapabilityFileRead           AgentCapability = "air//file_read"
	CapabilityFileReadBytes      AgentCapability = "air//file_read_bytes"
	CapabilityFileReadRangeBytes AgentCapability = "air//file_read_range_bytes"
	CapabilityFileGrep           AgentCapability = "air//file_grep"
	CapabilityFileHead           AgentCapability = "air//file_head"
	CapabilityFileTail           AgentCapability = "air//file_tail"
	CapabilityFileLines          AgentCapability = "air//file_lines"
	CapabilityFileStat           AgentCapability = "air//file_stat"
	CapabilityFileExists         AgentCapability = "air//file_exists"
	CapabilityFileWrite          AgentCapability = "air//file_write"
	CapabilityFileDelete         AgentCapability = "air//file_delete"
	CapabilityFileList           AgentCapability = "air//file_list"
	CapabilityFileEncode         AgentCapability = "air//file_encode"
	CapabilityFileDecode         AgentCapability = "air//file_decode"
	CapabilityFileDecodeText     AgentCapability = "air//file_decode_text"
	CapabilityFileEditLines      AgentCapability = "air//file_edit_lines"
	CapabilityFileSed            AgentCapability = "air//file_sed"
	CapabilityQueryDB            AgentCapability = "air//query_db"
	CapabilityOutput             AgentCapability = "air//output"
	CapabilityFileShareURL       AgentCapability = "air//file_share_url"
	CapabilityHTTPRequest        AgentCapability = "air//http_request"
	CapabilityWebSearch          AgentCapability = "air//web_search"
	CapabilityAttachToContext    AgentCapability = "air//attach_to_context"
	CapabilityAnalyzeImage       AgentCapability = "air//analyze_image"
	CapabilityTranscribeAudio    AgentCapability = "air//transcribe_audio"
	CapabilityGenerateImage      AgentCapability = "air//generate_image"
	CapabilitySpeak              AgentCapability = "air//speak"
	CapabilityEmbed              AgentCapability = "air//embed"
	CapabilityRequestUpgrade     AgentCapability = "air//request_upgrade"
)

type AgentCapabilityPolicy added in v0.8.1

type AgentCapabilityPolicy struct {
	Allow []AgentCapability `json:"allow"`
}

AgentCapabilityPolicy restricts generic operations. Private tools and bound MCPs are selected by the definition's own declarations, not by this list. An absent policy preserves the unrestricted generic inventory. An explicit policy with no entries permits no generic operations.

type AgentDefinition added in v0.7.0

type AgentDefinition struct {
	Slug                   string                 `json:"slug"`
	Description            string                 `json:"description"`
	Instructions           string                 `json:"instructions"`
	ModelSlot              string                 `json:"modelSlot"`
	Capabilities           *AgentCapabilityPolicy `json:"capabilities,omitempty"`
	InputSchema            json.RawMessage        `json:"inputSchema"`
	OutputSchema           json.RawMessage        `json:"outputSchema"`
	ContractHash           string                 `json:"contractHash"`
	Tools                  []AgentToolDefinition  `json:"tools,omitempty"`
	MCPs                   []string               `json:"mcps,omitempty"`
	Subagents              []string               `json:"subagents,omitempty"`
	Budget                 AgentBudget            `json:"budget"`
	MaxAttempts            int32                  `json:"maxAttempts"`
	MaxConcurrency         int32                  `json:"maxConcurrency"`
	MaxSubagentCalls       int32                  `json:"maxSubagentCalls"`
	MaxConcurrentSubagents int32                  `json:"maxConcurrentSubagents"`
	Review                 *AgentReviewPolicy     `json:"review,omitempty"`
}

type AgentManifest added in v0.5.0

type AgentManifest struct {
	RuntimeProtocol  string             `json:"runtimeProtocol"`
	Version          string             `json:"version"`
	Description      string             `json:"description"`
	Emoji            string             `json:"emoji"`
	Tools            []ToolDef          `json:"tools"`
	Webhooks         []WebhookDef       `json:"webhooks"`
	JobHandlers      []JobHandlerDef    `json:"jobHandlers"`
	JobCrons         []JobCronDef       `json:"jobCrons"`
	Routes           []RouteDef         `json:"routes"`
	Topics           []TopicDef         `json:"topics"`
	MCPServers       []MCPDef           `json:"mcpServers"`
	Connections      []ConnectionDef    `json:"connections"`
	EnvVars          []EnvVarDef        `json:"envVars"`
	Directories      []DirectoryDef     `json:"directories"`
	Instructions     []InstructionDef   `json:"instructions"`
	ModelSlots       []ModelSlotDef     `json:"modelSlots"`
	StaticAssets     []StaticAssetDef   `json:"staticAssets"`
	StartupHooks     []StartupHookDef   `json:"startupHooks"`
	Connectors       []ConnectorNeedDef `json:"connectors"`
	AgentDefinitions []AgentDefinition  `json:"agentDefinitions,omitempty"`
}

AgentManifest is the complete canonical declaration of an agent image. The SDK emits it in offline manifest mode and sends the same value during runtime synchronization. Slices are deterministically ordered by their identifiers, except Instructions and StartupHooks, whose registration order is semantic.

type AgentReply added in v0.7.0

type AgentReply struct {
	Kind      string          `json:"kind"`
	Output    json.RawMessage `json:"output,omitempty"`
	Question  string          `json:"question,omitempty"`
	Artifacts []AgentArtifact `json:"artifacts,omitempty"`
}

type AgentReviewDecision added in v0.8.1

type AgentReviewDecision struct {
	Kind     string `json:"kind"`
	Feedback string `json:"feedback,omitempty"`
}

type AgentReviewPolicy added in v0.8.1

type AgentReviewPolicy struct {
	Version        int32  `json:"version"`
	TimeoutMS      int64  `json:"timeoutMs"`
	MaxAttempts    int32  `json:"maxAttempts"`
	MaxConcurrency int32  `json:"maxConcurrency"`
	MaxCorrections int32  `json:"maxCorrections"`
	JobName        string `json:"jobName"`
}

type AgentReviewRequest added in v0.8.1

type AgentReviewRequest struct {
	Definition   string          `json:"definition"`
	ContractHash string          `json:"contractHash"`
	Submission   AgentSubmission `json:"submission"`
}

type AgentRunInfo added in v0.7.0

type AgentRunInfo struct {
	ID           string      `json:"id"`
	SessionID    string      `json:"sessionId"`
	Definition   string      `json:"definition"`
	ContractHash string      `json:"contractHash"`
	Status       string      `json:"status"`
	Error        string      `json:"error,omitempty"`
	Reply        *AgentReply `json:"reply,omitempty"`
	Steps        int64       `json:"steps"`
	Tokens       int64       `json:"tokens"`
	CreatedAt    time.Time   `json:"createdAt"`
	UpdatedAt    time.Time   `json:"updatedAt"`
	StartedAt    *time.Time  `json:"startedAt,omitempty"`
	CompletedAt  *time.Time  `json:"completedAt,omitempty"`
}

type AgentRunResponse added in v0.7.0

type AgentRunResponse struct {
	Run     AgentRunInfo `json:"run"`
	Created bool         `json:"created"`
}

type AgentSubmission added in v0.8.1

type AgentSubmission struct {
	ID           string               `json:"id"`
	RunID        string               `json:"runId"`
	SessionID    string               `json:"sessionId"`
	ToolCallID   string               `json:"toolCallId"`
	ContractHash string               `json:"contractHash"`
	Revision     int64                `json:"revision"`
	Input        json.RawMessage      `json:"input"`
	Output       json.RawMessage      `json:"output"`
	Artifacts    []AgentArtifact      `json:"artifacts,omitempty"`
	Decision     *AgentReviewDecision `json:"decision,omitempty"`
}

type AgentToolDefinition added in v0.7.0

type AgentToolDefinition struct {
	Name          string            `json:"name"`
	Description   string            `json:"description"`
	LLMHint       string            `json:"llmHint,omitempty"`
	InputSchema   json.RawMessage   `json:"inputSchema"`
	OutputSchema  json.RawMessage   `json:"outputSchema"`
	InputExamples []json.RawMessage `json:"inputExamples,omitempty"`
}

type AgentWaitRequest added in v0.7.0

type AgentWaitRequest struct {
	IDs       []string `json:"ids"`
	Mode      string   `json:"mode"`
	TimeoutMS *int64   `json:"timeoutMs,omitempty"`
}

type AgentWaitResult added in v0.7.0

type AgentWaitResult struct {
	Reason    string         `json:"reason"`
	Completed []AgentRunInfo `json:"completed"`
	Pending   []string       `json:"pending"`
}

type AuthInjection

type AuthInjection struct {
	Type AuthInjectionType `json:"type"`
	Name string            `json:"name,omitempty"`
}

type AuthInjectionType

type AuthInjectionType string
const (
	AuthInjectBearer     AuthInjectionType = "bearer"
	AuthInjectAPIKey     AuthInjectionType = "api_key_header"
	AuthInjectPathPrefix AuthInjectionType = "path_prefix"
	AuthInjectQueryParam AuthInjectionType = "query_param"
)

type BindingMode added in v0.8.1

type BindingMode string
const (
	BindingShared  BindingMode = "shared"
	BindingPerUser BindingMode = "per_user"
)

type Caller added in v0.7.0

type Caller struct {
	Kind      string       `json:"kind"`
	Access    Access       `json:"access"`
	User      *CallerUser  `json:"user,omitempty"`
	Initiator *CallerUser  `json:"initiator,omitempty"`
	Origin    CallerOrigin `json:"origin"`
}

Caller is host-attributed execution metadata, not an authentication credential.

func DecodeCallerHeader added in v0.7.0

func DecodeCallerHeader(headers http.Header) (Caller, error)

func (Caller) Validate added in v0.7.0

func (c Caller) Validate() error

Validate checks metadata consistency without establishing authority or resolving identity.

type CallerOrigin added in v0.7.0

type CallerOrigin struct {
	Interface string `json:"interface"`
	Platform  string `json:"platform"`
	ClientID  string `json:"clientId"`
	Execution string `json:"execution"`
}

type CallerUser added in v0.7.0

type CallerUser struct {
	ID             string `json:"id"`
	Email          string `json:"email"`
	DisplayName    string `json:"displayName"`
	PlatformMember bool   `json:"platformMember"`
}

type CandidateConfig added in v0.8.1

type CandidateConfig struct {
	Version    int                  `json:"version"`
	Selections []CandidateSelection `json:"selections"`
}

CandidateConfig selects resources from the candidate's own declarations. Source admission stores the plan; only the host commits it at candidate cutover.

func (CandidateConfig) HeaderValue added in v0.8.1

func (c CandidateConfig) HeaderValue() (string, error)

type CandidateSelection added in v0.8.1

type CandidateSelection struct {
	Type        string `json:"type"`
	Slug        string `json:"slug"`
	ResourceID  string `json:"resourceId,omitempty"`
	FixtureName string `json:"fixtureName,omitempty"`
}

type Capabilities

type Capabilities struct {
	Vision        bool `json:"vision,omitempty"`
	Transcription bool `json:"transcription,omitempty"`
	Speech        bool `json:"speech,omitempty"`
	Embedding     bool `json:"embedding,omitempty"`
	Image         bool `json:"image,omitempty"`
	Search        bool `json:"search,omitempty"`
}

type ConnectionAuth

type ConnectionAuth string
const (
	ConnectionAuthOAuth ConnectionAuth = "oauth"
	ConnectionAuthToken ConnectionAuth = "token"
	ConnectionAuthNone  ConnectionAuth = "none"
)

type ConnectionDef

type ConnectionDef struct {
	Slug              string            `json:"slug,omitempty"`
	Name              string            `json:"name"`
	Description       string            `json:"description"`
	BaseURL           string            `json:"baseUrl,omitempty"`
	AuthMode          ConnectionAuth    `json:"authMode"`
	AuthURL           string            `json:"authUrl,omitempty"`
	TokenURL          string            `json:"tokenUrl,omitempty"`
	Scopes            []string          `json:"scopes,omitempty"`
	AuthParams        map[string]string `json:"authParams,omitempty"`
	Headers           map[string]string `json:"headers,omitempty"`
	AuthInjection     AuthInjection     `json:"authInjection"`
	SetupInstructions string            `json:"setupInstructions,omitempty"`
	LLMHint           string            `json:"llmHint,omitempty"`
	BindingMode       BindingMode       `json:"bindingMode"`
}

type ConnectionErrorCode added in v0.8.1

type ConnectionErrorCode string
const (
	ConnectionErrorCodeAuthorizationRequired ConnectionErrorCode = "authorization_required"
	ConnectionErrorCodeInvalidRequest        ConnectionErrorCode = "invalid_request"
	ConnectionErrorCodeUnauthorized          ConnectionErrorCode = "unauthorized"
	ConnectionErrorCodeForbidden             ConnectionErrorCode = "forbidden"
	ConnectionErrorCodeNotBound              ConnectionErrorCode = "not_bound"
	ConnectionErrorCodeConflict              ConnectionErrorCode = "conflict"
	ConnectionErrorCodeGateway               ConnectionErrorCode = "gateway"
	ConnectionErrorCodeGatewayTimeout        ConnectionErrorCode = "gateway_timeout"
	ConnectionErrorCodeInternal              ConnectionErrorCode = "internal"
)

type ConnectionErrorResponse added in v0.8.1

type ConnectionErrorResponse struct {
	Error    string              `json:"error"`
	Code     ConnectionErrorCode `json:"code"`
	Slug     string              `json:"slug,omitempty"`
	ConnName string              `json:"connName,omitempty"`
	AuthURL  string              `json:"authUrl,omitempty"`
}

ConnectionErrorResponse is the host-produced non-2xx response body for the connection proxy. Upstream response bodies retain their original format.

type ConnectionResponseSource added in v0.8.1

type ConnectionResponseSource string
const (
	ConnectionResponseSourceHost     ConnectionResponseSource = "host"
	ConnectionResponseSourceUpstream ConnectionResponseSource = "upstream"
)

type ConnectorJobInfo added in v0.6.0

type ConnectorJobInfo struct {
	JobID      string                 `json:"jobId"`
	ResourceID string                 `json:"resourceId,omitempty"`
	Status     string                 `json:"status"`
	Output     json.RawMessage        `json:"output,omitempty"`
	Error      string                 `json:"error,omitempty"`
	Progress   *ConnectorJobProgress  `json:"progress,omitempty"`
	History    []ConnectorJobProgress `json:"history"`
}

type ConnectorJobProgress added in v0.6.0

type ConnectorJobProgress struct {
	Sequence        int64     `json:"sequence"`
	AttemptSequence int64     `json:"attemptSequence"`
	Phase           string    `json:"phase"`
	Message         string    `json:"message,omitempty"`
	Completed       int64     `json:"completed,omitempty"`
	Total           int64     `json:"total,omitempty"`
	Time            time.Time `json:"time"`
}

type ConnectorNeedDef added in v0.6.0

type ConnectorNeedDef struct {
	Slug        string               `json:"slug"`
	Description string               `json:"description"`
	Multiple    bool                 `json:"multiple,omitempty"`
	Requirement protocol.Requirement `json:"requirement"`
}

type ConnectorOrchestrationInfo added in v0.6.0

type ConnectorOrchestrationInfo struct {
	ID                   string             `json:"id"`
	Status               string             `json:"status"`
	Strategy             string             `json:"strategy"`
	CanaryPhase          string             `json:"canaryPhase"`
	CanaryCount          int32              `json:"canaryCount"`
	CanarySucceededCount int32              `json:"canarySucceededCount"`
	Targets              []ConnectorJobInfo `json:"targets"`
}

type ConnectorOrchestrationRequest added in v0.6.0

type ConnectorOrchestrationRequest struct {
	CommandName string                        `json:"commandName"`
	Request     protocol.OrchestrationRequest `json:"request"`
}

type ContinueAgentRequest added in v0.7.0

type ContinueAgentRequest struct {
	RequestID    string `json:"requestId"`
	ContractHash string `json:"contractHash"`
	Prompt       string `json:"prompt"`
}

type CreateRunRequest

type CreateRunRequest struct {
	TriggerType string `json:"triggerType"`
	TriggerRef  string `json:"triggerRef"`
}

type CreateRunResponse

type CreateRunResponse struct {
	RunID           string `json:"runId"`
	InvocationToken string `json:"invocationToken"`
	Caller          Caller `json:"caller"`
}

type DirectoryDef

type DirectoryDef struct {
	Path           string         `json:"path"`
	Read           Access         `json:"read"`
	Write          Access         `json:"write"`
	List           Access         `json:"list"`
	Description    string         `json:"description"`
	LLMHint        string         `json:"llmHint,omitempty"`
	RetentionHours int            `json:"retentionHours,omitempty"`
	Scope          DirectoryScope `json:"scope,omitempty"`
}

type DirectoryScope

type DirectoryScope string

type DisplayPart

type DisplayPart struct {
	Type     string  `json:"type"`
	Text     string  `json:"text,omitempty"`
	Source   string  `json:"source,omitempty"`
	URL      string  `json:"url,omitempty"`
	Data     []byte  `json:"data,omitempty"`
	Filename string  `json:"filename,omitempty"`
	MimeType string  `json:"mimeType,omitempty"`
	Alt      string  `json:"alt,omitempty"`
	Duration float64 `json:"duration,omitempty"`
}

type EnqueueJobErrorResponse added in v0.5.0

type EnqueueJobErrorResponse struct {
	Code           string `json:"code"`
	Error          string `json:"error"`
	HandlerName    string `json:"handlerName"`
	HandlerVersion int32  `json:"handlerVersion"`
}

EnqueueJobErrorResponse is returned with HTTP 409 when an exact job handler contract is temporarily unavailable during a deployment transition.

type EnqueueJobRequest added in v0.5.0

type EnqueueJobRequest struct {
	ID               string          `json:"id"`
	Name             string          `json:"name"`
	Version          int32           `json:"version"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
	Input            json.RawMessage `json:"input"`
	ScheduledAt      *time.Time      `json:"scheduledAt,omitempty"`
}

type EnqueueJobResponse added in v0.5.0

type EnqueueJobResponse struct {
	Job     JobInfo `json:"job"`
	Created bool    `json:"created"`
}

type EnvVarDef

type EnvVarDef struct {
	Slug        string `json:"slug,omitempty"`
	Description string `json:"description"`
	Secret      bool   `json:"secret"`
	Default     string `json:"default,omitempty"`
	Pattern     string `json:"pattern,omitempty"`
}

type EnvVarValueResponse

type EnvVarValueResponse struct {
	Value string `json:"value"`
}

type FileInfo

type FileInfo struct {
	Path         string    `json:"path"`
	Filename     string    `json:"filename"`
	ContentType  string    `json:"contentType"`
	Size         int64     `json:"size"`
	LastModified time.Time `json:"lastModified"`
}

type GetJobResponse added in v0.5.0

type GetJobResponse struct {
	Job JobInfo `json:"job"`
}

type HTTPRequest

type HTTPRequest struct {
	URL        string            `json:"url"`
	Method     string            `json:"method,omitempty"`
	Headers    map[string]string `json:"headers,omitempty"`
	Body       string            `json:"body,omitempty"`
	Timeout    int               `json:"timeout,omitempty"`
	SaveAs     string            `json:"saveAs,omitempty"`
	RunID      string            `json:"runId,omitempty"`
	Raw        bool              `json:"raw,omitempty"`
	AllHeaders bool              `json:"allHeaders,omitempty"`
}

type HTTPResponse

type HTTPResponse struct {
	Status      int               `json:"status"`
	Headers     map[string]string `json:"headers"`
	Body        string            `json:"body,omitempty"`
	ContentType string            `json:"contentType"`
	Size        int               `json:"size"`
	BodyPreview string            `json:"bodyPreview,omitempty"`
	SavedTo     string            `json:"savedTo,omitempty"`
	Note        string            `json:"note,omitempty"`
}

type InstructionDef

type InstructionDef struct {
	Text   string   `json:"text"`
	Access []Access `json:"access,omitempty"`
}

type JobCronDef added in v0.5.0

type JobCronDef struct {
	Slug             string          `json:"slug"`
	Schedule         string          `json:"schedule"`
	Description      string          `json:"description"`
	HandlerName      string          `json:"handlerName"`
	HandlerVersion   int32           `json:"handlerVersion"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
	Input            json.RawMessage `json:"input"`
}

type JobHandlerDef added in v0.5.0

type JobHandlerDef struct {
	Name             string          `json:"name"`
	Version          int32           `json:"version"`
	Description      string          `json:"description"`
	TimeoutMs        int64           `json:"timeoutMs"`
	MaxAttempts      int32           `json:"maxAttempts"`
	MaxConcurrency   int32           `json:"maxConcurrency"`
	InputSchema      json.RawMessage `json:"inputSchema"`
	OutputSchema     json.RawMessage `json:"outputSchema"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
}

type JobInfo added in v0.5.0

type JobInfo struct {
	ID               string          `json:"id"`
	AgentID          string          `json:"agentId"`
	HandlerName      string          `json:"handlerName"`
	HandlerVersion   int32           `json:"handlerVersion"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
	Status           string          `json:"status"`
	Input            json.RawMessage `json:"input"`
	Output           json.RawMessage `json:"output,omitempty"`
	AttemptCount     int32           `json:"attemptCount"`
	MaxAttempts      int32           `json:"maxAttempts"`
	AttemptLimit     int32           `json:"attemptLimit"`
	LastError        string          `json:"lastError,omitempty"`
	Progress         *JobProgress    `json:"progress,omitempty"`
	SourceRunID      string          `json:"sourceRunId,omitempty"`
	ScheduledAt      *time.Time      `json:"scheduledAt,omitempty"`
	CreatedAt        time.Time       `json:"createdAt"`
	UpdatedAt        time.Time       `json:"updatedAt"`
	StartedAt        *time.Time      `json:"startedAt,omitempty"`
	CompletedAt      *time.Time      `json:"completedAt,omitempty"`
}

type JobManifest added in v0.5.0

type JobManifest struct {
	JobHandlers []JobHandlerDef `json:"jobHandlers"`
	JobCrons    []JobCronDef    `json:"jobCrons"`
}

JobManifest is the canonical job declaration emitted by an agent image in job-manifest inspection mode. Both slices are ordered by their identifiers.

type JobProgress added in v0.5.0

type JobProgress struct {
	Phase     string `json:"phase"`
	Message   string `json:"message"`
	Completed int64  `json:"completed"`
	Total     int64  `json:"total"`
}

type JobRunRequest added in v0.5.0

type JobRunRequest struct {
	ID               string          `json:"id"`
	Name             string          `json:"name"`
	Version          int32           `json:"version"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
	Attempt          int32           `json:"attempt"`
	TimeoutMs        int64           `json:"timeoutMs"`
	Input            json.RawMessage `json:"input"`
	ScheduledAt      *time.Time      `json:"scheduledAt,omitempty"`
	Caller           Caller          `json:"caller"`
	ConversationID   string          `json:"conversationId"`
}

type JobRunResponse added in v0.5.0

type JobRunResponse struct {
	// Status is success, error, timeout, or retry. Retry reports a temporary
	// enqueue availability failure and asks Airlock to redeliver the attempt.
	Status string          `json:"status"`
	Output json.RawMessage `json:"output,omitempty"`
	Error  string          `json:"error,omitempty"`
}

type LLMProxyRequest

type LLMProxyRequest struct {
	Slug       string          `json:"slug,omitempty"`
	Capability string          `json:"capability,omitempty"`
	Options    json.RawMessage `json:"options"`
}

type ListAgentRunsResponse added in v0.7.0

type ListAgentRunsResponse struct {
	Runs       []AgentRunInfo `json:"runs"`
	NextCursor string         `json:"nextCursor,omitempty"`
}

type ListJobsResponse added in v0.5.0

type ListJobsResponse struct {
	Jobs       []JobInfo `json:"jobs"`
	NextCursor string    `json:"nextCursor,omitempty"`
}

type ListMembersResponse added in v0.7.0

type ListMembersResponse struct {
	Members    []Member `json:"members"`
	NextCursor string   `json:"nextCursor,omitempty"`
}

ListMembersResponse contains a page of deduplicated current-app members. Users with no direct or group-derived grant are excluded; public grants qualify. Each member has the highest effective access (admin > user > public).

type LogEntry

type LogEntry struct {
	Level   LogLevel `json:"level"`
	Message string   `json:"message"`
}

type LogLevel

type LogLevel string
const (
	LogLevelDebug LogLevel = "debug"
	LogLevelInfo  LogLevel = "info"
	LogLevelWarn  LogLevel = "warn"
	LogLevelError LogLevel = "error"
)

type MCPAuth

type MCPAuth string
const (
	MCPAuthOAuth          MCPAuth = "oauth"
	MCPAuthOAuthDiscovery MCPAuth = "oauth_discovery"
	MCPAuthToken          MCPAuth = "token"
	MCPAuthNone           MCPAuth = "none"
)

type MCPAuthStatus

type MCPAuthStatus struct {
	Slug         string  `json:"slug"`
	AuthMode     MCPAuth `json:"authMode"`
	Authorized   bool    `json:"authorized"`
	AuthURL      string  `json:"authUrl,omitempty"`
	Instructions string  `json:"instructions,omitempty"`
}

type MCPContent

type MCPContent struct {
	Type        string              `json:"type"`
	Text        string              `json:"text,omitempty"`
	URI         string              `json:"uri,omitempty"`
	Name        string              `json:"name,omitempty"`
	MimeType    string              `json:"mimeType,omitempty"`
	Data        string              `json:"data,omitempty"`
	Resource    *MCPResourceContent `json:"resource,omitempty"`
	Description string              `json:"description,omitempty"`
	Title       string              `json:"title,omitempty"`
	Annotations json.RawMessage     `json:"annotations,omitempty"`
	Icons       json.RawMessage     `json:"icons,omitempty"`
	Size        *int64              `json:"size,omitempty"`
	Meta        json.RawMessage     `json:"_meta,omitempty"`
}

type MCPDef

type MCPDef struct {
	Slug          string        `json:"slug,omitempty"`
	Name          string        `json:"name"`
	URL           string        `json:"url"`
	AuthMode      MCPAuth       `json:"authMode"`
	AuthURL       string        `json:"authUrl,omitempty"`
	TokenURL      string        `json:"tokenUrl,omitempty"`
	Scopes        []string      `json:"scopes,omitempty"`
	AuthInjection AuthInjection `json:"authInjection"`
	BindingMode   BindingMode   `json:"bindingMode"`
}

type MCPResourceContent added in v0.7.0

type MCPResourceContent struct {
	URI      string          `json:"uri"`
	MimeType string          `json:"mimeType,omitempty"`
	Text     string          `json:"text,omitempty"`
	Blob     string          `json:"blob,omitempty"`
	Meta     json.RawMessage `json:"_meta,omitempty"`
}

type MCPToolCallRequest

type MCPToolCallRequest struct {
	Tool      string          `json:"tool"`
	Arguments json.RawMessage `json:"arguments"`
}

type MCPToolCallResponse

type MCPToolCallResponse struct {
	Content           []MCPContent    `json:"content"`
	IsError           bool            `json:"isError"`
	StructuredContent json.RawMessage `json:"structuredContent,omitempty"`
	Meta              json.RawMessage `json:"_meta,omitempty"`
}

type MCPToolSchema

type MCPToolSchema struct {
	ServerSlug   string          `json:"serverSlug"`
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	InputSchema  json.RawMessage `json:"inputSchema"`
	OutputSchema json.RawMessage `json:"outputSchema,omitempty"`
}

type Member added in v0.7.0

type Member struct {
	User   MemberUser `json:"user"`
	Access Access     `json:"access"`
}

Member is a current-app identity and highest effective access snapshot across actual direct and group-derived grants, including public grants, not a credential.

type MemberUser added in v0.7.0

type MemberUser struct {
	ID             string `json:"id"`
	Email          string `json:"email"`
	DisplayName    string `json:"displayName"`
	PlatformMember bool   `json:"platformMember"`
}

MemberUser is directory metadata, not host-attributed execution identity.

type ModelProxyRequest

type ModelProxyRequest struct {
	Slug       string          `json:"slug,omitempty"`
	Capability string          `json:"capability"`
	Options    json.RawMessage `json:"options"`
}

type ModelSlotDef

type ModelSlotDef struct {
	Slug        string `json:"slug"`
	Capability  string `json:"capability"`
	Description string `json:"description,omitempty"`
}

type PrintRequest

type PrintRequest struct {
	Parts          []DisplayPart `json:"parts"`
	Topic          string        `json:"topic,omitempty"`
	ConversationID string        `json:"conversationId,omitempty"`
	RunID          string        `json:"runId,omitempty"`
	UserID         string        `json:"userId,omitempty"`
}

type PromptData

type PromptData struct {
	AgentDashboardURL   string       `json:"agentDashboardUrl"`
	AgentRouteURL       string       `json:"agentRouteUrl"`
	Capabilities        Capabilities `json:"capabilities,omitempty"`
	SupportedModalities []string     `json:"supportedModalities,omitempty"`
}

type PromptInput

type PromptInput struct {
	// RequestID is the stable admission UUID retained when retrying a human message.
	RequestID       string     `json:"requestId,omitempty"`
	Message         string     `json:"message,omitempty"`
	ConversationID  string     `json:"conversationId,omitempty"`
	Temperature     *float64   `json:"temperature,omitempty"`
	Files           []FileInfo `json:"files,omitempty"`
	ResumeRunID     string     `json:"resumeRunId,omitempty"`
	Approved        *bool      `json:"approved,omitempty"`
	Source          string     `json:"source,omitempty"`
	Instructions    string     `json:"instructions,omitempty"`
	CallerAccess    Access     `json:"callerAccess,omitempty"`
	ForceCompact    bool       `json:"forceCompact,omitempty"`
	DirectTools     bool       `json:"directTools,omitempty"`
	Platform        string     `json:"platform,omitempty"`
	UserDisplayName string     `json:"userDisplayName,omitempty"`
	UserEmail       string     `json:"userEmail,omitempty"`
}

type ProxyRequest

type ProxyRequest struct {
	Method  string            `json:"method"`
	Path    string            `json:"path"`
	Body    string            `json:"body,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
}

type RouteDef

type RouteDef struct {
	Path        string `json:"path"`
	Method      string `json:"method"`
	Access      Access `json:"access"`
	Description string `json:"description,omitempty"`
	ToolName    string `json:"tool_name,omitempty"`
}

type RunCompleteRequest

type RunCompleteRequest struct {
	JobID      string          `json:"jobId,omitempty"`
	Attempt    int32           `json:"attempt,omitempty"`
	LeaseToken string          `json:"leaseToken,omitempty"`
	RunID      string          `json:"runId"`
	Status     string          `json:"status"`
	Error      string          `json:"error,omitempty"`
	ErrorKind  string          `json:"errorKind,omitempty"`
	PanicTrace string          `json:"panicTrace,omitempty"`
	Actions    []Action        `json:"actions"`
	Logs       []LogEntry      `json:"logs,omitempty"`
	Checkpoint json.RawMessage `json:"checkpoint,omitempty"`
}

type RuntimeAgentDefinition added in v0.7.0

type RuntimeAgentDefinition struct {
	Slug         string `json:"slug"`
	ContractHash string `json:"contractHash"`
}

type RuntimeAttachment added in v0.7.0

type RuntimeAttachment struct {
	Path     string `json:"path"`
	MimeType string `json:"mimeType"`
	Filename string `json:"filename,omitempty"`
}

RuntimeAttachment references agent object storage, never inline file bytes.

type RuntimeContext added in v0.7.0

type RuntimeContext struct {
	AgentID             string                  `json:"agentId"`
	RunID               string                  `json:"runId"`
	InvocationToken     string                  `json:"invocationToken"`
	BridgeID            string                  `json:"bridgeId,omitempty"`
	ConversationID      string                  `json:"conversationId,omitempty"`
	Caller              Caller                  `json:"caller"`
	SupportedModalities []string                `json:"supportedModalities,omitempty"`
	Job                 *RuntimeJobContext      `json:"job,omitempty"`
	Definition          *RuntimeAgentDefinition `json:"definition,omitempty"`
	// TaskInput is the original admitted session-start input, supplied only by
	// the authenticated host. Continuation prompts and tool arguments are separate.
	TaskInput json.RawMessage `json:"taskInput,omitempty"`
}

RuntimeContext borrows an existing same-agent run. The app must not create or complete it. All attribution is supplied by the authenticated broker.

type RuntimeInvokeRequest added in v0.7.0

type RuntimeInvokeRequest struct {
	RuntimeProtocol string          `json:"runtimeProtocol"`
	CapabilityID    string          `json:"capabilityId"`
	ToolCallID      string          `json:"toolCallId"`
	Input           json.RawMessage `json:"input"`
	Context         RuntimeContext  `json:"context"`
}

RuntimeInvokeRequest is an internal broker-to-app call, authenticated with the target agent's bearer token. The broker must load the active run from shared storage, verify its agent ownership and authorize the selected capability before constructing this request. Never populate Context from public headers or accept a caller-supplied catalogue as an authorization source.

type RuntimeInvokeResponse added in v0.7.0

type RuntimeInvokeResponse struct {
	RuntimeProtocol string              `json:"runtimeProtocol"`
	Output          string              `json:"output"`
	Title           string              `json:"title,omitempty"`
	Metadata        map[string]any      `json:"metadata,omitempty"`
	Warnings        []string            `json:"warnings,omitempty"`
	Attachments     []RuntimeAttachment `json:"attachments,omitempty"`
	Logs            []LogEntry          `json:"logs,omitempty"`
	Actions         []Action            `json:"actions,omitempty"`
	Error           string              `json:"error,omitempty"`
}

RuntimeInvokeResponse retains the complete tool envelope and invocation-local telemetry. Airlock merges Actions and Logs into the borrowed run's record. Tool failures use Error with HTTP 200; protocol/auth failures use non-2xx.

type RuntimeJobContext added in v0.7.0

type RuntimeJobContext struct {
	ID         string `json:"id"`
	Attempt    int    `json:"attempt"`
	LeaseToken string `json:"leaseToken"`
}

type SealRequest

type SealRequest struct {
	Plaintext string `json:"plaintext"`
}

type SealResponse

type SealResponse struct {
	Sealed string `json:"sealed"`
}

type SearchProxyRequest

type SearchProxyRequest struct {
	Slug       string `json:"slug,omitempty"`
	Capability string `json:"capability,omitempty"`
	websearch.Request
}

type SessionAppendRequest

type SessionAppendRequest struct {
	Messages []session.Message `json:"messages"`
	Revision string            `json:"revision"`
}

type SessionAppendResponse

type SessionAppendResponse struct {
	Revision string `json:"revision"`
}

type SessionCompactRequest

type SessionCompactRequest struct {
	Summary     []session.Message `json:"summary"`
	TokensFreed int               `json:"tokensFreed"`
	Revision    string            `json:"revision"`
}

type SessionCompactResponse

type SessionCompactResponse struct {
	Revision string `json:"revision"`
}

type SessionLoadResponse

type SessionLoadResponse struct {
	Messages []session.Message `json:"messages"`
	Revision string            `json:"revision"`
}

type ShareFileRequest

type ShareFileRequest struct {
	Path           string `json:"path"`
	ExpiresSeconds int64  `json:"expiresSeconds,omitempty"`
}

type ShareFileResponse

type ShareFileResponse struct {
	URL         string `json:"url"`
	ExpiresAtMs int64  `json:"expiresAtMs"`
}

type SourceVersion added in v0.8.1

type SourceVersion struct {
	Revision   string
	Generation int64
}

SourceVersion is the canonical compare coordinate for application source. Revision identifies exact Git history; Generation changes only on deployment.

func ParseSourceETag added in v0.8.1

func ParseSourceETag(value string) (SourceVersion, error)

func (SourceVersion) ETag added in v0.8.1

func (v SourceVersion) ETag() string

type StartAgentRequest added in v0.7.0

type StartAgentRequest struct {
	RequestID    string          `json:"requestId"`
	ContractHash string          `json:"contractHash"`
	Input        json.RawMessage `json:"input"`
}

type StartupHookDef added in v0.5.0

type StartupHookDef struct {
	Name string `json:"name"`
}

type StaticAssetDef added in v0.5.0

type StaticAssetDef struct {
	Name        string `json:"name"`
	ContentType string `json:"contentType"`
	Size        int64  `json:"size"`
	SHA256      string `json:"sha256"`
}

type StorageFileRef added in v0.8.1

type StorageFileRef struct {
	ID          string `json:"id"`
	ContentID   string `json:"contentId"`
	Name        string `json:"name"`
	Path        string `json:"path"`
	ContentType string `json:"contentType"`
	Size        int64  `json:"size"`
}

type StorageFileRefRequest added in v0.8.1

type StorageFileRefRequest struct {
	Path string `json:"path"`
}

type StorageSetIndexRequest added in v0.8.1

type StorageSetIndexRequest struct {
	File StorageFileRef `json:"file"`
	Text string         `json:"text"`
}

type SyncRequest

type SyncRequest = AgentManifest

SyncRequest is the complete agent declaration accepted by runtime sync.

type SyncResponse

type SyncResponse struct {
	RuntimeProtocol   string                     `json:"runtimeProtocol"`
	PromptData        PromptData                 `json:"promptData"`
	MCPAuthStatus     []MCPAuthStatus            `json:"mcpAuthStatus,omitempty"`
	MCPSchemas        map[string][]MCPToolSchema `json:"mcpSchemas,omitempty"`
	PublicStorageBase string                     `json:"publicStorageBase,omitempty"`
}

type ToolDef

type ToolDef struct {
	Name               string            `json:"name"`
	Description        string            `json:"description"`
	LLMHint            string            `json:"llmHint,omitempty"`
	Access             Access            `json:"access"`
	InputSchema        json.RawMessage   `json:"inputSchema,omitempty"`
	OutputSchema       json.RawMessage   `json:"outputSchema,omitempty"`
	InputExamples      []json.RawMessage `json:"inputExamples,omitempty"`
	FileInputDirectory string            `json:"fileInputDirectory,omitempty"`
}

type TopicDef

type TopicDef struct {
	Slug        string          `json:"slug"`
	Description string          `json:"description"`
	LLMHint     string          `json:"llmHint,omitempty"`
	Access      Access          `json:"access"`
	PerUser     bool            `json:"perUser,omitempty"`
	Enrollment  TopicEnrollment `json:"enrollment,omitempty"`
}

type TopicEnrollment added in v0.7.0

type TopicEnrollment string
const (
	TopicEnrollmentDefaultOn  TopicEnrollment = "default_on"
	TopicEnrollmentDefaultOff TopicEnrollment = "default_off"
)

type TopicSubscriptionRequest added in v0.7.0

type TopicSubscriptionRequest struct {
	ConversationID string `json:"conversationId"`
}

type UnsealRequest

type UnsealRequest struct {
	Sealed string `json:"sealed"`
}

type UnsealResponse

type UnsealResponse struct {
	Plaintext string `json:"plaintext"`
}

type UpdateJobProgressRequest added in v0.5.0

type UpdateJobProgressRequest struct {
	Attempt   int32  `json:"attempt"`
	Phase     string `json:"phase"`
	Message   string `json:"message"`
	Completed int64  `json:"completed"`
	Total     int64  `json:"total"`
}

type UpgradeRequest added in v0.7.0

type UpgradeRequest struct {
	RunID       string `json:"runId"`
	Description string `json:"description"`
}

type WebhookDef

type WebhookDef struct {
	Path        string `json:"path"`
	Verify      string `json:"verify"`
	Header      string `json:"header,omitempty"`
	TimeoutMs   int64  `json:"timeoutMs"`
	Description string `json:"description,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL