appserver

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package appserver implements the Codex app-server protocol surface used by Intercom. Wire shapes track Codex's experimental generated schema.

Codex app-server uses JSON-RPC-shaped messages without the "jsonrpc":"2.0" member. Unknown object fields are intentionally ignored by encoding/json so additive protocol changes remain forward compatible.

Index

Constants

View Source 
const (
	DefaultMaxMessageSize        int64 = 128 << 20
	DefaultMaxConcurrentHandlers       = 64
)
View Source 
const (
	MethodInitialize          = "initialize"
	MethodInitialized         = "initialized"
	MethodThreadStart         = "thread/start"
	MethodThreadResume        = "thread/resume"
	MethodThreadFork          = "thread/fork"
	MethodThreadList          = "thread/list"
	MethodThreadRead          = "thread/read"
	MethodThreadGoalGet       = "thread/goal/get"
	MethodThreadUnsubscribe   = "thread/unsubscribe"
	MethodTurnStart           = "turn/start"
	MethodTurnInterrupt       = "turn/interrupt"
	MethodMCPServerStatusList = "mcpServerStatus/list"
)

Method names used by the minimal managed-thread client.

View Source 
const (
	MethodCommandExecutionApproval = "item/commandExecution/requestApproval"
	MethodFileChangeApproval       = "item/fileChange/requestApproval"
	MethodToolRequestUserInput     = "item/tool/requestUserInput"
	MethodMCPServerElicitation     = "mcpServer/elicitation/request"
	MethodPermissionsApproval      = "item/permissions/requestApproval"
	MethodDynamicToolCall          = "item/tool/call"
	MethodChatGPTAuthTokensRefresh = "account/chatgptAuthTokens/refresh"
	MethodAttestationGenerate      = "attestation/generate"
	MethodCurrentTimeRead          = "currentTime/read"
	MethodLegacyApplyPatchApproval = "applyPatchApproval"
	MethodLegacyExecApproval       = "execCommandApproval"
)

Reverse request methods consumed by Intercom.

View Source 
const (
	NotificationError                         = "error"
	NotificationThreadStarted                 = "thread/started"
	NotificationThreadGoalUpdated             = "thread/goal/updated"
	NotificationThreadGoalCleared             = "thread/goal/cleared"
	NotificationTurnStarted                   = "turn/started"
	NotificationTurnCompleted                 = "turn/completed"
	NotificationItemStarted                   = "item/started"
	NotificationItemCompleted                 = "item/completed"
	NotificationMCPServerStartupStatusUpdated = "mcpServer/startupStatus/updated"
)

Lifecycle notifications used by the managed-thread controller. Other notification methods remain available through Notification's raw payload.

View Source 
const (
	ErrorCodeInvalidRequest = int64(-32600)
	ErrorCodeMethodNotFound = int64(-32601)
	ErrorCodeInvalidParams  = int64(-32602)
	ErrorCodeInternal       = int64(-32603)
)
View Source 
const (
	ThreadStatusNotLoaded   = "notLoaded"
	ThreadStatusIdle        = "idle"
	ThreadStatusSystemError = "systemError"
	ThreadStatusActive      = "active"
)
View Source 
const (
	TurnStatusCompleted   = "completed"
	TurnStatusInterrupted = "interrupted"
	TurnStatusFailed      = "failed"
	TurnStatusInProgress  = "inProgress"
)
View Source 
const (
	ThreadGoalStatusActive        = "active"
	ThreadGoalStatusPaused        = "paused"
	ThreadGoalStatusBlocked       = "blocked"
	ThreadGoalStatusUsageLimited  = "usageLimited"
	ThreadGoalStatusBudgetLimited = "budgetLimited"
	ThreadGoalStatusComplete      = "complete"
)
View Source 
const (
	CommandExecutionDecisionAccept           = "accept"
	CommandExecutionDecisionAcceptForSession = "acceptForSession"
	CommandExecutionDecisionDecline          = "decline"
	CommandExecutionDecisionCancel           = "cancel"
)
View Source 
const (
	FileChangeDecisionAccept           = "accept"
	FileChangeDecisionAcceptForSession = "acceptForSession"
	FileChangeDecisionDecline          = "decline"
	FileChangeDecisionCancel           = "cancel"
)
View Source 
const (
	PermissionGrantScopeTurn    = "turn"
	PermissionGrantScopeSession = "session"
)
View Source 
const (
	LegacyReviewDecisionApproved           = "approved"
	LegacyReviewDecisionApprovedForSession = "approved_for_session"
	LegacyReviewDecisionDenied             = "denied"
	LegacyReviewDecisionTimedOut           = "timed_out"
	LegacyReviewDecisionAbort              = "abort"
)

Legacy approval requests use ReviewDecision, whose denial spellings differ from the v2 approval methods above.

View Source 
const MinimumSupportedVersion = "0.144.1"

MinimumSupportedVersion is the oldest Codex CLI version whose experimental app-server contract Intercom supports. Later versions are accepted and validated against the protocol surface Intercom consumes.

Variables

