agentsdk

type Access string

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 Agent struct {

	// Deps holds application-level dependencies (connection handles, MCP handles, etc.).
	// The builder defines their own typed struct and assigns it here.
	// Access from handlers via GetDeps[T](run).
	Deps any
	// contains filtered or unexported fields
}

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

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

type AnyTool interface {
	// contains filtered or unexported methods
}

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

type AuthInjectionType string

type AuthRequiredError struct {
	Slug     string `json:"slug"`
	ConnName string `json:"connName"`
	AuthURL  string `json:"authUrl"`
}

type Caller struct {
	Access Access
	UserID string // optional, for audit
	RunID  string // optional, for audit
}

type Capabilities struct {
	Vision        bool `json:"vision,omitempty"`        // chat with images — analyzeImage / multimodal attachToContext
	Transcription bool `json:"transcription,omitempty"` // speech-to-text — voice-note auto-transcribe + transcribe()
	Speech        bool `json:"speech,omitempty"`        // text-to-speech — speech()
	Embedding     bool `json:"embedding,omitempty"`     // vector embeddings — embed()
	Image         bool `json:"image,omitempty"`         // image generation — generateImage()
	Search        bool `json:"search,omitempty"`        // web search — webSearch()
}

type Config struct {
	Description string // required — shown to users in the Airlock UI
	// Emoji is an optional decorative glyph shown next to the agent in
	// the Airlock UI (agent list, sidebar, header). Purely cosmetic;
	// empty means "no emoji". A short grapheme is expected (a single
	// emoji incl. ZWJ / skin-tone / flag sequences) — it is NOT
	// validated to one rune; over-long/garbage values are dropped
	// server-side rather than failing the sync.
	Emoji string
}

type Connection struct {
	Slug        string // unique per agent; binds as conn_{slug} in run_js
	Name        string
	Description string
	BaseURL     string
	AuthMode    ConnectionAuth
	AuthURL     string
	TokenURL    string
	Scopes      []string
	// AuthParams are extra query parameters added to the OAuth
	// authorization request, overriding the platform defaults per key.
	// Optional escape hatch for providers whose refresh-token handshake
	// differs from the default.
	AuthParams map[string]string
	// Headers are static request headers Airlock sets on every proxied
	// call for this connection (User-Agent, Accept, X-Foo, …). Merged
	// per-key on top of the platform baseline (a real-browser UA); the
	// caller's per-call ProxyRequest.Headers merge on top in turn. Set a
	// value to the empty string to drop a baseline key entirely.
	Headers           map[string]string
	AuthInjection     AuthInjection
	SetupInstructions string
	LLMHint           string // appended to the connection block in the system prompt
	Access            Access // who may invoke conn_{slug}; default AccessUser
}

type ConnectionAuth string

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"`
	Access            Access            `json:"access,omitempty"`
}

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

type ConnectionResponse struct {
	StatusCode int
	Headers    http.Header
	Body       io.ReadCloser
}

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

type CreateRunResponse struct {
	RunID string `json:"runId"`
}

type Cron struct {
	Slug        string              // unique per agent (across crons + schedules)
	Schedule    string              // standard cron expression, e.g. "0 9 * * *"
	Handler     ScheduleHandlerFunc // required
	Timeout     time.Duration       // max execution time (default: 2 min)
	Description string
}

type DirPath string

type Directory struct {
	Path        string // S3-style path with no leading '/', e.g. "reports"; no '..' or '//'; no trailing slash
	Read        Access // gates ReadFile / OpenFile / StatFile + the public read route
	Write       Access // gates WriteFile / DeleteFile + the public write route
	List        Access // gates ListDir
	Description string // shown in the system prompt's directories section

	// LLMHint is optional guidance shown to the LLM in the system prompt
	// alongside the directory entry, e.g. "internal cache; avoid listing
	// or modifying" or "user-uploaded reports; prefer summarizing over
	// quoting". Authorization stays with Read/Write/List — LLMHint only
	// steers the model. Empty by default.
	LLMHint string

	// RetentionHours, when > 0, opts the directory into Airlock's storage
	// sweeper: any file in the S3 prefix older than this many hours is
	// deleted on the next sweep tick (~6h cadence). Zero means files
	// stay forever — that's the default for normal builder directories.
	// The framework's /tmp registers with 72 to garbage-collect chat
	// uploads and generated media; tools that produce throwaway artifacts
	// (e.g. AI-generated images served via fileShareURL with a 1h URL
	// expiry) should set a matching short TTL so the bytes go away when
	// the URL does.
	RetentionHours int

	// Scope opts the directory into per-context isolation: WriteFile
	// transparently inserts a scope segment (user-<id>/conv-<id>/run-<id>)
	// between the directory prefix and the rest of the path, and reads
	// only succeed when the scope key in the path matches one the
	// current run owns. Use it for directories accessible to lower-trust
	// callers (public-MCP, anon) where you need per-caller isolation
	// without sacrificing usability — the LLM sees the scoped path,
	// passes it around, and access just works for the caller who wrote
	// it. Default ScopeNone preserves today's behaviour.
	Scope DirectoryScope
}

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 DirectoryOpts struct {
	Read        Access // default AccessUser
	Write       Access // default AccessUser
	List        Access // default AccessUser
	Description string

	// LLMHint: see Directory.LLMHint. Optional model-facing guidance.
	LLMHint string

	// RetentionHours: see Directory.RetentionHours. Zero = no sweep.
	RetentionHours int

	// Scope: see Directory.Scope. Default ScopeNone (no scoping).
	Scope DirectoryScope
}

