# Go data types

Complete public input, result, event and configuration fields.

These declarations come from the shipped SDK. Optional fields and defaults are explicit in the declarations; required fields must be supplied. Server-generated fields describe responses and should not be invented by clients.

## AssistanceSettings



```go
type AssistanceSettings struct {
	Overseer           bool  `json:"overseer"`
	Version            int64 `json:"version"`
	OverseerConfigured bool  `json:"overseer_configured"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Overseer` | `bool` | Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `OverseerConfigured` | `bool` | Whether the engine has a configured Coordinator provider; not the enablement switch. |

## AssistanceUpdate



```go
type AssistanceUpdate struct {
	Version  int64 `json:"version,omitempty"`
	Overseer *bool `json:"overseer,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Overseer` | `*bool` | Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |

## OverseerInput



```go
type OverseerInput struct {
	PreviousPlanID string  `json:"previous_plan_id,omitempty"`
	Prompt         string  `json:"prompt"`
	Target         *Target `json:"target,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `PreviousPlanID` | `string` | Optional prior plan belonging to the caller for continuing permitted context. |
| `Prompt` | `string` | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `Target` | `*Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |

## Instance



```go
type Instance struct {
	ID           string         `json:"id"`
	AgentID      string         `json:"agent_id"`
	Presence     string         `json:"presence"`
	LastSeen     time.Time      `json:"last_seen"`
	Capabilities []string       `json:"capabilities"`
	Progress     map[string]any `json:"progress"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `AgentID` | `string` | Logical agent identity ID, shared by its runtime instances. |
| `Presence` | `string` | Observed runtime presence: connected, stale or offline. |
| `LastSeen` | `time.Time` | Most recent runtime heartbeat timestamp. |
| `Capabilities` | `[]string` | Application-declared runtime capabilities. This does not grant contact permission. |
| `Progress` | `map[string]any` | Explicit application-reported progress metadata; not automatic model telemetry. |

## FleetAgent



```go
type FleetAgent struct {
	Agent     Agent      `json:"agent"`
	Instances []Instance `json:"instances"`
	Fresh     bool       `json:"fresh"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Agent` | `Agent` | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `Instances` | `[]Instance` | Runtime connections and their observed presence. |
| `Fresh` | `bool` | Whether the reported runtime evidence is current. |

## OverseerDispatch



```go
type OverseerDispatch struct {
	AgentID        string `json:"agent_id"`
	ConversationID string `json:"conversation_id"`
	RequestID      string `json:"request_id,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `AgentID` | `string` | Logical agent identity ID, shared by its runtime instances. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `RequestID` | `string` | Canonical durable request ID. This is not a worker delivery ID. |

## OverseerInstruction



```go
type OverseerInstruction struct {
	AgentID   string `json:"agent_id"`
	Operation string `json:"operation"`
	Body      string `json:"body"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `AgentID` | `string` | Logical agent identity ID, shared by its runtime instances. |
| `Operation` | `string` | Requested operation, with values defined by that endpoint. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |

## OverseerPlan



```go
type OverseerPlan struct {
	Automatic            bool                  `json:"automatic,omitempty"`
	Instructions         []OverseerInstruction `json:"instructions,omitempty"`
	SummaryError         string                `json:"summary_error,omitempty"`
	PreviousPlanID       string                `json:"previous_plan_id,omitempty"`
	Target               *Target               `json:"target,omitempty"`
	ID                   string                `json:"id"`
	Prompt               string                `json:"prompt"`
	ContextIDs           []string              `json:"context_agent_ids"`
	Operation            string                `json:"operation"`
	Summary              string                `json:"summary"`
	Body                 string                `json:"body,omitempty"`
	Sources              []FleetAgent          `json:"sources"`
	RequiresConfirmation bool                  `json:"requires_confirmation"`
	CreatedAt            time.Time             `json:"created_at"`
	ExpiresAt            time.Time             `json:"expires_at"`
	Dispatches           []OverseerDispatch    `json:"dispatches"`
	Replies              []Request             `json:"replies"`
	ReplySummary         string                `json:"reply_summary,omitempty"`
	ReplyDigest          string                `json:"reply_digest,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Automatic` | `bool` | True when Coordinator delegated without a separate review step. |
| `Instructions` | `[]OverseerInstruction` | Per-agent communication instructions, when different specialists need different tasks. |
| `SummaryError` | `string` | Safe model-summary error. Existing durable instructions remain separately inspectable. |
| `PreviousPlanID` | `string` | Optional prior plan belonging to the caller for continuing permitted context. |
| `Target` | `*Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `Prompt` | `string` | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `ContextIDs` | `[]string` | Agent IDs included in the current permitted plan context. |
| `Operation` | `string` | Requested operation, with values defined by that endpoint. |
| `Summary` | `string` | Plan explanation or status answer, as defined by its operation. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Sources` | `[]FleetAgent` | Authorized specialist context used for this plan, not omniscient agent execution state. |
| `RequiresConfirmation` | `bool` | Whether this saved plan needs explicit confirmation before dispatch. |
| `CreatedAt` | `time.Time` | Creation timestamp in RFC 3339 UTC. |
| `ExpiresAt` | `time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `Dispatches` | `[]OverseerDispatch` | Attributed conversation/request IDs created by a confirmed or automatic plan. |
| `Replies` | `[]Request` | Specialist requested decisions visible to the current caller. |
| `ReplySummary` | `string` | Model-generated summary of the authorized replies, including pending/missing evidence. |
| `ReplyDigest` | `string` | Digest identifying the reply evidence used by the summary. |

## Client



```go
type Client struct {
	BaseURL string
	Token   string
	HTTP    *http.Client
	// AssistanceTimeout applies only to model-backed planning and summaries.
	// Zero uses 40 seconds; a shorter caller context still takes precedence.
	AssistanceTimeout time.Duration
	// MaxResponseBytes bounds decoded responses. Zero uses 256 MiB, covering the
	// API's bounded 1000-recipient fan-out even with JSON escaping. Decoding streams.
	MaxResponseBytes int64
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `BaseURL` | `string` | Engine origin, including scheme and optional port. No embedded credentials. |
| `Token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `HTTP` | `*http.Client` | Go HTTP client/transport override. New uses a 20-second timeout; contexts can impose a shorter deadline. |
| `AssistanceTimeout` | `time.Duration` | AssistanceTimeout applies only to model-backed planning and summaries. Zero uses 40 seconds; a shorter caller context still takes precedence.  |
| `MaxResponseBytes` | `int64` | MaxResponseBytes bounds decoded responses. Zero uses 256 MiB, covering the API's bounded 1000-recipient fan-out even with JSON escaping. Decoding streams.  |

## APIError



```go
type APIError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Status  int    `json:"-"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Code` | `string` | Stable API error code for programmatic handling. |
| `Message` | `string` | Safe human-readable API error message. |
| `Status` | `int` | Local SDK field; not serialized on the JSON wire. |

## Target



```go
type Target struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |

## Person



```go
type Person struct {
	ID         string         `json:"id"`
	Name       string         `json:"name"`
	ExternalID string         `json:"external_id"`
	Metadata   map[string]any `json:"metadata"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `Name` | `string` | Human-readable name. It is not necessarily unique. |
| `ExternalID` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `Metadata` | `map[string]any` | Application-supplied JSON metadata. Do not put credentials here. |

## Agent



```go
type Agent struct {
	ID         string         `json:"id"`
	Name       string         `json:"name"`
	ExternalID string         `json:"external_id"`
	Metadata   map[string]any `json:"metadata"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `Name` | `string` | Human-readable name. It is not necessarily unique. |
| `ExternalID` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `Metadata` | `map[string]any` | Application-supplied JSON metadata. Do not put credentials here. |

## Session



```go
type Session struct {
	Token      string `json:"token"`
	Agent      Agent  `json:"agent"`
	InstanceID string `json:"instance_id"`
	// ExpiresAt is zero when the connection never expires.
	ExpiresAt time.Time `json:"expires_at"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `Agent` | `Agent` | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `InstanceID` | `string` | Exact connected runtime ID, separate from the logical agent identity. |
| `ExpiresAt` | `time.Time` | ExpiresAt is zero when the connection never expires.  |

## EnrollInput



```go
type EnrollInput struct {
	NeverExpires   bool           `json:"never_expires,omitempty"`
	ConnectionName string         `json:"connection_name,omitempty"`
	Renewable      bool           `json:"renewable,omitempty"`
	ExpiresAt      *time.Time     `json:"expires_at,omitempty"`
	ParentID       string         `json:"parent_id,omitempty"`
	Agent          string         `json:"agent"`
	Name           string         `json:"name"`
	Capabilities   []string       `json:"capabilities"`
	Metadata       map[string]any `json:"metadata,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `NeverExpires` | `bool` | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. |
| `ConnectionName` | `string` | Human-readable label for this Agent runtime connection. |
| `Renewable` | `bool` | Use a renewable 24-hour worker lease bounded by the supplied hard expiry. Renewal never extends the hard deadline. |
| `ExpiresAt` | `*time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `ParentID` | `string` | Optional parent agent identity for a deliberately bounded enrollment. |
| `Agent` | `string` | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `Name` | `string` | Human-readable name. It is not necessarily unique. |
| `Capabilities` | `[]string` | Application-declared runtime capabilities. This does not grant contact permission. |
| `Metadata` | `map[string]any` | Application-supplied JSON metadata. Do not put credentials here. |

## Action



```go
type Action struct {
	Name            string         `json:"name"`
	ExecutorID      string         `json:"executor_id"`
	Resource        string         `json:"resource"`
	ResourceVersion string         `json:"resource_version"`
	Arguments       map[string]any `json:"arguments"`
	OperationKey    string         `json:"operation_key"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Name` | `string` | Human-readable name. It is not necessarily unique. |
| `ExecutorID` | `string` | Identity allowed to redeem the exact approved action. |
| `Resource` | `string` | Customer-defined resource identifier. The engine does not control the external resource. |
| `ResourceVersion` | `string` | Customer-defined version fence that the external tool must also enforce. |
| `Arguments` | `map[string]any` | JSON action arguments covered by the exact approval binding. |
| `OperationKey` | `string` | Stable identity of the external business operation, separate from the HTTP retry key. |

## AskInput



```go
type AskInput struct {
	AttachmentIDs  []string   `json:"attachment_ids,omitempty"`
	Mentions       []Mention  `json:"mentions,omitempty"`
	Blocking       bool       `json:"blocking,omitempty"`
	ReuseDirect    bool       `json:"reuse_direct,omitempty"`
	PreviewToken   string     `json:"preview_token,omitempty"`
	Target         Target     `json:"target"`
	ConversationID string     `json:"conversation_id,omitempty"`
	Kind           string     `json:"kind,omitempty"`
	Title          string     `json:"title,omitempty"`
	Body           string     `json:"body,omitempty"`
	Choices        []string   `json:"choices,omitempty"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	Action         *Action    `json:"action,omitempty"`
	SharedKey      string     `json:"shared_key,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `AttachmentIDs` | `[]string` | IDs of staged private drafts to claim in the initial operation; at most five. |
| `Mentions` | `[]Mention` | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `Blocking` | `bool` | Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking. |
| `ReuseDirect` | `bool` | Opt into reusing exact authorized two-person history. False by default; does not merge shared chats. |
| `PreviewToken` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `Target` | `Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `Title` | `string` | Optional short label. A normal message does not require a title. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Choices` | `[]string` | Optional exact answer strings. A chosen answer must match an offered value. |
| `ExpiresAt` | `*time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `Action` | `*Action` | Optional exact bound-action descriptor for the advanced execution contract. |
| `SharedKey` | `string` | Explicit reusable-answer key; reuse also requires exact matching question context and current authority. |

## Response



```go
type Response struct {
	ResponderInstanceID string `json:"responder_instance_id,omitempty"`
	SourceAnswerID      string `json:"source_answer_id,omitempty"`
	ReuseMethod         string `json:"reuse_method,omitempty"`
	ReuseReason         string `json:"reuse_reason,omitempty"`
	SourceInvalidated   bool   `json:"source_invalidated,omitempty"`
	Outcome             string `json:"outcome"`
	Answer              any    `json:"answer,omitempty"`
	Version             int    `json:"version"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ResponderInstanceID` | `string` | Runtime that supplied the final response, when applicable. |
| `SourceAnswerID` | `string` | Published answer used as response provenance. |
| `ReuseMethod` | `string` | How an existing informational answer was reused. |
| `ReuseReason` | `string` | Recorded reason or provenance for reuse. |
| `SourceInvalidated` | `bool` | Whether the source informational answer has since been invalidated. |
| `Outcome` | `string` | Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind. |
| `Answer` | `any` | JSON response value; for choices, the selected exact string. |
| `Version` | `int` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

## Request



```go
type Request struct {
	Attachments         []Attachment `json:"attachments,omitempty"`
	Mentions            []Mention    `json:"mentions,omitempty"`
	Blocking            bool         `json:"blocking,omitempty"`
	RequesterInstanceID string       `json:"requester_instance_id,omitempty"`
	ID                  string       `json:"id"`
	ConversationID      string       `json:"conversation_id"`
	RequesterID         string       `json:"requester_id"`
	Kind                string       `json:"kind"`
	Title               string       `json:"title"`
	Body                string       `json:"body"`
	Choices             []string     `json:"choices"`
	State               string       `json:"state"`
	Version             int          `json:"version"`
	Response            *Response    `json:"response,omitempty"`
	Action              *Action      `json:"action,omitempty"`
	ExpiresAt           time.Time    `json:"expires_at"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Attachments` | `[]Attachment` | Currently visible attachment metadata. |
| `Mentions` | `[]Mention` | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `Blocking` | `bool` | Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking. |
| `RequesterInstanceID` | `string` | Runtime that initiated the request, when applicable. |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `RequesterID` | `string` | Identity that opened the requested decision. |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `Title` | `string` | Optional short label. A normal message does not require a title. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Choices` | `[]string` | Optional exact answer strings. A chosen answer must match an offered value. |
| `State` | `string` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `Version` | `int` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Response` | `*Response` | Recorded final typed decision, absent while pending. |
| `Action` | `*Action` | Optional exact bound-action descriptor for the advanced execution contract. |
| `ExpiresAt` | `time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |

## Mention



```go
type Mention struct {
	PrincipalID string `json:"principal_id"`
	Start       int    `json:"start"`
	End         int    `json:"end"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `PrincipalID` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `Start` | `int` | Inclusive Unicode code-point offset of the mention, not a byte or UTF-16 index. |
| `End` | `int` | Exclusive Unicode code-point offset of the mention. |

## SendInput



```go
type SendInput struct {
	AttachmentIDs  []string  `json:"attachment_ids,omitempty"`
	Mentions       []Mention `json:"mentions,omitempty"`
	ReuseDirect    bool      `json:"reuse_direct,omitempty"`
	PreviewToken   string    `json:"preview_token,omitempty"`
	Target         Target    `json:"target"`
	ConversationID string    `json:"conversation_id,omitempty"`
	Body           string    `json:"body"`
	Title          string    `json:"title,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `AttachmentIDs` | `[]string` | IDs of staged private drafts to claim in the initial operation; at most five. |
| `Mentions` | `[]Mention` | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `ReuseDirect` | `bool` | Opt into reusing exact authorized two-person history. False by default; does not merge shared chats. |
| `PreviewToken` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `Target` | `Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Title` | `string` | Optional short label. A normal message does not require a title. |

## Message



```go
type Message struct {
	ReceivedBy     []string     `json:"received_by,omitempty"`
	Attachments    []Attachment `json:"attachments,omitempty"`
	Mentions       []Mention    `json:"mentions,omitempty"`
	ID             string       `json:"id"`
	ConversationID string       `json:"conversation_id"`
	Body           string       `json:"body"`
	SenderID       string       `json:"sender_id"`
	InstanceID     string       `json:"instance_id,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ReceivedBy` | `[]string` | Agent IDs whose current native deliveries have been acknowledged, projected only for an authorized sender. This is durable receipt, not proof of model reading or task completion. |
| `Attachments` | `[]Attachment` | Currently visible attachment metadata. |
| `Mentions` | `[]Mention` | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `SenderID` | `string` | Identity that sent the message, independent of the delivering channel. |
| `InstanceID` | `string` | Exact connected runtime ID, separate from the logical agent identity. |

## SendResult



```go
type SendResult struct {
	ConversationID string    `json:"conversation_id"`
	Messages       []Message `json:"messages"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `Messages` | `[]Message` | Canonical message records in this response, not worker delivery envelopes. |

## Execution

Execution is an authorization intent and worker report, not proof of an external effect.


```go
type Execution struct {
	ID           string `json:"id"`
	RequestID    string `json:"request_id"`
	ExecutorID   string `json:"executor_id"`
	OperationKey string `json:"operation_key"`
	Action       Action `json:"action"`
	State        string `json:"state"`
	Result       any    `json:"result"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `RequestID` | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `ExecutorID` | `string` | Identity allowed to redeem the exact approved action. |
| `OperationKey` | `string` | Stable identity of the external business operation, separate from the HTTP retry key. |
| `Action` | `Action` | Optional exact bound-action descriptor for the advanced execution contract. |
| `State` | `string` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `Result` | `any` | Executor-reported JSON result. It is not independent proof of an external effect. |

## Delivery



```go
type Delivery struct {
	ID         string `json:"id"`
	Generation int64  `json:"generation"`
	Payload    struct {
		Type           string   `json:"type"`
		ConversationID string   `json:"conversation_id"`
		Message        *Message `json:"message,omitempty"`
		Request        *Request `json:"request,omitempty"`
	} `json:"payload"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `Generation` | `int64` | Current inbox lease generation. Ack must echo this generation. |
| `Payload` | `struct { 	Type           string   `json:"type"` 	ConversationID string   `json:"conversation_id"` 	Message        *Message `json:"message,omitempty"` 	Request        *Request `json:"request,omitempty"` }` | Canonical message/request information inside a delivery envelope. |

## SendReceipt

SendReceipt confirms durable acceptance, not delivery or execution.


```go
type SendReceipt struct {
	ConversationID string `json:"conversation_id"`
	MessageCount   int    `json:"message_count"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `MessageCount` | `int` | Number of canonical messages accepted in the compact receipt; no bodies returned. |

## PermissionRule

PermissionRule defaults to allow. Explicit deny is limited to communication
toward exact contacts/groups and wins over matching grants.


```go
type PermissionRule struct {
	Effect     string `json:"effect,omitempty"`
	Action     string `json:"action"`
	TargetKind string `json:"target_kind"`
	TargetID   string `json:"target_id"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Effect` | `string` | Whether this contact rule allows or explicitly blocks the selected action. A matching explicit deny overrides grants. |
| `Action` | `string` | Optional exact bound-action descriptor for the advanced execution contract. |
| `TargetKind` | `string` | Kind of identity or managed resource matched by the rule. |
| `TargetID` | `string` | Stable ID or explicitly supported wildcard of the rule's target. |

## ContactPermissionsInput



```go
type ContactPermissionsInput struct {
	Subject Target           `json:"subject"`
	Rules   []PermissionRule `json:"rules"`
	Version int64            `json:"version"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Subject` | `Target` | Authorized subject projection of the access inspection. |
| `Rules` | `[]PermissionRule` | Directional permission rules granted by this policy role. |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

## ContactPreviewInput



```go
type ContactPreviewInput struct {
	Subject Target            `json:"subject"`
	Rules   *[]PermissionRule `json:"rules,omitempty"`
	Version int64             `json:"version"`
	Targets []Target          `json:"targets,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Subject` | `Target` | Authorized subject projection of the access inspection. |
| `Rules` | `*[]PermissionRule` | Directional permission rules granted by this policy role. |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Targets` | `[]Target` | Explicit targets for a private batch or shared chat. These have different audience semantics. |

## Credential

Credential is metadata only. Permissions restrict, never grant, identity access.


```go
type Credential struct {
	ID                 string     `json:"id"`
	PrincipalID        string     `json:"principal_id"`
	Name               string     `json:"name"`
	OwnerName          string     `json:"owner_name"`
	Kind               string     `json:"kind"`
	Prefix             string     `json:"prefix"`
	TokenHint          string     `json:"token_hint"`
	CreatedAt          time.Time  `json:"created_at"`
	LastUsedAt         *time.Time `json:"last_used_at"`
	ExpiresAt          *time.Time `json:"expires_at"`
	RenewableUntil     *time.Time `json:"renewable_until"`
	PreviousUntil      *time.Time `json:"previous_until"`
	Permissions        []string   `json:"permissions"`
	Version            int64      `json:"version"`
	Revoked            bool       `json:"revoked"`
	ParentCredentialID string     `json:"parent_credential_id,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `PrincipalID` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `Name` | `string` | Human-readable name. It is not necessarily unique. |
| `OwnerName` | `string` | Display name of the identity that owns the credential. |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `Prefix` | `string` | Permitted enrollment namespace prefix for a bounded launcher. |
| `TokenHint` | `string` | Non-secret token suffix used to identify a credential. It cannot authenticate. |
| `CreatedAt` | `time.Time` | Creation timestamp in RFC 3339 UTC. |
| `LastUsedAt` | `*time.Time` | Most recently recorded authenticated use, or null. Updates are throttled and are not an exact per-request audit trail. |
| `ExpiresAt` | `*time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `RenewableUntil` | `*time.Time` | Hard deadline for a renewable worker credential, or null when it is not renewable. |
| `PreviousUntil` | `*time.Time` | Deadline for the previous token during rotation overlap, or null when no previous token remains valid. |
| `Permissions` | `[]string` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Revoked` | `bool` | Whether the credential has been revoked and can no longer authenticate. |
| `ParentCredentialID` | `string` | Credential that enrolled this worker, when applicable; used for optional worker revocation with the parent. |

## CredentialInput



```go
type CredentialInput struct {
	NeverExpires bool       `json:"never_expires,omitempty"`
	PrincipalID  string     `json:"principal_id"`
	Kind         string     `json:"kind"`
	Name         string     `json:"name,omitempty"`
	Prefix       string     `json:"prefix,omitempty"`
	ExpiresAt    *time.Time `json:"expires_at,omitempty"`
	Permissions  []string   `json:"permissions,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `NeverExpires` | `bool` | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. |
| `PrincipalID` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `Name` | `string` | Human-readable name. It is not necessarily unique. |
| `Prefix` | `string` | Permitted enrollment namespace prefix for a bounded launcher. |
| `ExpiresAt` | `*time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `Permissions` | `[]string` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |

## CredentialEdit



```go
type CredentialEdit struct {
	NeverExpires     bool       `json:"never_expires,omitempty"`
	Version          int64      `json:"version"`
	Name             *string    `json:"name,omitempty"`
	ExpiresAt        *time.Time `json:"expires_at,omitempty"`
	Permissions      *[]string  `json:"permissions,omitempty"`
	ClearPermissions bool       `json:"clear_permissions,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `NeverExpires` | `bool` | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Name` | `*string` | Human-readable name. It is not necessarily unique. |
| `ExpiresAt` | `*time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `Permissions` | `*[]string` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |
| `ClearPermissions` | `bool` | Remove the credential-specific permission restriction. This does not grant permissions absent from the underlying identity. |

## IssuedCredential



```go
type IssuedCredential struct {
	Token string `json:"token"`
	ID    string `json:"id"`
	Kind  string `json:"kind"`
	// ExpiresAt is zero when the token never expires.
	ExpiresAt time.Time `json:"expires_at"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `ExpiresAt` | `time.Time` | ExpiresAt is zero when the token never expires.  |

## CredentialReplacement



```go
type CredentialReplacement struct {
	Token      string     `json:"token"`
	Credential Credential `json:"credential"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `Credential` | `Credential` | Non-secret credential metadata returned with a newly rotated bearer token. |

## ChannelPolicy



```go
type ChannelPolicy struct {
	Mode            string   `json:"mode"`
	Destinations    []string `json:"destinations"`
	FollowupSeconds int      `json:"followup_seconds"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Mode` | `string` | primary, copy or fallback routing mode. |
| `Destinations` | `[]string` | Recipient-owned delivery destination IDs in preference order. An empty list keeps delivery in the workspace only. |
| `FollowupSeconds` | `int` | Delay before trying the next channel for an unanswered question or approval after provider acceptance. Zero disables follow-ups; new delays are 5 to 900 seconds. |

## ChannelOverride



```go
type ChannelOverride struct {
	Source Target        `json:"source"`
	Policy ChannelPolicy `json:"policy"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Source` | `Target` | Sender selector for a channel override: an exact Agent or an Agent role group. |
| `Policy` | `ChannelPolicy` | Channel delivery policy. It changes delivery destinations without granting contact or decision authority. |

## DeliveryPreferences



```go
type DeliveryPreferences struct {
	PersonID  string            `json:"person_id"`
	Version   int64             `json:"version"`
	Default   *ChannelPolicy    `json:"default"`
	Overrides []ChannelOverride `json:"overrides"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `PersonID` | `string` | Stable recipient Person identity ID. |
| `Version` | `int64` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Default` | `*ChannelPolicy` | Recipient default channel policy; null preserves existing destination-based routing. |
| `Overrides` | `[]ChannelOverride` | Ordered sender-specific delivery preferences. An exact Agent match precedes matching Agent roles, then the recipient default. |

## Event



```go
type Event struct {
	Sequence       int64           `json:"sequence"`
	Kind           string          `json:"kind"`
	ActorID        string          `json:"actor_id"`
	ConversationID string          `json:"conversation_id"`
	RecipientID    string          `json:"recipient_id"`
	Data           json.RawMessage `json:"data"`
	CreatedAt      time.Time       `json:"created_at"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Sequence` | `int64` | Monotonically ordered canonical event sequence. Checkpoint after application processing. |
| `Kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `ActorID` | `string` | Identity responsible for the canonical event. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `RecipientID` | `string` | Intended individual identity for the delivery or event projection. |
| `Data` | `json.RawMessage` | Event-specific JSON data. Full events contain the canonical payload; summary mode is smaller. |
| `CreatedAt` | `time.Time` | Creation timestamp in RFC 3339 UTC. |

## EventOptions



```go
type EventOptions struct {
	After          int64
	Summary        bool
	ConversationID string
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `After` | `int64` | Last committed canonical event sequence. Default 0 starts from retained visible events; checkpoint only after applying each event. |
| `Summary` | `bool` | Plan explanation or status answer, as defined by its operation. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |

## Attachment



```go
type Attachment struct {
	ID             string    `json:"id"`
	ConversationID string    `json:"conversation_id"`
	MessageID      string    `json:"message_id,omitempty"`
	RequestID      string    `json:"request_id,omitempty"`
	FileName       string    `json:"file_name"`
	MediaType      string    `json:"media_type"`
	Size           int64     `json:"size"`
	SHA256         string    `json:"sha256"`
	CreatedAt      time.Time `json:"created_at"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ID` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `MessageID` | `string` | Canonical message ID for deduplication and correlation. |
| `RequestID` | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `FileName` | `string` | Safe file name shown with the attachment. |
| `MediaType` | `string` | Declared media type, for example application/pdf. |
| `Size` | `int64` | File length in bytes, from 1 byte through 5 MiB. |
| `SHA256` | `string` | SHA-256 digest of the stored file bytes. |
| `CreatedAt` | `time.Time` | Creation timestamp in RFC 3339 UTC. |

## QueryInput



```go
type QueryInput struct {
	Collection string            `json:"collection"`
	Search     string            `json:"search,omitempty"`
	Filters    map[string]string `json:"filters,omitempty"`
	Limit      int               `json:"limit,omitempty"`
	Cursor     string            `json:"cursor,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Collection` | `string` | One of the documented query collections. |
| `Search` | `string` | Optional text search, at most 200 characters. |
| `Filters` | `map[string]string` | Supported exact collection filters, not arbitrary SQL or JSON selectors. |
| `Limit` | `int` | Page size: default 50, minimum 1, maximum 200. |
| `Cursor` | `string` | Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours. |

## QueryPage



```go
type QueryPage struct {
	Items      []json.RawMessage `json:"items"`
	NextCursor string            `json:"next_cursor,omitempty"`
	Order      string            `json:"order"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Items` | `[]json.RawMessage` | Authorized records returned by this page. |
| `NextCursor` | `string` | Opaque next-page cursor. Continue even when the current items array is empty. |
| `Order` | `string` | Documented ordering for this collection. |

## CapabilityInput



```go
type CapabilityInput struct {
	Target       *Target `json:"target,omitempty"`
	RequestID    string  `json:"request_id,omitempty"`
	ConnectionID string  `json:"connection_id,omitempty"`
	Descriptor   *Action `json:"descriptor,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Target` | `*Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `RequestID` | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `ConnectionID` | `string` | Configured channel connection ID. |
| `Descriptor` | `*Action` | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

## CapabilityResult



```go
type CapabilityResult struct {
	ObservedAt     time.Time       `json:"observed_at"`
	Operations     map[string]bool `json:"operations"`
	RequestVersion int             `json:"request_version,omitempty"`
	Outcomes       []string        `json:"outcomes"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ObservedAt` | `time.Time` | Timestamp of this capability snapshot. |
| `Operations` | `map[string]bool` | Map of action names to currently allowed booleans. Actual mutation checks again. |
| `RequestVersion` | `int` | Request version observed during capability evaluation. |
| `Outcomes` | `[]string` | Currently allowed typed decision outcomes. |

## DispatchPreviewInput



```go
type DispatchPreviewInput struct {
	Targets    []Target `json:"targets"`
	Operation  string   `json:"operation"`
	Descriptor *Action  `json:"descriptor,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Targets` | `[]Target` | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `Operation` | `string` | Requested operation, with values defined by that endpoint. |
| `Descriptor` | `*Action` | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

## DispatchPreview



```go
type DispatchPreview struct {
	Recipients       []json.RawMessage `json:"recipients"`
	Count            int               `json:"count"`
	HiddenRecipients int               `json:"hidden_recipients"`
	Token            string            `json:"token"`
	ExpiresAt        time.Time         `json:"expires_at"`
	Sends            bool              `json:"sends"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Recipients` | `[]json.RawMessage` | Resolved, authorized recipient projection. |
| `Count` | `int` | Number of recipients resolved by this preview. |
| `HiddenRecipients` | `int` | Resolved recipients whose details the caller cannot view. |
| `Token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `ExpiresAt` | `time.Time` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `Sends` | `bool` | Whether a preview itself sends anything; dispatch preview returns false. |

## SendBatchInput



```go
type SendBatchInput struct {
	AttachmentIDs []string `json:"attachment_ids,omitempty"`
	Targets       []Target `json:"targets"`
	Body          string   `json:"body"`
	Title         string   `json:"title,omitempty"`
	PreviewToken  string   `json:"preview_token,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `AttachmentIDs` | `[]string` | IDs of staged private drafts to claim in the initial operation; at most five. |
| `Targets` | `[]Target` | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Title` | `string` | Optional short label. A normal message does not require a title. |
| `PreviewToken` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |

## SendBatchItem



```go
type SendBatchItem struct {
	Target Target     `json:"target"`
	Result SendResult `json:"result"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Target` | `Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `Result` | `SendResult` | Executor-reported JSON result. It is not independent proof of an external effect. |

## AskBatchInput



```go
type AskBatchInput struct {
	Targets      []Target `json:"targets"`
	Request      AskInput `json:"request"`
	PreviewToken string   `json:"preview_token,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Targets` | `[]Target` | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `Request` | `AskInput` | Nested requested-decision input or canonical request in a batch result. |
| `PreviewToken` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |

## AskBatchItem



```go
type AskBatchItem struct {
	Target  Target  `json:"target"`
	Request Request `json:"request"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Target` | `Target` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `Request` | `Request` | Nested requested-decision input or canonical request in a batch result. |

## StartChatInput

Mentions address existing participants. Offsets count Unicode code points,
and never narrow the shared audience or grant contact/decision authority.


```go
type StartChatInput struct {
	AttachmentIDs []string  `json:"attachment_ids,omitempty"`
	Targets       []Target  `json:"targets"`
	Body          string    `json:"body"`
	Title         string    `json:"title,omitempty"`
	Approval      bool      `json:"approval,omitempty"`
	Choices       []string  `json:"choices,omitempty"`
	Mentions      []Mention `json:"mentions,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `AttachmentIDs` | `[]string` | IDs of staged private drafts to claim in the initial operation; at most five. |
| `Targets` | `[]Target` | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Title` | `string` | Optional short label. A normal message does not require a title. |
| `Approval` | `bool` | Attach a typed approval request to the initial shared chat message. False by default. |
| `Choices` | `[]string` | Optional exact answer strings. A chosen answer must match an offered value. |
| `Mentions` | `[]Mention` | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |

## ChatMembershipInput

Membership controls disclosure, never IAM or the original request audience.
ShareHistory is false unless the caller explicitly opts in for additions.


```go
type ChatMembershipInput struct {
	Operation    string   `json:"operation"`
	Version      int      `json:"version"`
	Title        string   `json:"title,omitempty"`
	Members      []string `json:"members,omitempty"`
	ShareHistory bool     `json:"share_history,omitempty"`
	NextManager  string   `json:"next_manager,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Operation` | `string` | Requested operation, with values defined by that endpoint. |
| `Version` | `int` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Title` | `string` | Optional short label. A normal message does not require a title. |
| `Members` | `[]string` | Directory-group or chat member identity IDs. Membership never substitutes for contact authority. |
| `ShareHistory` | `bool` | Explicitly disclose earlier history to additions. False by default. |
| `NextManager` | `string` | Existing participant to manage the chat when the current manager leaves. |

## ChatMembershipResult



```go
type ChatMembershipResult struct {
	ConversationID string `json:"conversation_id"`
	Version        int    `json:"version"`
	Left           bool   `json:"left,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `ConversationID` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `Version` | `int` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Left` | `bool` | True when the membership operation removed the caller from the shared conversation. |

## ReplaceRequestInput

ReplaceRequest retires an own pending request and sends a fresh decision to
its unchanged audience. Keep the key stable when retrying an unknown result.


```go
type ReplaceRequestInput struct {
	Version  int       `json:"version"`
	Body     string    `json:"body"`
	Mentions []Mention `json:"mentions,omitempty"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Version` | `int` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `Body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `Mentions` | `[]Mention` | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |

## ReplacedRequest



```go
type ReplacedRequest struct {
	Previous    Request `json:"previous"`
	Replacement Request `json:"replacement"`
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `Previous` | `Request` | Original request after supersession. |
| `Replacement` | `Request` | New pending request; future decisions use this ID. |