View Source 
var (
	ErrClosed              = errors.New("appserver: client closed")
	ErrMessageTooLarge     = errors.New("appserver: websocket message too large")
	ErrBinaryMessage       = errors.New("appserver: binary websocket message")
	ErrUnknownResponseID   = errors.New("appserver: unknown response id")
	ErrDuplicateResponseID = errors.New("appserver: duplicate response id")
	ErrAlreadyResponded    = errors.New("appserver: reverse request already answered")
	ErrHandlerLimit        = errors.New("appserver: concurrent reverse request limit exceeded")
)

Functions

func ParseUnixEndpoint 

func ParseUnixEndpoint(endpoint string) (string, error)

ParseUnixEndpoint validates the explicit unix:///absolute/path form used by the managed adapter and returns its decoded filesystem path.

Types

type ActivePermissionProfile 

type ActivePermissionProfile struct {
	ID      string  `json:"id"`
	Extends *string `json:"extends"`
}

type ApprovalPolicyName 

type ApprovalPolicyName string
const (
	ApprovalUntrusted ApprovalPolicyName = "untrusted"
	ApprovalOnRequest ApprovalPolicyName = "on-request"
	ApprovalNever     ApprovalPolicyName = "never"
)

type ApprovalsReviewer 

type ApprovalsReviewer string
const (
	ApprovalsReviewerUser       ApprovalsReviewer = "user"
	ApprovalsReviewerAutoReview ApprovalsReviewer = "auto_review"
	ApprovalsReviewerGuardian   ApprovalsReviewer = "guardian_subagent"
)

type AttestationGenerateParams 

type AttestationGenerateParams struct{}

type AttestationGenerateResponse 

type AttestationGenerateResponse struct {
	Token string `json:"token"`
}

type ByteRange 

type ByteRange struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

type ChatGPTAuthTokensRefreshParams 

type ChatGPTAuthTokensRefreshParams struct {
	Reason            string  `json:"reason"`
	PreviousAccountID *string `json:"previousAccountId,omitempty"`
}

type ChatGPTAuthTokensRefreshResponse 

type ChatGPTAuthTokensRefreshResponse struct {
	AccessToken      string  `json:"accessToken"`
	ChatGPTAccountID string  `json:"chatgptAccountId"`
	ChatGPTPlanType  *string `json:"chatgptPlanType"`
}

type Client 

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

Client owns one app-server websocket connection and its request IDs.

func DialUnix 

func DialUnix(ctx context.Context, endpoint string, opts Options) (*Client, error)

DialUnix performs a standard websocket HTTP Upgrade over the endpoint's Unix-domain socket. The synthetic ws://localhost/ URL supplies only the HTTP request target and Host header; the transport cannot fall back to TCP.

func (*Client) Call 

func (c *Client) Call(ctx context.Context, method string, params, result any) error

Call sends a request and waits for its matching result or error.

func (*Client) Close 

func (c *Client) Close() error

Close closes only this websocket client. It does not stop app-server.

func (*Client) Done 

func (c *Client) Done() <-chan struct{}

Done closes when the reader exits or Close is called.

func (*Client) Initialize 

func (c *Client) Initialize(ctx context.Context, params InitializeParams) (InitializeResponse, error)

func (*Client) Initialized 

func (c *Client) Initialized(ctx context.Context) error

func (*Client) MCPServerStatusList added in v0.2.2 

func (c *Client) MCPServerStatusList(ctx context.Context, params MCPServerStatusListParams) (MCPServerStatusListResponse, error)

func (*Client) Notify 

func (c *Client) Notify(ctx context.Context, method string, params any) error

Notify sends a client notification such as initialized.

func (*Client) StartCall 

func (c *Client) StartCall(ctx context.Context, method string, params any) (*PendingCall, error)

StartCall registers response correlation before writing the request, so a fast response cannot race past the pending map.

func (*Client) StartTurn 

func (c *Client) StartTurn(ctx context.Context, params TurnStartParams) (TurnStartAwait, error)

func (*Client) ThreadFork added in v0.2.2 

func (c *Client) ThreadFork(ctx context.Context, params ThreadForkParams) (ThreadForkResponse, error)

func (*Client) ThreadGoalGet added in v0.2.4 

func (c *Client) ThreadGoalGet(ctx context.Context, params ThreadGoalGetParams) (ThreadGoalGetResponse, error)

func (*Client) ThreadList added in v0.2.2 

func (c *Client) ThreadList(ctx context.Context, params ThreadListParams) (ThreadListResponse, error)

func (*Client) ThreadRead 

func (c *Client) ThreadRead(ctx context.Context, params ThreadReadParams) (ThreadReadResponse, error)

func (*Client) ThreadResume 

func (c *Client) ThreadResume(ctx context.Context, params ThreadResumeParams) (ThreadResumeResponse, error)

func (*Client) ThreadStart 

func (c *Client) ThreadStart(ctx context.Context, params ThreadStartParams) (ThreadStartResponse, error)

func (*Client) TurnInterrupt 

func (c *Client) TurnInterrupt(ctx context.Context, params TurnInterruptParams) error

func (*Client) TurnStart 

func (c *Client) TurnStart(ctx context.Context, params TurnStartParams) (TurnStartResponse, error)