type DirectoryScope string

type DisplayPart struct {
	Type     string  `json:"type"`             // "text", "image", "file", "audio", "video"
	Text     string  `json:"text,omitempty"`   // body text, or caption for media types
	Source   string  `json:"source,omitempty"` // S3 key
	URL      string  `json:"url,omitempty"`    // external URL
	Data     []byte  `json:"data,omitempty"`   // raw bytes (base64 in JSON)
	Filename string  `json:"filename,omitempty"`
	MimeType string  `json:"mimeType,omitempty"`
	Alt      string  `json:"alt,omitempty"`      // accessibility text for images
	Duration float64 `json:"duration,omitempty"` // seconds, audio/video
}

type EnvVar struct {
	// Slug is the unique identifier per agent. Mirrored as the URL
	// segment in /api/v1/agents/{id}/env-vars/{slug}.
	Slug string

	// Description is shown to the operator in the editor UI. Never sent
	// to the LLM.
	Description string

	// Secret toggles the write-only UI affordance + redaction. See the
	// type doc for full semantics.
	Secret bool

	// Default is the value used when the operator hasn't configured the
	// slot. Lets an agent ship with sensible plain-config defaults
	// (region="us-east-1", timeout="30s") that the operator only
	// overrides when needed.
	//
	// Forbidden for Secret=true: there is no sensible default for a
	// credential, and a hardcoded one in agent source would defeat the
	// point of the secrets surface. RegisterEnvVar panics if both are
	// set.
	Default string

	// Pattern is an optional Go regex (RE2) the operator-supplied value
	// must match. Airlock rejects values that don't match at save time,
	// so typos in known-shape credentials (AWS keys, region codes,
	// hostnames) surface immediately rather than at first runtime use.
	// Empty string disables validation.
	//
	// Validated against agent's declaration (mirrors the Description
	// and Default fields), not against a per-set choice — operators
	// can't bypass the pattern.
	Pattern string
}

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 EnvVarHandle struct {
	// contains filtered or unexported fields
}

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

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

type ExecCommand struct {
	Command string        `json:"command"`
	Args    []string      `json:"args,omitempty"`
	Stdin   []byte        `json:"-"` // marshalled separately as base64
	Timeout time.Duration `json:"-"` // 0 = server default (60s); marshalled as timeoutMs
}

type ExecEndpoint struct {
	Slug        string // unique per agent; binds as exec_{slug} in run_js
	Description string
	LLMHint     string // appended to the endpoint block in the system prompt
	Access      Access // who may invoke; default AccessAdmin; AccessPublic is silently demoted to AccessUser
}

type ExecEndpointDef struct {
	Slug        string `json:"slug,omitempty"`
	Description string `json:"description"`
	LLMHint     string `json:"llmHint,omitempty"`
	Access      Access `json:"access,omitempty"`
}

type ExecError struct {
	Kind    string // "transport" | "timeout" | "config" | "denied"
	Message string
}

type ExecExit struct {
	ExitCode   int
	DurationMs int64
}

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

type ExecRequest struct {
	Command   string   `json:"command"`
	Args      []string `json:"args,omitempty"`
	StdinB64  string   `json:"stdinB64,omitempty"`
	TimeoutMs int64    `json:"timeoutMs,omitempty"`
}

type ExecResult struct {
	Stdout     []byte
	Stderr     []byte
	ExitCode   int
	DurationMs int64
}