func (*Client) Wait 

func (c *Client) Wait() error

Wait waits for connection termination. It returns nil for a local Close, io.EOF for a peer websocket close, or the fatal protocol/transport error.

func (*Client) WaitHandlers 

func (c *Client) WaitHandlers(ctx context.Context) error

WaitHandlers waits for reverse-request handlers that were dispatched by the reader. Lifecycle callers invoke this after observing a terminal turn event, which establishes that no later reverse requests belong to the turn.

type ClientInfo 

type ClientInfo struct {
	Name    string  `json:"name"`
	Title   *string `json:"title"`
	Version string  `json:"version"`
}

type CommandExecutionRequestApprovalParams 

type CommandExecutionRequestApprovalParams struct {
	ThreadID              string            `json:"threadId"`
	TurnID                string            `json:"turnId"`
	ItemID                string            `json:"itemId"`
	StartedAtMS           int64             `json:"startedAtMs"`
	ApprovalID            *string           `json:"approvalId,omitempty"`
	EnvironmentID         *string           `json:"environmentId"`
	Reason                *string           `json:"reason,omitempty"`
	Command               *string           `json:"command,omitempty"`
	CWD                   *string           `json:"cwd,omitempty"`
	CommandActions        json.RawMessage   `json:"commandActions,omitempty"`
	AdditionalPermissions json.RawMessage   `json:"additionalPermissions,omitempty"`
	AvailableDecisions    []json.RawMessage `json:"availableDecisions,omitempty"`
}

The approval request types retain large, evolving nested objects as raw JSON while typing the routing and denial fields Intercom needs.

type CommandExecutionRequestApprovalResponse 

type CommandExecutionRequestApprovalResponse struct {
	Decision any `json:"decision"`
}

type CurrentTimeReadParams 

type CurrentTimeReadParams struct {
	ThreadID string `json:"threadId"`
}

type CurrentTimeReadResponse 

type CurrentTimeReadResponse struct {
	CurrentTimeAt int64 `json:"currentTimeAt"`
}

type DynamicToolCallOutputContentItem 

type DynamicToolCallOutputContentItem struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	ImageURL string `json:"imageUrl,omitempty"`
}

func DynamicToolText 

func DynamicToolText(text string) DynamicToolCallOutputContentItem

type DynamicToolCallParams 

type DynamicToolCallParams struct {
	ThreadID  string          `json:"threadId"`
	TurnID    string          `json:"turnId"`
	CallID    string          `json:"callId"`
	Namespace *string         `json:"namespace"`
	Tool      string          `json:"tool"`
	Arguments json.RawMessage `json:"arguments"`
}

type DynamicToolCallResponse 

type DynamicToolCallResponse struct {
	ContentItems []DynamicToolCallOutputContentItem `json:"contentItems"`
	Success      bool                               `json:"success"`
}

type DynamicToolNamespaceTool 

type DynamicToolNamespaceTool struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	InputSchema  any    `json:"inputSchema"`
	DeferLoading bool   `json:"deferLoading,omitempty"`
}

type DynamicToolSpec 

type DynamicToolSpec struct {
	Type         string                     `json:"type"`
	Name         string                     `json:"name"`
	Description  string                     `json:"description"`
	InputSchema  any                        `json:"inputSchema,omitempty"`
	DeferLoading bool                       `json:"deferLoading,omitempty"`
	Tools        []DynamicToolNamespaceTool `json:"tools,omitempty"`
}

DynamicToolSpec is the flattened function-or-namespace dynamic tool union. Intercom uses Type "function".

type ErrorNotification 

type ErrorNotification struct {
	Error     TurnError `json:"error"`
	WillRetry bool      `json:"willRetry"`
	ThreadID  string    `json:"threadId"`
	TurnID    string    `json:"turnId"`
}

type FileChangeRequestApprovalParams 

type FileChangeRequestApprovalParams struct {
	ThreadID    string  `json:"threadId"`
	TurnID      string  `json:"turnId"`
	ItemID      string  `json:"itemId"`
	StartedAtMS int64   `json:"startedAtMs"`
	Reason      *string `json:"reason,omitempty"`
	GrantRoot   *string `json:"grantRoot,omitempty"`
}

type FileChangeRequestApprovalResponse 

type FileChangeRequestApprovalResponse struct {
	Decision string `json:"decision"`
}

type GrantedPermissionProfile 

type GrantedPermissionProfile struct {
	Network    json.RawMessage `json:"network,omitempty"`
	FileSystem json.RawMessage `json:"fileSystem,omitempty"`
}

type InitializeCapabilities 

type InitializeCapabilities struct {
	ExperimentalAPI                bool     `json:"experimentalApi"`
	RequestAttestation             bool     `json:"requestAttestation"`
	MCPServerOpenAIFormElicitation bool     `json:"mcpServerOpenaiFormElicitation,omitempty"`
	OptOutNotificationMethods      []string `json:"optOutNotificationMethods,omitempty"`
}

type InitializeParams 

type InitializeParams struct {
	ClientInfo   ClientInfo              `json:"clientInfo"`
	Capabilities *InitializeCapabilities `json:"capabilities"`
}

type InitializeResponse 

type InitializeResponse struct {
	UserAgent      string `json:"userAgent"`
	CodexHome      string `json:"codexHome"`
	PlatformFamily string `json:"platformFamily"`
	PlatformOS     string `json:"platformOs"`
}

type ItemNotification 

type ItemNotification struct {
	Item          json.RawMessage `json:"item"`
	ThreadID      string          `json:"threadId"`
	TurnID        string          `json:"turnId"`
	StartedAtMS   *int64          `json:"startedAtMs,omitempty"`
	CompletedAtMS *int64          `json:"completedAtMs,omitempty"`
}

type LegacyApplyPatchApprovalParams 

type LegacyApplyPatchApprovalParams struct {
	ConversationID string                     `json:"conversationId"`
	CallID         string                     `json:"callId"`
	FileChanges    map[string]json.RawMessage `json:"fileChanges"`
	Reason         *string                    `json:"reason"`
	GrantRoot      *string                    `json:"grantRoot"`
}

type LegacyApprovalResponse 

type LegacyApprovalResponse struct {
	Decision any `json:"decision"`
}

type LegacyExecCommandApprovalParams 

type LegacyExecCommandApprovalParams struct {
	ConversationID string            `json:"conversationId"`
	CallID         string            `json:"callId"`
	ApprovalID     *string           `json:"approvalId"`
	Command        []string          `json:"command"`
	CWD            string            `json:"cwd"`
	Reason         *string           `json:"reason"`
	ParsedCommand  []json.RawMessage `json:"parsedCmd"`
}

type MCPAuthStatus added in v0.2.2 

type MCPAuthStatus string
const (
	MCPAuthUnsupported MCPAuthStatus = "unsupported"
	MCPAuthNotLoggedIn MCPAuthStatus = "notLoggedIn"
	MCPAuthBearerToken MCPAuthStatus = "bearerToken"
	MCPAuthOAuth       MCPAuthStatus = "oAuth"
)

type MCPResource added in v0.2.2 

type MCPResource struct {
	Annotations json.RawMessage   `json:"annotations,omitempty"`
	Description *string           `json:"description,omitempty"`
	MIMEType    *string           `json:"mimeType,omitempty"`
	Name        string            `json:"name"`
	Size        *int64            `json:"size,omitempty"`
	Title       *string           `json:"title,omitempty"`
	URI         string            `json:"uri"`
	Icons       []json.RawMessage `json:"icons,omitempty"`
	Meta        json.RawMessage   `json:"_meta,omitempty"`
}

type MCPResourceTemplate added in v0.2.2 

type MCPResourceTemplate struct {
	Annotations json.RawMessage `json:"annotations,omitempty"`
	URITemplate string          `json:"uriTemplate"`
	Name        string          `json:"name"`
	Title       *string         `json:"title,omitempty"`
	Description *string         `json:"description,omitempty"`
	MIMEType    *string         `json:"mimeType,omitempty"`
}

type MCPServerElicitationRequestParams 

type MCPServerElicitationRequestParams struct {
	ThreadID        string          `json:"threadId"`
	TurnID          *string         `json:"turnId"`
	ServerName      string          `json:"serverName"`
	Mode            string          `json:"mode"`
	Meta            json.RawMessage `json:"_meta"`
	Message         string          `json:"message"`
	RequestedSchema json.RawMessage `json:"requestedSchema,omitempty"`
	URL             string          `json:"url,omitempty"`
	ElicitationID   string          `json:"elicitationId,omitempty"`
}

type MCPServerElicitationRequestResponse 

type MCPServerElicitationRequestResponse struct {
	Action  string          `json:"action"`
	Content json.RawMessage `json:"content"`
	Meta    json.RawMessage `json:"_meta"`
}

type MCPServerInfo added in v0.2.2 

type MCPServerInfo struct {
	Name        string            `json:"name"`
	Title       *string           `json:"title"`
	Version     string            `json:"version"`
	Description *string           `json:"description"`
	Icons       []json.RawMessage `json:"icons"`
	WebsiteURL  *string           `json:"websiteUrl"`
}

type MCPServerStartupState added in v0.2.2 

type MCPServerStartupState string
const (
	MCPServerStarting  MCPServerStartupState = "starting"
	MCPServerReady     MCPServerStartupState = "ready"
	MCPServerFailed    MCPServerStartupState = "failed"
	MCPServerCancelled MCPServerStartupState = "cancelled"
)

type MCPServerStatus added in v0.2.2 

type MCPServerStatus struct {
	Name              string                `json:"name"`
	ServerInfo        *MCPServerInfo        `json:"serverInfo"`
	Tools             map[string]MCPTool    `json:"tools"`
	Resources         []MCPResource         `json:"resources"`
	ResourceTemplates []MCPResourceTemplate `json:"resourceTemplates"`
	AuthStatus        MCPAuthStatus         `json:"authStatus"`
}

type MCPServerStatusDetail added in v0.2.2 

type MCPServerStatusDetail string
const (
	MCPServerStatusFull             MCPServerStatusDetail = "full"
	MCPServerStatusToolsAndAuthOnly MCPServerStatusDetail = "toolsAndAuthOnly"
)