type ExecStream struct {
	Stdout io.ReadCloser
	Stderr io.ReadCloser
	Wait   func() (ExecExit, error)
}

type FileInfo struct {
	Path         FilePath  `json:"path"`     // S3-style storage path, e.g. "uploads/foo.png"
	Filename     string    `json:"filename"` // original upload name; S3 metadata
	ContentType  string    `json:"contentType"`
	Size         int64     `json:"size"`
	LastModified time.Time `json:"lastModified"`
}

type FileOp string

type FilePath string

type HTTPRequest struct {
	URL     string            `json:"url"`
	Method  string            `json:"method,omitempty"` // default: GET
	Headers map[string]string `json:"headers,omitempty"`
	Body    string            `json:"body,omitempty"`
	Timeout int               `json:"timeout,omitempty"` // seconds, default: 30, max: 120
	SaveAs  string            `json:"saveAs,omitempty"`  // save response body to S3 at this key (binary-safe)
	Raw     bool              `json:"raw,omitempty"`     // skip HTML→markdown conversion for HTML responses
	// AllHeaders returns every upstream response header. Default (false)
	// returns only the curated few an agent reasons about; the rest
	// (CSP, Via, Alt-Svc, telemetry) are noise that burns context.
	AllHeaders bool `json:"allHeaders,omitempty"`
}

type HTTPResponse struct {
	Status      int               `json:"status"`
	Headers     map[string]string `json:"headers"`
	Body        string            `json:"body,omitempty"`
	ContentType string            `json:"contentType"` // original upstream Content-Type
	// Size is the byte length of the content the agent can act on — the
	// inline body, the converted markdown, or the object written to
	// SavedTo. Always populated (never the upstream Content-Length,
	// which is 0 for chunked/unknown).
	Size int `json:"size"`
	// BodyPreview is the head (~1 KB) of a saved text/markdown body so
	// the result is legible without a second fileRead. Empty for binary
	// or inline (Body carries the whole thing) responses.
	BodyPreview string `json:"bodyPreview,omitempty"`
	SavedTo     string `json:"savedTo,omitempty"` // S3 key if body was auto-saved
	Note        string `json:"note,omitempty"`    // human-readable note about transformations applied (e.g. HTML→markdown conversion)
}

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

type Instruction struct {
	Text   string
	Access []Access
}

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

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

type ListOpts struct {
	// Recursive walks the entire subtree. Zero value (false) lists only
	// files directly under the path (one level only, like `ls`).
	Recursive bool
}

type ListSchedulesFilter struct {
	Slug string
}

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

type LogLevel string

type MCP struct {
	Slug     string // unique per agent; binds as mcp_{slug} in run_js
	Name     string
	URL      string
	AuthMode MCPAuth
	AuthURL  string
	TokenURL string
	Scopes   []string
	// AuthInjection picks how the stored credential is added to each MCP
	// HTTP call: bearer header (default), custom header, query parameter,
	// or path prefix. Mirrors Connection.AuthInjection.
	AuthInjection AuthInjection
	Access        Access // who may invoke mcp_{slug}; default AccessUser
}

type MCPAuth string

type MCPAuthStatus struct {
	Slug       string  `json:"slug"`
	AuthMode   MCPAuth `json:"authMode"`
	Authorized bool    `json:"authorized"`
	AuthURL    string  `json:"authUrl,omitempty"`
	// Instructions is the server-level description the remote MCP server
	// advertised in its initialize result (the spec's `instructions`
	// field). Empty when the server set none. Rendered next to
	// mcp_<slug> in the prompt so the model knows what the server is for.
	Instructions string `json:"instructions,omitempty"`
}

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"`
}

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"`
	Access        Access        `json:"access,omitempty"`
}

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

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

type MCPToolCallResponse struct {
	Content []MCPContent `json:"content"`
	IsError bool         `json:"isError"`
}

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

type MockAirlock struct {
	Server *httptest.Server

	// LLMResponse is the NDJSON response returned by POST /api/agent/llm/stream.
	// Set this before making prompt requests.
	LLMResponse []byte
	// contains filtered or unexported fields
}

type MockRequest struct {
	Method string
	Path   string
	Body   []byte
}

type ModelCapability string

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

type ModelSlot struct {
	Slug        string
	Capability  ModelCapability // required: CapText, CapVision, CapImage, CapSpeech, CapTranscription, CapEmbedding
	Description string          // human-readable hint shown in the admin UI
}

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

type PrintRequest struct {
	Parts          []DisplayPart `json:"parts"`
	Topic          string        `json:"topic,omitempty"`          // empty = direct to conversation
	ConversationID string        `json:"conversationId,omitempty"` // set for direct prints
	RunID          string        `json:"runId,omitempty"`          // originating run, used to sort ephemerals after their run's assistant messages
	UserID         string        `json:"userId,omitempty"`         // topic publish scoped to this user's subscribed conversations (PublishToUser)
}

type PromptData struct {
	// AgentDashboardURL points at the agent's settings page in the
	// Airlock UI; the prompt tells the LLM to direct users there when
	// a connection or MCP server needs OAuth.
	AgentDashboardURL string `json:"agentDashboardUrl"`

	// AgentRouteURL is the agent's public subdomain (scheme + host +
	// optional port). The prompt embeds it for "share file at this
	// URL" guidance. Derived server-side because the scheme/port
	// logic lives in airlock's PUBLIC_URL parsing.
	AgentRouteURL string `json:"agentRouteUrl"`

	// Siblings is the FULL configured sibling list with each one's
	// tool schemas. Static at sync time (changes when the operator
	// edits the address book). Per-user visibility is layered on at
	// dispatch via PromptInput.VisibleSiblings.
	Siblings []SiblingInfo `json:"siblings,omitempty"`

	// Capabilities are the model slots Airlock has bound for this
	// agent (agent override → system default). Each bool is true iff
	// some model is bound for that slot — the prompt branches on
	// these to avoid recommending builtins that would 4xx at
	// runtime (e.g. analyzeImage on an agent with no vision model).
	Capabilities Capabilities `json:"capabilities,omitempty"`

	// SupportedModalities is the chat model's declared input
	// modality list ("text", "image", "pdf", "audio", "video") at
	// sync time. PromptInput.SupportedModalities overrides per-run
	// when set (the run-time value reflects the actual model that
	// will serve THIS turn, which can differ from sync if the agent
	// uses run.LLM(slug=...) elsewhere). The prompt template uses
	// whichever the agent has on hand.
	SupportedModalities []string `json:"supportedModalities,omitempty"`
}

type PromptInput struct {
	Messages            []message.Message `json:"messages"`
	Message             string            `json:"message,omitempty"` // New user message text (used with SessionStore)
	ConversationID      string            `json:"conversationId,omitempty"`
	ProviderID          string            `json:"providerId,omitempty"`
	ModelID             string            `json:"modelId,omitempty"`
	Temperature         *float64          `json:"temperature,omitempty"`
	MaxOutputTokens     *int              `json:"maxOutputTokens,omitempty"`
	ProviderOptions     json.RawMessage   `json:"providerOptions,omitempty"`
	Files               []FileInfo        `json:"files,omitempty"`
	ResumeRunID         string            `json:"resumeRunId,omitempty"`
	Approved            *bool             `json:"approved,omitempty"`
	SupportedModalities []string          `json:"supportedModalities,omitempty"` // e.g. ["text", "image", "pdf", "audio", "video"]
	Source              string            `json:"source,omitempty"`              // "user" (default), "system" (injected by Airlock)

	// Instructions is an access-filtered concatenation of the agent's
	// registered AddInstruction fragments, composed by Airlock at run
	// dispatch. The agent appends this to its sync-cached system prompt.
	Instructions string `json:"instructions,omitempty"`

	// CallerAccess is the resolved per-(agent, user) access level for the
	// triggering caller. agentsdk uses it to gate which conn_/mcp_/topic_/
	// storage_ JS bindings (and registered tools) are exposed to the run.
	// Airlock sets this from trigger.ResolveAgentAccess. For trusted server
	// triggers (webhooks, crons) Airlock sends AccessAdmin.
	CallerAccess Access `json:"callerAccess,omitempty"`

	// VisibleSiblings are the sibling-agent IDs this run's user is
	// authorized to A2A-call. UUIDs (not slugs) so a mid-run rename
	// doesn't silently revoke or reassign bindings. Computed by Airlock
	// at dispatch using the same access ladder that gates the MCP
	// endpoint. agentsdk intersects this with the sync-cached
	// PromptData.Siblings (matched on .ID) for both prompt rendering
	// and VM bindings — so the prompt and the runtime agree about which
	// agent_<slug> namespaces are reachable on this run.
	VisibleSiblings []uuid.UUID `json:"visibleSiblings,omitempty"`

	// ForceCompact tells the agent to skip the thinking loop and run a
	// user-triggered compaction instead. Message is ignored when set. The
	// agent loads conversation history, asks the model to summarize it,
	// persists the summary via the SessionStore's Compact method, and emits
	// a short text-delta describing the outcome.
	ForceCompact bool `json:"forceCompact,omitempty"`

	// AutoConfirm makes run_js skip the request_confirmation gate and
	// execute directly. Airlock sets it for runs that have no interactive
	// second turn in which to answer a confirmation — currently public
	// one-shot bridge sessions. It governs only this run's own run_js; a
	// suspension that still reaches the triggering surface by another path
	// (e.g. an A2A-delegated confirmation) is auto-denied there instead.
	AutoConfirm bool `json:"autoConfirm,omitempty"`

	// DirectTools selects the per-run tool surface. When false (default),
	// the LLM gets one `run_js` tool and capabilities are JS bindings inside
	// the goja sandbox. When true, every capability is its own typed LLM
	// tool — no JS sandbox, no TypeScript manifest in the prompt. Airlock
	// sets this based on the resolved caller; today it's hardcoded to
	// `callerAccess == AccessPublic`.
	DirectTools bool `json:"directTools,omitempty"`

	// Platform / UserDisplayName / UserEmail are per-turn context for the
	// prompt's <env> block. Airlock sets Platform explicitly per dispatch
	// path (web/telegram/discord/a2a — never inferred) and resolves the
	// originating user's name/email; any may be empty (then omitted).
	Platform        string `json:"platform,omitempty"`
	UserDisplayName string `json:"userDisplayName,omitempty"`
	UserEmail       string `json:"userEmail,omitempty"`
}

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