type MCPServerStatusListParams added in v0.2.2 

type MCPServerStatusListParams struct {
	Cursor   *string                `json:"cursor,omitempty"`
	Limit    *uint32                `json:"limit,omitempty"`
	Detail   *MCPServerStatusDetail `json:"detail,omitempty"`
	ThreadID *string                `json:"threadId,omitempty"`
}

type MCPServerStatusListResponse added in v0.2.2 

type MCPServerStatusListResponse struct {
	Data       []MCPServerStatus `json:"data"`
	NextCursor *string           `json:"nextCursor"`
}

type MCPServerStatusUpdatedNotification added in v0.2.2 

type MCPServerStatusUpdatedNotification struct {
	ThreadID      *string               `json:"threadId"`
	Name          string                `json:"name"`
	Status        MCPServerStartupState `json:"status"`
	Error         *string               `json:"error"`
	FailureReason *string               `json:"failureReason"`
}

type MCPTool added in v0.2.2 

type MCPTool struct {
	Name         string            `json:"name"`
	Title        *string           `json:"title,omitempty"`
	Description  *string           `json:"description,omitempty"`
	InputSchema  json.RawMessage   `json:"inputSchema"`
	OutputSchema json.RawMessage   `json:"outputSchema,omitempty"`
	Annotations  json.RawMessage   `json:"annotations,omitempty"`
	Icons        []json.RawMessage `json:"icons,omitempty"`
	Meta         json.RawMessage   `json:"_meta,omitempty"`
}

type Notification 

type Notification struct {
	Method string
	Params json.RawMessage
}

Notification is a raw, forward-compatible app-server notification.

func (Notification) DecodeParams 

func (n Notification) DecodeParams(dst any) error

type Options 

type Options struct {
	// MaxMessageSize bounds each inbound and outbound JSON message. Values at
	// or below zero use DefaultMaxMessageSize.
	MaxMessageSize int64
	// MaxConcurrentHandlers bounds independently running reverse-request
	// callbacks. Exceeding the limit is a fatal protocol error rather than
	// blocking the ordered reader. Values at or below zero use the default.
	MaxConcurrentHandlers int
	OnNotification        func(Notification)
	// OnReverseRequestReceived runs synchronously on the ordered reader before
	// the request handler is scheduled. It must return promptly and must not
	// answer the request. Lifecycle owners can use it to close startup races
	// without performing any I/O.
	OnReverseRequestReceived func(*ReverseRequest)
	// OnReverseRequest runs on an independent goroutine and may perform I/O.
	OnReverseRequest func(*ReverseRequest)
}

Options configures protocol dispatch. Notification callbacks execute on the ordered reader goroutine and therefore must return promptly. Reverse request callbacks execute on independent goroutines so an approval or tool handler can wait without blocking lifecycle messages or normal responses.

type PendingCall 

type PendingCall struct {
	ID RequestID
	// contains filtered or unexported fields
}

PendingCall is a request that has been written and is awaiting a response. It exposes the request ID for state machines that correlate early events.

func (*PendingCall) Await 

func (p *PendingCall) Await(ctx context.Context, result any) error

Await waits once for a PendingCall. A canceled deadline replaces live correlation with a bounded tombstone so one late response is ignored. Managed callers must still decide whether a mutating-request timeout makes their higher-level state ambiguous.

type PermissionsRequestApprovalParams 

type PermissionsRequestApprovalParams struct {
	ThreadID      string          `json:"threadId"`
	TurnID        string          `json:"turnId"`
	ItemID        string          `json:"itemId"`
	EnvironmentID *string         `json:"environmentId"`
	StartedAtMS   int64           `json:"startedAtMs"`
	CWD           string          `json:"cwd"`
	Reason        *string         `json:"reason"`
	Permissions   json.RawMessage `json:"permissions"`
}

type PermissionsRequestApprovalResponse 

type PermissionsRequestApprovalResponse struct {
	Permissions      GrantedPermissionProfile `json:"permissions"`
	Scope            string                   `json:"scope"`
	StrictAutoReview bool                     `json:"strictAutoReview,omitempty"`
}

type RPCError 