type RequestOpts struct {
	// Method is the HTTP verb. Empty defaults to "GET" (the majority
	// of calls).
	Method string
	// Path is appended to the connection's BaseURL. Required.
	Path string
	// Body is encoded by type when non-nil: []byte / string sent as-is,
	// io.Reader fully read, anything else JSON-marshalled.
	Body any
	// Headers merge per-key on top of the platform baseline (real-browser
	// User-Agent) and the connection's declared Headers. Set a value to
	// the empty string to suppress a key set by a lower layer. Nil/empty
	// map means no overrides.
	Headers map[string]string
}

type Route struct {
	Method      string           // "GET", "POST", ...
	Path        string           // e.g. "/spotify"
	Handler     RouteHandlerFunc // required
	Access      Access           // required: AccessAdmin, AccessUser, or AccessPublic
	Description string
}

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

type RouteHandlerFunc func(ctx context.Context, w http.ResponseWriter, r *http.Request)

type RunCompleteRequest struct {
	RunID string `json:"runId"`
	// Status is "success" | "error" | "suspended" | "timeout" | "tool_errors".
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
	// ErrorKind is set when Status == "error" and disambiguates platform
	// vs agent failure for the UI. Empty otherwise.
	ErrorKind  string          `json:"errorKind,omitempty"`
	PanicTrace string          `json:"panicTrace,omitempty"`
	Actions    json.RawMessage `json:"actions"`
	Logs       []LogEntry      `json:"logs,omitempty"`
	Checkpoint json.RawMessage `json:"checkpoint,omitempty"`
}

type Schedule struct {
	Slug        string              // unique per agent (across crons + schedules)
	Handler     ScheduleHandlerFunc // required
	Timeout     time.Duration       // max execution time (default: 2 min)
	Description string
}

type ScheduleAtRequest struct {
	Slug   string    `json:"slug"`
	FireAt time.Time `json:"fireAt"`
}

type ScheduleHandlerDef struct {
	Slug        string `json:"slug"`
	Kind        string `json:"kind"`
	Recurrence  string `json:"recurrence,omitempty"`
	TimeoutMs   int64  `json:"timeoutMs"`
	Description string `json:"description,omitempty"`
}

type ScheduleHandlerFunc func(ctx context.Context, ew *EventWriter) error

type ScheduledFire struct {
	ID         string    `json:"id"`
	Slug       string    `json:"slug"`
	Kind       string    `json:"kind"` // "cron" | "schedule"
	FireAt     time.Time `json:"fireAt"`
	Status     string    `json:"status"` // pending|fired|error|orphaned|cancelled
	Recurrence string    `json:"recurrence,omitempty"`
}

type ScheduledFireRef struct {
	FireID string
	Slug   string
}

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

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

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

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

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

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

type SiblingInfo struct {
	// ID is the canonical, rename-safe identifier. MCP outbound calls
	// use the UUID in the URL path so a sibling rename doesn't break
	// in-flight bindings.
	ID uuid.UUID `json:"id"`
	// Slug is the human-readable binding name — appears in the prompt
	// and as the `agent_<slug>` namespace on this agent's VM.
	Slug        string          `json:"slug"`
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Tools       []MCPToolSchema `json:"tools,omitempty"`
}

type SyncRequest struct {
	Version          string               `json:"version"`
	Description      string               `json:"description,omitempty"`
	Emoji            string               `json:"emoji,omitempty"`
	Tools            []ToolDef            `json:"tools,omitempty"`
	Webhooks         []WebhookDef         `json:"webhooks"`
	ScheduleHandlers []ScheduleHandlerDef `json:"scheduleHandlers"`
	Routes           []RouteDef           `json:"routes,omitempty"`
	Topics           []TopicDef           `json:"topics,omitempty"`
	MCPServers       []MCPDef             `json:"mcpServers,omitempty"`
	Connections      []ConnectionDef      `json:"connections,omitempty"`
	ExecEndpoints    []ExecEndpointDef    `json:"execEndpoints,omitempty"`
	EnvVars          []EnvVarDef          `json:"envVars,omitempty"`
	Directories      []DirectoryDef       `json:"directories,omitempty"`
	Instructions     []InstructionDef     `json:"instructions,omitempty"`
	ModelSlots       []ModelSlotDef       `json:"modelSlots,omitempty"`
}

type SyncResponse struct {
	// PromptData carries the slice of system-prompt input the agent
	// can't derive locally: dashboard / route URLs, the full sibling
	// address book with their published tool schemas. Required. An
	// older agentsdk that doesn't know about PromptData would have
	// produced an empty system prompt; the new agentsdk's
	// applySyncResponse panics on a zero-value PromptData with a
	// clear "your airlock is newer than your agentsdk" message.
	PromptData PromptData `json:"promptData"`

	MCPAuthStatus []MCPAuthStatus `json:"mcpAuthStatus,omitempty"`
	// MCPSchemas carries discovered tool schemas per MCP server slug.
	// Airlock populates these from its server-side discovery cache so the
	// agent's VM can install one typed JS method per tool on each
	// `mcp_{slug}` object — no per-run discovery round-trips.
	MCPSchemas map[string][]MCPToolSchema `json:"mcpSchemas,omitempty"`
	// PublicStorageBase is the URL prefix at which directories are reachable
	// on the agent's subdomain, ending without a trailing slash. Callers
	// join with '/' and the storage path (e.g. "reports/q1.csv") to
	// construct a URL: "https://{slug}.{domain}/__air/storage/reports/q1.csv".
	// The proxy enforces the directory's Read cap at fetch time — public
	// dirs serve unauthenticated, user/admin dirs require subdomain login
	// (redirect-on-missing-cookie).
	PublicStorageBase string `json:"publicStorageBase,omitempty"`
}

type Tool[In any, Out any] struct {
	Name        string
	Description string

	// LLMHint is optional model-only guidance — usage tips, deprecation
	// warnings, "prefer X over Y" notes — that you don't want to leak to
	// member UIs that render Description (e.g. the agent dashboard's
	// Tools tab). When this struct is later lowered into goai.Tool the
	// hint is appended to Description in `[brackets]`; goai.Tool itself
	// has no LLMHint field (it mirrors ai-sdk's LanguageModelV4FunctionTool).
	LLMHint string

	Execute       func(ctx context.Context, input In) (Out, error)
	Access        Access
	InputExamples []In
}

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"`
}

type Topic struct {
	Slug        string
	Description string
	LLMHint     string // optional model-only guidance — see Directory.LLMHint
	Access      Access // who may subscribe via topic_{slug}.subscribe(); default AccessUser
	// PerUser forbids broadcast: Publish panics, only PublishToUser delivers
	// (to the named user's subscribed conversations). Use for personal feeds
	// (reminders, alerts) where a broadcast would leak across users.
	PerUser bool
}

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"`
}

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

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

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

type User struct {
	ID          string
	Email       string
	DisplayName string
}

type Webhook struct {
	Path        string             // unique per agent
	Handler     WebhookHandlerFunc // required
	Verify      string             // "none" | "hmac" | "token" | "bearer" | "ed25519" (default: "none")
	Header      string             // header carrying the signature/token (hmac/ed25519 modes)
	Timeout     time.Duration      // max execution time (default: 2 min)
	Description string
	Access      Access // who may invoke; default AccessUser
}

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"`
}

type WebhookHandlerFunc func(ctx context.Context, data []byte, ew *EventWriter) error