type RPCError struct {
	Code    int64           `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

RPCError is an app-server error response. It also implements error.

func (*RPCError) Error 

func (e *RPCError) Error() string

type RequestID 

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

RequestID is the protocol's string-or-signed-integer request identifier. It is comparable and can therefore be used directly as a map key.

func NumberRequestID 

func NumberRequestID(id int64) RequestID

func StringRequestID 

func StringRequestID(id string) RequestID

func (RequestID) IsZero 

func (id RequestID) IsZero() bool

func (RequestID) MarshalJSON 

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

func (RequestID) Number 

func (id RequestID) Number() (int64, bool)

func (RequestID) String 

func (id RequestID) String() string

func (RequestID) Text 

func (id RequestID) Text() (string, bool)

func (*RequestID) UnmarshalJSON 

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

type ReverseRequest 

type ReverseRequest struct {
	ID     RequestID
	Method string
	Params json.RawMessage
	// contains filtered or unexported fields
}

ReverseRequest is an app-server-initiated request. A handler must answer it exactly once with Respond or RespondError.

func (*ReverseRequest) DecodeParams 

func (r *ReverseRequest) DecodeParams(dst any) error

func (*ReverseRequest) Respond 

func (r *ReverseRequest) Respond(ctx context.Context, result any) error

func (*ReverseRequest) RespondError 

func (r *ReverseRequest) RespondError(ctx context.Context, rpcErr *RPCError) error

type SandboxMode 

type SandboxMode string
const (
	SandboxReadOnly         SandboxMode = "read-only"
	SandboxWorkspaceWrite   SandboxMode = "workspace-write"
	SandboxDangerFullAccess SandboxMode = "danger-full-access"
)

type SandboxPolicy 

type SandboxPolicy struct {
	Type                string   `json:"type"`
	NetworkAccess       any      `json:"networkAccess,omitempty"`
	WritableRoots       []string `json:"writableRoots,omitempty"`
	ExcludeTmpdirEnvVar bool     `json:"excludeTmpdirEnvVar,omitempty"`
	ExcludeSlashTmp     bool     `json:"excludeSlashTmp,omitempty"`
}

SandboxPolicy is the superset of the sandbox-policy variants in the baseline generated schema. Fields that do not apply to Type are omitted.

type SortDirection added in v0.2.2 

type SortDirection string
const (
	SortAscending  SortDirection = "asc"
	SortDescending SortDirection = "desc"
)

type TextElement 

type TextElement struct {
	ByteRange   ByteRange `json:"byteRange"`
	Placeholder *string   `json:"placeholder"`
}

type Thread 

type Thread struct {
	ID             string          `json:"id"`
	Extra          json.RawMessage `json:"extra"`
	SessionID      string          `json:"sessionId"`
	ForkedFromID   *string         `json:"forkedFromId"`
	ParentThreadID *string         `json:"parentThreadId"`
	Preview        string          `json:"preview"`
	Ephemeral      bool            `json:"ephemeral"`
	HistoryMode    string          `json:"historyMode"`
	ModelProvider  string          `json:"modelProvider"`
	CreatedAt      int64           `json:"createdAt"`
	UpdatedAt      int64           `json:"updatedAt"`
	RecencyAt      *int64          `json:"recencyAt"`
	Status         ThreadStatus    `json:"status"`
	Path           *string         `json:"path"`
	CWD            string          `json:"cwd"`
	CLIVersion     string          `json:"cliVersion"`
	Source         json.RawMessage `json:"source"`
	ThreadSource   json.RawMessage `json:"threadSource"`
	AgentNickname  *string         `json:"agentNickname"`
	AgentRole      *string         `json:"agentRole"`
	GitInfo        json.RawMessage `json:"gitInfo"`
	Name           *string         `json:"name"`
	Turns          []Turn          `json:"turns"`
}

type ThreadForkParams added in v0.2.2 

type ThreadForkParams struct {
	ThreadID              string             `json:"threadId"`
	LastTurnID            *string            `json:"lastTurnId,omitempty"`
	Path                  *string            `json:"path,omitempty"`
	Model                 *string            `json:"model,omitempty"`
	ModelProvider         *string            `json:"modelProvider,omitempty"`
	ServiceTier           *string            `json:"serviceTier,omitempty"`
	CWD                   *string            `json:"cwd,omitempty"`
	RuntimeWorkspaceRoots []string           `json:"runtimeWorkspaceRoots,omitempty"`
	ApprovalPolicy        any                `json:"approvalPolicy,omitempty"`
	ApprovalsReviewer     *ApprovalsReviewer `json:"approvalsReviewer,omitempty"`
	Sandbox               *SandboxMode       `json:"sandbox,omitempty"`
	Permissions           *string            `json:"permissions,omitempty"`
	Config                map[string]any     `json:"config,omitempty"`
	BaseInstructions      *string            `json:"baseInstructions,omitempty"`
	DeveloperInstructions *string            `json:"developerInstructions,omitempty"`
	Ephemeral             bool               `json:"ephemeral,omitempty"`
	ThreadSource          *string            `json:"threadSource,omitempty"`
	ExcludeTurns          bool               `json:"excludeTurns,omitempty"`
}

ThreadForkParams describes a non-destructive copy of a materialized thread. ThreadID is preferred over Path; a non-empty Path takes precedence when both are present, as specified by app-server.

type ThreadForkResponse added in v0.2.2 

type ThreadForkResponse struct{ ThreadResponse }

type ThreadGoal added in v0.2.4 

type ThreadGoal struct {
	ThreadID string `json:"threadId"`
	Status   string `json:"status"`
}

type ThreadGoalClearedNotification added in v0.2.4 

type ThreadGoalClearedNotification struct {
	ThreadID string `json:"threadId"`
}

type ThreadGoalGetParams added in v0.2.4 

type ThreadGoalGetParams struct {
	ThreadID string `json:"threadId"`
}

type ThreadGoalGetResponse added in v0.2.4 

type ThreadGoalGetResponse struct {
	Goal *ThreadGoal `json:"goal"`
}

type ThreadGoalUpdatedNotification added in v0.2.4 

type ThreadGoalUpdatedNotification struct {
	ThreadID string     `json:"threadId"`
	TurnID   *string    `json:"turnId"`
	Goal     ThreadGoal `json:"goal"`
}

type ThreadListParams added in v0.2.2 

type ThreadListParams struct {
	Cursor           *string            `json:"cursor,omitempty"`
	Limit            *uint32            `json:"limit,omitempty"`
	SortKey          *ThreadSortKey     `json:"sortKey,omitempty"`
	SortDirection    *SortDirection     `json:"sortDirection,omitempty"`
	ModelProviders   []string           `json:"modelProviders,omitempty"`
	SourceKinds      []ThreadSourceKind `json:"sourceKinds,omitempty"`
	Archived         *bool              `json:"archived,omitempty"`
	CWD              any                `json:"cwd,omitempty"`
	UseStateDBOnly   bool               `json:"useStateDbOnly,omitempty"`
	SearchTerm       *string            `json:"searchTerm,omitempty"`
	ParentThreadID   *string            `json:"parentThreadId,omitempty"`
	AncestorThreadID *string            `json:"ancestorThreadId,omitempty"`
}

ThreadListParams mirrors the app-server list filters. CWD accepts either a string or []string, matching the protocol's ThreadListCwdFilter union.

type ThreadListResponse added in v0.2.2 

type ThreadListResponse struct {
	Data            []Thread `json:"data"`
	NextCursor      *string  `json:"nextCursor"`
	BackwardsCursor *string  `json:"backwardsCursor"`
}

type ThreadReadParams 

type ThreadReadParams struct {
	ThreadID     string `json:"threadId"`
	IncludeTurns bool   `json:"includeTurns,omitempty"`
}

type ThreadReadResponse 

type ThreadReadResponse struct {
	Thread Thread `json:"thread"`
}

type ThreadResponse 

type ThreadResponse struct {
	Thread                  Thread                   `json:"thread"`
	Model                   string                   `json:"model"`
	ModelProvider           string                   `json:"modelProvider"`
	ServiceTier             *string                  `json:"serviceTier"`
	CWD                     string                   `json:"cwd"`
	RuntimeWorkspaceRoots   []string                 `json:"runtimeWorkspaceRoots"`
	InstructionSources      []string                 `json:"instructionSources"`
	ApprovalPolicy          any                      `json:"approvalPolicy"`
	ApprovalsReviewer       ApprovalsReviewer        `json:"approvalsReviewer"`
	Sandbox                 SandboxPolicy            `json:"sandbox"`
	ActivePermissionProfile *ActivePermissionProfile `json:"activePermissionProfile"`
	ReasoningEffort         *string                  `json:"reasoningEffort"`
	MultiAgentMode          any                      `json:"multiAgentMode"`
}

ThreadResponse contains the common settings returned by thread/start and thread/resume.

type ThreadResumeParams 

type ThreadResumeParams struct {
	ThreadID              string             `json:"threadId"`
	Model                 *string            `json:"model,omitempty"`
	ModelProvider         *string            `json:"modelProvider,omitempty"`
	CWD                   *string            `json:"cwd,omitempty"`
	RuntimeWorkspaceRoots []string           `json:"runtimeWorkspaceRoots,omitempty"`
	ApprovalPolicy        any                `json:"approvalPolicy,omitempty"`
	ApprovalsReviewer     *ApprovalsReviewer `json:"approvalsReviewer,omitempty"`
	Sandbox               *SandboxMode       `json:"sandbox,omitempty"`
	Config                map[string]any     `json:"config,omitempty"`
	BaseInstructions      *string            `json:"baseInstructions,omitempty"`
	DeveloperInstructions *string            `json:"developerInstructions,omitempty"`
	ExcludeTurns          bool               `json:"excludeTurns,omitempty"`
}

type ThreadResumeResponse 

type ThreadResumeResponse struct {
	ThreadResponse
	InitialTurnsPage json.RawMessage `json:"initialTurnsPage"`
}

type ThreadSortKey added in v0.2.2 

type ThreadSortKey string
const (
	ThreadSortCreatedAt ThreadSortKey = "created_at"
	ThreadSortUpdatedAt ThreadSortKey = "updated_at"
	ThreadSortRecencyAt ThreadSortKey = "recency_at"
)

type ThreadSourceKind added in v0.2.2 

type ThreadSourceKind string
const (
	ThreadSourceCLI                 ThreadSourceKind = "cli"
	ThreadSourceVSCode              ThreadSourceKind = "vscode"
	ThreadSourceExec                ThreadSourceKind = "exec"
	ThreadSourceAppServer           ThreadSourceKind = "appServer"
	ThreadSourceSubAgent            ThreadSourceKind = "subAgent"
	ThreadSourceSubAgentReview      ThreadSourceKind = "subAgentReview"
	ThreadSourceSubAgentCompact     ThreadSourceKind = "subAgentCompact"
	ThreadSourceSubAgentThreadSpawn ThreadSourceKind = "subAgentThreadSpawn"
	ThreadSourceSubAgentOther       ThreadSourceKind = "subAgentOther"
	ThreadSourceUnknown             ThreadSourceKind = "unknown"
)

type ThreadStartParams 

type ThreadStartParams struct {
	Model                 *string            `json:"model,omitempty"`
	ModelProvider         *string            `json:"modelProvider,omitempty"`
	CWD                   *string            `json:"cwd,omitempty"`
	RuntimeWorkspaceRoots []string           `json:"runtimeWorkspaceRoots,omitempty"`
	ApprovalPolicy        any                `json:"approvalPolicy,omitempty"`
	ApprovalsReviewer     *ApprovalsReviewer `json:"approvalsReviewer,omitempty"`
	Sandbox               *SandboxMode       `json:"sandbox,omitempty"`
	Config                map[string]any     `json:"config,omitempty"`
	BaseInstructions      *string            `json:"baseInstructions,omitempty"`
	DeveloperInstructions *string            `json:"developerInstructions,omitempty"`
	Ephemeral             *bool              `json:"ephemeral,omitempty"`
	DynamicTools          []DynamicToolSpec  `json:"dynamicTools,omitempty"`
}

type ThreadStartResponse 

type ThreadStartResponse struct{ ThreadResponse }

type ThreadStartedNotification 

type ThreadStartedNotification struct {
	Thread Thread `json:"thread"`
}

type ThreadStatus 

type ThreadStatus struct {
	Type        string   `json:"type"`
	ActiveFlags []string `json:"activeFlags,omitempty"`
}

type ToolRequestUserInputAnswer 

type ToolRequestUserInputAnswer struct {
	Answers []string `json:"answers"`
}

type ToolRequestUserInputParams 

type ToolRequestUserInputParams struct {
	ThreadID         string            `json:"threadId"`
	TurnID           string            `json:"turnId"`
	ItemID           string            `json:"itemId"`
	Questions        []json.RawMessage `json:"questions"`
	AutoResolutionMS *uint64           `json:"autoResolutionMs"`
}

type ToolRequestUserInputResponse 

type ToolRequestUserInputResponse struct {
	Answers map[string]ToolRequestUserInputAnswer `json:"answers"`
}

type Turn 

type Turn struct {
	ID          string            `json:"id"`
	Items       []json.RawMessage `json:"items"`
	ItemsView   string            `json:"itemsView"`
	Status      string            `json:"status"`
	Error       *TurnError        `json:"error"`
	StartedAt   *int64            `json:"startedAt"`
	CompletedAt *int64            `json:"completedAt"`
	DurationMS  *int64            `json:"durationMs"`
}

type TurnCompletedNotification 

type TurnCompletedNotification struct {
	ThreadID string `json:"threadId"`
	Turn     Turn   `json:"turn"`
}

type TurnError 

type TurnError struct {
	Message           string          `json:"message"`
	CodexErrorInfo    json.RawMessage `json:"codexErrorInfo"`
	AdditionalDetails *string         `json:"additionalDetails"`
}

type TurnInterruptParams 

type TurnInterruptParams struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
}

type TurnInterruptResponse 

type TurnInterruptResponse struct{}

type TurnStartAwait 

type TurnStartAwait func(context.Context) (TurnStartResponse, error)

TurnStartAwait waits for a turn/start response whose request has already been written. Keeping correlation alive independently of the write context lets lifecycle owners drain an ambiguous start during graceful shutdown.

type TurnStartParams 

type TurnStartParams struct {
	ThreadID              string             `json:"threadId"`
	ClientUserMessageID   *string            `json:"clientUserMessageId,omitempty"`
	Input                 []UserInput        `json:"input"`
	CWD                   *string            `json:"cwd,omitempty"`
	RuntimeWorkspaceRoots []string           `json:"runtimeWorkspaceRoots,omitempty"`
	ApprovalPolicy        any                `json:"approvalPolicy,omitempty"`
	ApprovalsReviewer     *ApprovalsReviewer `json:"approvalsReviewer,omitempty"`
	SandboxPolicy         *SandboxPolicy     `json:"sandboxPolicy,omitempty"`
	Permissions           *string            `json:"permissions,omitempty"`
	Model                 *string            `json:"model,omitempty"`
	OutputSchema          any                `json:"outputSchema,omitempty"`
}

type TurnStartResponse 

type TurnStartResponse struct {
	Turn Turn `json:"turn"`
}

type TurnStartedNotification 

type TurnStartedNotification struct {
	ThreadID string `json:"threadId"`
	Turn     Turn   `json:"turn"`
}

type UserInput 

type UserInput struct {
	Type         string        `json:"type"`
	Text         string        `json:"text,omitempty"`
	TextElements []TextElement `json:"text_elements"`
	URL          string        `json:"url,omitempty"`
	Path         string        `json:"path,omitempty"`
	Name         string        `json:"name,omitempty"`
	Detail       string        `json:"detail,omitempty"`
}

UserInput is the flattened input union. Text inputs must carry a text_elements array, whose generated wire name uses snake case.

func TextInput 

func TextInput(text string) UserInput

Source Files

View all Source files

Jump to

Keyboard shortcuts

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