codex

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package codex implements a genai provider backed by the Codex CLI.

Instead of making HTTP requests directly, it launches `codex app-server` as a subprocess and communicates over stdin/stdout using the JSON-RPC 2.0 protocol.

See https://codex.openai.com/ for Codex CLI documentation.

Protocol

The provider performs a JSON-RPC handshake (initialize → initialized → model/list → thread/start) on each call, then sends a turn/start request and reads notifications until turn/completed.

Session / multi-turn

Each GenSync or GenStream call launches a fresh subprocess. The thread ID is always returned inside Reply.Opaque["thread_id"]. When the message history contains a previous thread ID, it is automatically picked up: thread/resume is used instead of thread/start and only the last user message is sent.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/maruel/genai"
	"github.com/maruel/genai/providers/codex"
)

func main() {
	c, err := codex.New(context.Background(), genai.ProviderOptionModel("gpt-6.1-terra"))
	if c != nil {
		defer func() {
			if err := c.Close(); err != nil {
				log.Printf("Close: %v", err)
			}
		}()
	}
	if err != nil {
		log.Print(err)
		return
	}
	msgs := genai.Messages{genai.NewTextMessage("Say hello")}
	res, err := c.GenSync(context.Background(), msgs, genai.EffortHigh)
	if err != nil {
		log.Print(err)
		return
	}
	fmt.Println(res.Replies[0].Text)
}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Scoreboard 

func Scoreboard() scoreboard.Score

Scoreboard for the Codex CLI provider.

Types

type AccountLoginCompletedNotification added in v0.7.0 

type AccountLoginCompletedNotification struct {
	LoginID              string                      `json:"loginId,omitzero"`
	Success              bool                        `json:"success"`
	Error                string                      `json:"error,omitzero"`
	OnboardingEntrypoint DesktopOnboardingEntrypoint `json:"onboardingEntrypoint,omitzero"`
}

AccountLoginCompletedNotification holds params for account/login/completed.

type AccountRateLimitsUpdatedNotification added in v0.7.0 

type AccountRateLimitsUpdatedNotification struct {
	RateLimits RateLimitSnapshot `json:"rateLimits"`
}

AccountRateLimitsUpdatedNotification holds params for account/rateLimits/updated.

It is a sparse rolling rate-limit update. Clients should merge available fields into the latest account/rateLimits/read snapshot or refetch it.

type AccountUpdatedNotification added in v0.7.0 

type AccountUpdatedNotification struct {
	AuthMode AuthMode `json:"authMode,omitzero"`
	PlanType PlanType `json:"planType,omitzero"`
}

AccountUpdatedNotification holds params for account/updated.

type ActivePermissionProfile added in v0.6.0 

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

ActivePermissionProfile identifies the permission profile active for a thread.

type AdditionalContextEntry added in v0.6.0 

type AdditionalContextEntry struct {
	Value string                `json:"value"`
	Kind  AdditionalContextKind `json:"kind"`
}

AdditionalContextEntry is one client-provided context fragment.

type AdditionalContextKind added in v0.6.0 

type AdditionalContextKind string

AdditionalContextKind identifies the trust level for turn context fragments. 

const (
	AdditionalContextKindUntrusted   AdditionalContextKind = "untrusted"
	AdditionalContextKindApplication AdditionalContextKind = "application"
)

Additional context kind constants.

type AgentMessageDelivery added in v0.8.0 

type AgentMessageDelivery string

AgentMessageDelivery describes asynchronous message delivery. 

const AgentMessageDeliveryAsync AgentMessageDelivery = "async"

AgentMessageDeliveryAsync identifies an asynchronously delivered message.

type AgentMessageDeltaNotification added in v0.4.1 

type AgentMessageDeltaNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	ItemID   string `json:"itemId"`
	Delta    string `json:"delta"`
}

AgentMessageDeltaNotification holds the params for item/agentMessage/delta notifications.

type AgentMessageItem added in v0.4.1 

type AgentMessageItem struct {
	ID             string                   `json:"id"`
	Type           ItemType                 `json:"type"`
	Text           string                   `json:"text,omitzero"`
	Phase          MessagePhase             `json:"phase,omitzero"`
	MemoryCitation *MemoryCitation          `json:"memoryCitation,omitzero"`
	Delivery       AgentMessageDelivery     `json:"delivery,omitzero"`
	Questions      []AsyncUserInputQuestion `json:"questions,omitzero"`
}

AgentMessageItem is an agent text response item.

type ApprovalsReviewer added in v0.5.6 

type ApprovalsReviewer string

ApprovalsReviewer configures where approval requests are routed. 

const (
	// ApprovalsReviewerUser routes approval requests to the user.
	ApprovalsReviewerUser ApprovalsReviewer = "user"
	// ApprovalsReviewerAutoReview routes approval requests through auto-review.
	ApprovalsReviewerAutoReview ApprovalsReviewer = "auto_review"
	// ApprovalsReviewerGuardianSubagent routes approval requests through a guardian subagent.
	ApprovalsReviewerGuardianSubagent ApprovalsReviewer = "guardian_subagent"
)

Approval reviewer constants.

type AsyncUserInputQuestion added in v0.8.0 

type AsyncUserInputQuestion struct {
	Title   string   `json:"title"`
	Options []string `json:"options,omitzero"`
}

AsyncUserInputQuestion is an asynchronous question attached to an agent message.

type AuthMode added in v0.7.0 

type AuthMode string

AuthMode identifies the active Codex authentication mode. 

const (
	AuthModeAPIKey              AuthMode = "apikey"
	AuthModeChatGPT             AuthMode = "chatgpt"
	AuthModeChatGPTAuthTokens   AuthMode = "chatgptAuthTokens"
	AuthModeAgentIdentity       AuthMode = "agentIdentity"
	AuthModePersonalAccessToken AuthMode = "personalAccessToken"
	AuthModeBedrockAPIKey       AuthMode = "bedrockApiKey"
	AuthModeBedrockAccessKeys   AuthMode = "bedrockAccessKeys"
	AuthModeHeaders             AuthMode = "headers"
)

Auth mode constants.

type AuthRecoveryNotification added in v0.8.0 

type AuthRecoveryNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	Provider string `json:"provider"`
	Message  string `json:"message"`
}

AuthRecoveryNotification holds provider authentication recovery state.

type AutoReviewDecisionSource added in v0.5.6 

type AutoReviewDecisionSource string

AutoReviewDecisionSource identifies what produced an auto-review decision. 

const (
	// AutoReviewDecisionSourceAgent indicates the agent made the auto-review decision.
	AutoReviewDecisionSourceAgent AutoReviewDecisionSource = "agent"
)

Auto-review decision source constants.

type ByteRange added in v0.6.0 

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

ByteRange identifies a byte range in a parent text buffer.

type Capabilities added in v0.4.1 

type Capabilities struct {
	ExperimentalAPI           bool                       `json:"experimentalApi"`
	RequestAttestation        bool                       `json:"requestAttestation"`
	McpServerOpenaiForm       bool                       `json:"mcpServerOpenaiFormElicitation,omitzero"`
	OptOutNotificationMethods []Method                   `json:"optOutNotificationMethods"`
	Extensions                map[string]json.RawMessage `json:"extensions,omitzero"`
}

Capabilities declares client capabilities in the initialize handshake.

type Client 

type Client struct {
	base.NotImplemented
	// contains filtered or unexported fields
}

Client is a genai provider that delegates to the local `codex` CLI.

func New 

func New(_ context.Context, opts ...genai.ProviderOption) (*Client, error)

New creates a Client for the `codex` CLI.

The binary is located lazily on the first call to GenSync, GenStream, or Ping, so New succeeds even when the CLI is not installed.

Supported ProviderOptions:

  • genai.ProviderOptionModel — model ID (e.g. "gpt-6-astra", "gpt-6.1-terra"). genai.ModelCheap, genai.ModelGood, and genai.ModelSOTA are rejected.
  • *ProviderOption — process settings.
  • genai.ProviderOptionStarterWrapper — intercepts subprocess creation.

func (*Client) Capabilities 

func (c *Client) Capabilities() genai.ProviderCapabilities

Capabilities implements genai.Provider.

func (*Client) Close added in v0.9.0 

func (c *Client) Close() error

Close implements io.Closer. It currently does nothing.

func (*Client) GenStream 

func (c *Client) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))

GenStream implements genai.Provider.

func (*Client) GenSync 

func (c *Client) GenSync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (r genai.Result, err error)

GenSync implements genai.Provider.

func (*Client) HTTPClient 

func (c *Client) HTTPClient() *http.Client

HTTPClient implements genai.Provider. The CLI provider does not use HTTP.

func (*Client) ListModels 

func (c *Client) ListModels(ctx context.Context) ([]genai.Model, error)

ListModels implements genai.Provider by querying the codex app-server's model/list RPC. It launches a subprocess, performs the JSON-RPC handshake (initialize → initialized → model/list), and returns the live model list.

func (*Client) ModelID 

func (c *Client) ModelID() string

ModelID implements genai.Provider.

func (*Client) Name 

func (c *Client) Name() string

Name implements genai.Provider.

func (*Client) OutputModalities 

func (c *Client) OutputModalities() genai.Modalities

OutputModalities implements genai.Provider.

func (*Client) Ping 

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

Ping implements genai.ProviderPing by running `codex --version`.

func (*Client) Scoreboard 

func (c *Client) Scoreboard() scoreboard.Score

Scoreboard implements genai.Provider.

type ClientInfo added in v0.4.1 

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

ClientInfo identifies the client in the initialize handshake.

type CollabAgentState added in v0.5.6 

type CollabAgentState struct {
	Status  CollabAgentStatus `json:"status"`
	Message *string           `json:"message,omitzero"`
}

CollabAgentState describes the state of a collaborative agent.

type CollabAgentStatus added in v0.5.6 

type CollabAgentStatus string

CollabAgentStatus is a collaborative agent lifecycle status. 

const (
	// CollabAgentStatusPendingInit indicates the agent is pending initialization.
	CollabAgentStatusPendingInit CollabAgentStatus = "pendingInit"
	// CollabAgentStatusRunning indicates the agent is running.
	CollabAgentStatusRunning CollabAgentStatus = "running"
	// CollabAgentStatusInterrupted indicates the agent was interrupted.
	CollabAgentStatusInterrupted CollabAgentStatus = "interrupted"
	// CollabAgentStatusCompleted indicates the agent completed.
	CollabAgentStatusCompleted CollabAgentStatus = "completed"
	// CollabAgentStatusErrored indicates the agent errored.
	CollabAgentStatusErrored CollabAgentStatus = "errored"
	// CollabAgentStatusShutdown indicates the agent shut down.
	CollabAgentStatusShutdown CollabAgentStatus = "shutdown"
	// CollabAgentStatusNotFound indicates the agent was not found.
	CollabAgentStatusNotFound CollabAgentStatus = "notFound"
)

Collaborative agent status constants.

type CollabAgentTool added in v0.5.6 

type CollabAgentTool string

CollabAgentTool is a collaborative agent tool name. 

const (
	// CollabAgentToolSpawnAgent starts a collaborative agent.
	CollabAgentToolSpawnAgent CollabAgentTool = "spawnAgent"
	// CollabAgentToolSendInput sends input to a collaborative agent.
	CollabAgentToolSendInput CollabAgentTool = "sendInput"
	// CollabAgentToolResumeAgent resumes a collaborative agent.
	CollabAgentToolResumeAgent CollabAgentTool = "resumeAgent"
	// CollabAgentToolWait waits for a collaborative agent.
	CollabAgentToolWait CollabAgentTool = "wait"
	// CollabAgentToolCloseAgent closes a collaborative agent.
	CollabAgentToolCloseAgent CollabAgentTool = "closeAgent"
	// CollabAgentToolFollowupTask sends a follow-up task to a collaborative agent.
	CollabAgentToolFollowupTask CollabAgentTool = "followupTask"
	// CollabAgentToolInterruptAgent interrupts a collaborative agent.
	CollabAgentToolInterruptAgent CollabAgentTool = "interruptAgent"
	// CollabAgentToolListAgents lists collaborative agents.
	CollabAgentToolListAgents CollabAgentTool = "listAgents"
	// CollabAgentToolSendMessage sends a message to a collaborative agent.
	CollabAgentToolSendMessage CollabAgentTool = "sendMessage"
)

Collaborative agent tool constants.

type CollabAgentToolCallItem added in v0.4.1 

type CollabAgentToolCallItem struct {
	ID                string                      `json:"id"`
	Type              ItemType                    `json:"type"`
	Tool              CollabAgentTool             `json:"tool,omitzero"`
	Status            CollabAgentToolCallStatus   `json:"status,omitzero"`
	SenderThreadID    string                      `json:"senderThreadId,omitzero"`
	ReceiverThreadIDs []string                    `json:"receiverThreadIds,omitzero"`
	Prompt            string                      `json:"prompt,omitzero"`
	Model             string                      `json:"model,omitzero"`
	ReasoningEffort   ReasoningEffort             `json:"reasoningEffort,omitzero"`
	AgentsStates      map[string]CollabAgentState `json:"agentsStates,omitzero"`
}

CollabAgentToolCallItem is a collaborative multi-agent tool call item.

type CollabAgentToolCallStatus added in v0.5.6 

type CollabAgentToolCallStatus string

CollabAgentToolCallStatus is a collaborative agent tool call status. 

const (
	// CollabAgentToolCallStatusInProgress indicates the collaborative tool call is running.
	CollabAgentToolCallStatusInProgress CollabAgentToolCallStatus = "inProgress"
	// CollabAgentToolCallStatusCompleted indicates the collaborative tool call completed.
	CollabAgentToolCallStatusCompleted CollabAgentToolCallStatus = "completed"
	// CollabAgentToolCallStatusFailed indicates the collaborative tool call failed.
	CollabAgentToolCallStatusFailed CollabAgentToolCallStatus = "failed"
	// CollabAgentToolCallStatusInterrupted indicates the collaborative tool call was interrupted.
	CollabAgentToolCallStatusInterrupted CollabAgentToolCallStatus = "interrupted"
)

Collaborative agent tool call status constants.

type CollaborationMode added in v0.9.0 

type CollaborationMode struct {
	Mode     ModeKind              `json:"mode"`
	Settings CollaborationSettings `json:"settings"`
}

CollaborationMode holds the collaboration settings for a Codex session.

type CollaborationSettings added in v0.9.0 

type CollaborationSettings struct {
	Model                 string           `json:"model"`
	ReasoningEffort       *ReasoningEffort `json:"reasoning_effort"`
	DeveloperInstructions *string          `json:"developer_instructions"`
}

CollaborationSettings holds the model and instructions for a collaboration mode.

type CommandAction added in v0.6.0 

type CommandAction struct {
	Type    CommandActionType `json:"type"`
	Command string            `json:"command"`
	Name    string            `json:"name,omitzero"`
	Path    string            `json:"path,omitzero"`
	Query   string            `json:"query,omitzero"`
}

CommandAction describes one best-effort parsed shell command action.

type CommandActionType added in v0.6.0 

type CommandActionType string

CommandActionType identifies a parsed command action variant. 

const (
	CommandActionTypeRead      CommandActionType = "read"
	CommandActionTypeListFiles CommandActionType = "listFiles"
	CommandActionTypeSearch    CommandActionType = "search"
	CommandActionTypeUnknown   CommandActionType = "unknown"
)

Command action type constants.

type CommandExecutionItem added in v0.4.1 

type CommandExecutionItem struct {
	ID               string                 `json:"id"`
	Type             ItemType               `json:"type"`
	PluginID         string                 `json:"pluginId,omitzero"`
	ScriptPath       string                 `json:"scriptPath,omitzero"`
	Command          string                 `json:"command,omitzero"`
	Cwd              string                 `json:"cwd,omitzero"`
	ProcessID        string                 `json:"processId,omitzero"`
	Source           CommandExecutionSource `json:"source,omitzero"`
	Status           CommandExecutionStatus `json:"status,omitzero"`
	CommandActions   []CommandAction        `json:"commandActions,omitzero"`
	AggregatedOutput *string                `json:"aggregatedOutput,omitzero"`
	ExitCode         *int                   `json:"exitCode,omitzero"`
	Duration         *base.DurationMS       `json:"durationMs,omitzero"`
}

CommandExecutionItem is a shell command execution item. Source indicates the origin: "agent" (default), "userShell", "unifiedExecStartup", or "unifiedExecInteraction".

type CommandExecutionOutputDeltaNotification added in v0.4.1 

type CommandExecutionOutputDeltaNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	ItemID   string `json:"itemId"`
	Delta    string `json:"delta"`
}

CommandExecutionOutputDeltaNotification holds params for item/commandExecution/outputDelta.

type CommandExecutionSource added in v0.5.6 

type CommandExecutionSource string

CommandExecutionSource describes the source of a command execution item. 

const (
	// CommandExecutionSourceAgent indicates a command requested by the agent.
	CommandExecutionSourceAgent CommandExecutionSource = "agent"
	// CommandExecutionSourceUserShell indicates a command from the user's shell.
	CommandExecutionSourceUserShell CommandExecutionSource = "userShell"
	// CommandExecutionSourceUnifiedExecStartup indicates startup command output.
	CommandExecutionSourceUnifiedExecStartup CommandExecutionSource = "unifiedExecStartup"
	// CommandExecutionSourceUnifiedExecInteraction indicates interactive command output.
	CommandExecutionSourceUnifiedExecInteraction CommandExecutionSource = "unifiedExecInteraction"
)

Command execution source constants.

type CommandExecutionStatus added in v0.5.6 

type CommandExecutionStatus string

CommandExecutionStatus is a command execution lifecycle status. 

const (
	// CommandExecutionStatusInProgress indicates the command is still running.
	CommandExecutionStatusInProgress CommandExecutionStatus = "inProgress"
	// CommandExecutionStatusCompleted indicates the command completed.
	CommandExecutionStatusCompleted CommandExecutionStatus = "completed"
	// CommandExecutionStatusFailed indicates the command failed.
	CommandExecutionStatusFailed CommandExecutionStatus = "failed"
	// CommandExecutionStatusDeclined indicates the command was not approved.
	CommandExecutionStatusDeclined CommandExecutionStatus = "declined"
)

Command execution status constants.

type ConfigWarningNotification added in v0.5.6 

type ConfigWarningNotification struct {
	Summary string          `json:"summary"`
	Details *string         `json:"details,omitzero"`
	Path    *string         `json:"path,omitzero"`
	Range   json.RawMessage `json:"range,omitzero"`
}

ConfigWarningNotification holds params for configWarning.

type ConsumeAccountRateLimitResetCreditOutcome added in v0.7.0 

type ConsumeAccountRateLimitResetCreditOutcome string

ConsumeAccountRateLimitResetCreditOutcome is the result of consuming a rate-limit reset credit. 

const (
	ConsumeAccountRateLimitResetCreditOutcomeReset           ConsumeAccountRateLimitResetCreditOutcome = "reset"
	ConsumeAccountRateLimitResetCreditOutcomeNothingToReset  ConsumeAccountRateLimitResetCreditOutcome = "nothingToReset"
	ConsumeAccountRateLimitResetCreditOutcomeNoCredit        ConsumeAccountRateLimitResetCreditOutcome = "noCredit"
	ConsumeAccountRateLimitResetCreditOutcomeAlreadyRedeemed ConsumeAccountRateLimitResetCreditOutcome = "alreadyRedeemed"
)

Rate-limit reset credit outcome constants.

type ConsumeAccountRateLimitResetCreditParams added in v0.7.0 

type ConsumeAccountRateLimitResetCreditParams struct {
	IdempotencyKey string `json:"idempotencyKey"`
	CreditID       string `json:"creditId,omitzero"`
}

ConsumeAccountRateLimitResetCreditParams holds params for account/rateLimitResetCredit/consume.

type ConsumeAccountRateLimitResetCreditResponse added in v0.7.0 

type ConsumeAccountRateLimitResetCreditResponse struct {
	Outcome ConsumeAccountRateLimitResetCreditOutcome `json:"outcome"`
}

ConsumeAccountRateLimitResetCreditResponse is the response to account/rateLimitResetCredit/consume.

type ContextCompactedNotification added in v0.5.6 

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

ContextCompactedNotification holds the deprecated thread compaction event.

type ContextCompactionThreadItem added in v0.6.0 

type ContextCompactionThreadItem struct {
	ID   string   `json:"id"`
	Type ItemType `json:"type"`
}

ContextCompactionThreadItem signals a context window compaction.

type CreditsSnapshot added in v0.7.0 

type CreditsSnapshot struct {
	HasCredits bool   `json:"hasCredits"`
	Unlimited  bool   `json:"unlimited"`
	Balance    string `json:"balance,omitzero"`
}

CreditsSnapshot describes Codex account credit availability.

type CyberAccessProgram added in v0.9.0 

type CyberAccessProgram string

CyberAccessProgram identifies an explicit cyber access selection. 

const (
	CyberAccessProgramDaybreakBlue CyberAccessProgram = "daybreakBlue"
	CyberAccessProgramDaybreakRed  CyberAccessProgram = "daybreakRed"
	CyberAccessProgramStandard     CyberAccessProgram = "standard"
)

Cyber access programs.

type DeprecationNoticeNotification added in v0.5.6 

type DeprecationNoticeNotification struct {
	Summary string  `json:"summary"`
	Details *string `json:"details,omitzero"`
}

DeprecationNoticeNotification holds params for deprecationNotice.

type DesktopOnboardingEntrypoint added in v0.8.0 

type DesktopOnboardingEntrypoint string

DesktopOnboardingEntrypoint identifies a provider onboarding flow. 

const DesktopOnboardingEntrypointLifeSciences DesktopOnboardingEntrypoint = "life_sciences"

DesktopOnboardingEntrypointLifeSciences identifies life-sciences onboarding.

type DynamicToolCallItem added in v0.4.1 

type DynamicToolCallItem struct {
	ID           string                             `json:"id"`
	Type         ItemType                           `json:"type"`
	Namespace    string                             `json:"namespace,omitzero"`
	Tool         string                             `json:"tool,omitzero"`
	Arguments    json.RawMessage                    `json:"arguments,omitzero"`
	Status       DynamicToolCallStatus              `json:"status,omitzero"`
	ContentItems []DynamicToolCallOutputContentItem `json:"contentItems,omitzero"`
	Success      *bool                              `json:"success,omitzero"`
	Duration     base.DurationMS                    `json:"durationMs,omitzero"`
}

DynamicToolCallItem is a dynamically registered tool call item.

type DynamicToolCallOutputContentItem added in v0.6.0 

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

DynamicToolCallOutputContentItem is one dynamic tool output content item.

type DynamicToolCallOutputContentItemType added in v0.6.0 

type DynamicToolCallOutputContentItemType string

DynamicToolCallOutputContentItemType identifies a dynamic tool output content item. 

const (
	DynamicToolCallOutputContentItemTypeInputText  DynamicToolCallOutputContentItemType = "inputText"
	DynamicToolCallOutputContentItemTypeInputImage DynamicToolCallOutputContentItemType = "inputImage"
)

Dynamic tool output content item type constants.

type DynamicToolCallStatus added in v0.5.6 

type DynamicToolCallStatus string

DynamicToolCallStatus is a dynamic tool call lifecycle status. 

const (
	// DynamicToolCallStatusInProgress indicates the dynamic tool call is still running.
	DynamicToolCallStatusInProgress DynamicToolCallStatus = "inProgress"
	// DynamicToolCallStatusCompleted indicates the dynamic tool call completed.
	DynamicToolCallStatusCompleted DynamicToolCallStatus = "completed"
	// DynamicToolCallStatusFailed indicates the dynamic tool call failed.
	DynamicToolCallStatusFailed DynamicToolCallStatus = "failed"
)

Dynamic tool call status constants.

type DynamicToolNamespaceTool added in v0.8.0 

type DynamicToolNamespaceTool struct {
	Type         string          `json:"type"`
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	InputSchema  json.RawMessage `json:"inputSchema"`
	DeferLoading bool            `json:"deferLoading,omitzero"`
}

DynamicToolNamespaceTool is one function exposed by a dynamic tool namespace.

type DynamicToolSpec added in v0.6.0 

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

DynamicToolSpec describes a dynamically registered tool.

type EnteredReviewModeItem added in v0.4.1 

type EnteredReviewModeItem struct {
	ID     string   `json:"id"`
	Type   ItemType `json:"type"`
	Review string   `json:"review,omitzero"`
}

EnteredReviewModeItem signals the agent entered review mode.

type EnvironmentConnectionNotification added in v0.8.0 

type EnvironmentConnectionNotification struct {
	ThreadID      string `json:"threadId"`
	EnvironmentID string `json:"environmentId"`
}

EnvironmentConnectionNotification holds thread environment connection state.

type ErrorNotification added in v0.4.1 

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

ErrorNotification holds params for error notifications.

type ExitedReviewModeItem added in v0.4.1 

type ExitedReviewModeItem struct {
	ID     string   `json:"id"`
	Type   ItemType `json:"type"`
	Review string   `json:"review,omitzero"`
}

ExitedReviewModeItem signals the agent exited review mode.

type ExternalAgentConfigImportProgressNotification added in v0.8.0 

type ExternalAgentConfigImportProgressNotification struct {
	ImportID        string            `json:"importId"`
	ItemTypeResults []json.RawMessage `json:"itemTypeResults"`
}

ExternalAgentConfigImportProgressNotification holds import progress.

type FileChangeItem added in v0.4.1 

type FileChangeItem struct {
	ID      string             `json:"id"`
	Type    ItemType           `json:"type"`
	Changes []FileUpdateChange `json:"changes,omitzero"`
	Status  PatchApplyStatus   `json:"status,omitzero"`
}

FileChangeItem is a file creation/modification/deletion item.

type FileChangeOutputDeltaNotification added in v0.4.1 

type FileChangeOutputDeltaNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	ItemID   string `json:"itemId"`
	Delta    string `json:"delta"`
}

FileChangeOutputDeltaNotification holds deprecated apply-patch output.

type FileChangePatchUpdatedNotification added in v0.5.6 

type FileChangePatchUpdatedNotification struct {
	ThreadID string             `json:"threadId"`
	TurnID   string             `json:"turnId"`
	ItemID   string             `json:"itemId"`
	Changes  []FileUpdateChange `json:"changes"`
}

FileChangePatchUpdatedNotification holds params for item/fileChange/patchUpdated.

type FileUpdateChange added in v0.4.1 

type FileUpdateChange struct {
	Path string          `json:"path"`
	Kind PatchChangeKind `json:"kind"`
	Diff string          `json:"diff,omitzero"`
}

FileUpdateChange describes a single file change within a fileChange item.

type FunctionCallOutputItem added in v0.8.0 

type FunctionCallOutputItem struct {
	ID        string          `json:"id"`
	Type      ItemType        `json:"type"`
	Name      string          `json:"name"`
	Namespace string          `json:"namespace,omitzero"`
	Output    json.RawMessage `json:"output"`
}

FunctionCallOutputItem is a client-provided tool output in thread history.

type GatewayOAuthChangedNotification added in v0.10.2 

type GatewayOAuthChangedNotification struct {
	// AuthURL is an authorization handoff and must not be logged.
	AuthURL    string             `json:"authUrl,omitzero"`
	ProviderID string             `json:"providerId"`
	Status     GatewayOAuthStatus `json:"status"`
	Error      string             `json:"error,omitzero"`
}

GatewayOAuthChangedNotification holds params for account/gatewayOAuth/changed.

type GatewayOAuthStatus added in v0.10.2 

type GatewayOAuthStatus string

GatewayOAuthStatus describes provider gateway authentication readiness. 

const (
	GatewayOAuthStatusFailed    GatewayOAuthStatus = "failed"
	GatewayOAuthStatusNotReady  GatewayOAuthStatus = "notReady"
	GatewayOAuthStatusStarted   GatewayOAuthStatus = "started"
	GatewayOAuthStatusSucceeded GatewayOAuthStatus = "succeeded"
)

Gateway OAuth states.

type GetAccountRateLimitsResponse added in v0.7.0 

type GetAccountRateLimitsResponse struct {
	OrdinaryUsageAllowed  bool                          `json:"ordinaryUsageAllowed,omitzero"`
	RateLimits            RateLimitSnapshot             `json:"rateLimits"`
	RateLimitsByLimitID   map[string]RateLimitSnapshot  `json:"rateLimitsByLimitId,omitzero"`
	RateLimitResetCredits *RateLimitResetCreditsSummary `json:"rateLimitResetCredits,omitzero"`
	AccountID             string                        `json:"accountId,omitzero"`
	RateLimitUpsell       base.Unknown                  `json:"rateLimitUpsell,omitzero"`
}

GetAccountRateLimitsResponse is the response to account/rateLimits/read.

type GitInfo added in v0.6.0 

type GitInfo struct {
	SHA       *string `json:"sha,omitzero"`
	Branch    *string `json:"branch,omitzero"`
	OriginURL *string `json:"originUrl,omitzero"`
}

GitInfo is optional Git metadata captured for a thread.

type GuardianApprovalReview added in v0.6.0 

type GuardianApprovalReview struct {
	Status            GuardianApprovalReviewStatus `json:"status"`
	RiskLevel         *GuardianRiskLevel           `json:"riskLevel,omitzero"`
	UserAuthorization *GuardianUserAuthorization   `json:"userAuthorization,omitzero"`
	Rationale         *string                      `json:"rationale,omitzero"`
}

GuardianApprovalReview is the approval auto-review payload.

type GuardianApprovalReviewAction added in v0.6.0 

type GuardianApprovalReviewAction struct {
	Type          string                  `json:"type"`
	Source        GuardianCommandSource   `json:"source,omitzero"`
	Command       string                  `json:"command,omitzero"`
	Cwd           string                  `json:"cwd,omitzero"`
	Program       string                  `json:"program,omitzero"`
	Argv          []string                `json:"argv,omitzero"`
	Files         []string                `json:"files,omitzero"`
	Target        string                  `json:"target,omitzero"`
	Host          string                  `json:"host,omitzero"`
	Protocol      NetworkApprovalProtocol `json:"protocol,omitzero"`
	Port          *uint16                 `json:"port,omitzero"`
	Server        string                  `json:"server,omitzero"`
	ToolName      string                  `json:"toolName,omitzero"`
	ConnectorID   *string                 `json:"connectorId,omitzero"`
	ConnectorName *string                 `json:"connectorName,omitzero"`
	ToolTitle     *string                 `json:"toolTitle,omitzero"`
	Reason        *string                 `json:"reason,omitzero"`
	Permissions   json.RawMessage         `json:"permissions,omitzero"`
}

GuardianApprovalReviewAction is a flattened tagged union for guardian review actions.

type GuardianApprovalReviewStatus added in v0.6.0 

type GuardianApprovalReviewStatus string

GuardianApprovalReviewStatus is an approval auto-review lifecycle status. 

const (
	GuardianApprovalReviewStatusInProgress GuardianApprovalReviewStatus = "inProgress"
	GuardianApprovalReviewStatusApproved   GuardianApprovalReviewStatus = "approved"
	GuardianApprovalReviewStatusDenied     GuardianApprovalReviewStatus = "denied"
	GuardianApprovalReviewStatusTimedOut   GuardianApprovalReviewStatus = "timedOut"
	GuardianApprovalReviewStatusAborted    GuardianApprovalReviewStatus = "aborted"
)

Guardian approval review status constants.

type GuardianCommandSource added in v0.6.0 

type GuardianCommandSource string

GuardianCommandSource identifies the command source under guardian review. 

const (
	GuardianCommandSourceShell       GuardianCommandSource = "shell"
	GuardianCommandSourceUnifiedExec GuardianCommandSource = "unifiedExec"
)

Guardian command source constants.

type GuardianRiskLevel added in v0.6.0 

type GuardianRiskLevel string

GuardianRiskLevel is the risk level assigned by approval auto-review. 

const (
	GuardianRiskLevelLow      GuardianRiskLevel = "low"
	GuardianRiskLevelMedium   GuardianRiskLevel = "medium"
	GuardianRiskLevelHigh     GuardianRiskLevel = "high"
	GuardianRiskLevelCritical GuardianRiskLevel = "critical"
)

Guardian risk level constants.

type GuardianUserAuthorization added in v0.6.0 

type GuardianUserAuthorization string

GuardianUserAuthorization is the authorization level assigned by approval auto-review. 

const (
	GuardianUserAuthorizationUnknown GuardianUserAuthorization = "unknown"
	GuardianUserAuthorizationLow     GuardianUserAuthorization = "low"
	GuardianUserAuthorizationMedium  GuardianUserAuthorization = "medium"
	GuardianUserAuthorizationHigh    GuardianUserAuthorization = "high"
)

Guardian user authorization constants.

type GuardianWarningNotification added in v0.5.6 

type GuardianWarningNotification struct {
	ThreadID string `json:"threadId"`
	Message  string `json:"message"`
}

GuardianWarningNotification holds params for guardianWarning.

type HookPromptFragment added in v0.6.0 

type HookPromptFragment struct {
	Text      string `json:"text"`
	HookRunID string `json:"hookRunId"`
}

HookPromptFragment is one hook execution prompt fragment.

type HookPromptItem added in v0.4.1 

type HookPromptItem struct {
	ID        string               `json:"id"`
	Type      ItemType             `json:"type"`
	Fragments []HookPromptFragment `json:"fragments,omitzero"`
}

HookPromptItem is a hook execution prompt item.

type ImageDetail added in v0.5.6 

type ImageDetail string

ImageDetail controls how much image detail to send to the model. 

const (
	// ImageDetailAuto lets Codex choose image detail.
	ImageDetailAuto ImageDetail = "auto"
	// ImageDetailLow requests low-detail image processing.
	ImageDetailLow ImageDetail = "low"
	// ImageDetailHigh requests high-detail image processing.
	ImageDetailHigh ImageDetail = "high"
	// ImageDetailOriginal requests original image detail.
	ImageDetailOriginal ImageDetail = "original"
)

Image detail constants.

type ImageGenerationFailure added in v0.8.0 

type ImageGenerationFailure struct {
	Type     string     `json:"type"`
	LimitID  string     `json:"limitId"`
	ResetsAt base.TimeS `json:"resetsAt,omitzero"`
}

ImageGenerationFailure describes a failed image generation request.

type ImageGenerationItem added in v0.4.1 

type ImageGenerationItem struct {
	ID                    string                 `json:"id"`
	Type                  ItemType               `json:"type"`
	Status                string                 `json:"status,omitzero"`
	RevisedPrompt         string                 `json:"revisedPrompt,omitzero"`
	Result                string                 `json:"result,omitzero"`
	TransparentBackground bool                   `json:"transparentBackground,omitzero"`
	Failure               ImageGenerationFailure `json:"failure,omitzero"`
	SavedPath             string                 `json:"savedPath,omitzero"`
}

ImageGenerationItem is an image generation item.

type ImageViewItem added in v0.4.1 

type ImageViewItem struct {
	ID   string   `json:"id"`
	Type ItemType `json:"type"`
	Path string   `json:"path,omitzero"`
}

ImageViewItem is an image viewing item.

type InitializeParams added in v0.4.1 

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

InitializeParams holds the params for the initialize request.

type InputModality added in v0.5.6 

type InputModality string

InputModality is a model input modality. 

const (
	// InputModalityText indicates text input support.
	InputModalityText InputModality = "text"
	// InputModalityImage indicates image input support.
	InputModalityImage InputModality = "image"
	// InputModalityAudio indicates audio input support.
	InputModalityAudio InputModality = "audio"
)

Input modality constants.

type ItemCompletedNotification added in v0.5.6 

type ItemCompletedNotification struct {
	// Item is the raw upstream ThreadItem tagged union payload.
	Item json.RawMessage `json:"item"`
	// ThreadID is the thread containing the item.
	ThreadID string `json:"threadId"`
	// TurnID is the turn containing the item.
	TurnID string `json:"turnId"`
	// CompletedAt is the Unix timestamp in milliseconds when the item completed.
	CompletedAt base.TimeMS `json:"completedAtMs"`
}

ItemCompletedNotification holds params for item/completed notifications.

type ItemGuardianApprovalReviewCompletedNotification added in v0.5.6 

type ItemGuardianApprovalReviewCompletedNotification struct {
	ThreadID       string                       `json:"threadId"`
	TurnID         string                       `json:"turnId"`
	StartedAt      base.TimeMS                  `json:"startedAtMs"`
	CompletedAt    base.TimeMS                  `json:"completedAtMs"`
	ReviewID       string                       `json:"reviewId"`
	TargetItemID   *string                      `json:"targetItemId,omitzero"`
	DecisionSource AutoReviewDecisionSource     `json:"decisionSource"`
	Review         GuardianApprovalReview       `json:"review"`
	Action         GuardianApprovalReviewAction `json:"action"`
}

ItemGuardianApprovalReviewCompletedNotification holds params for item/autoApprovalReview/completed.

type ItemGuardianApprovalReviewStartedNotification added in v0.5.6 

type ItemGuardianApprovalReviewStartedNotification struct {
	ThreadID     string                       `json:"threadId"`
	TurnID       string                       `json:"turnId"`
	StartedAt    base.TimeMS                  `json:"startedAtMs"`
	ReviewID     string                       `json:"reviewId"`
	TargetItemID *string                      `json:"targetItemId,omitzero"`
	Review       GuardianApprovalReview       `json:"review"`
	Action       GuardianApprovalReviewAction `json:"action"`
}

ItemGuardianApprovalReviewStartedNotification holds params for item/autoApprovalReview/started.

type ItemHeader added in v0.4.1 

type ItemHeader struct {
	ID   string   `json:"id"`
	Type ItemType `json:"type"`
}

ItemHeader extracts the discriminant fields from a raw item for dispatch.

type ItemStartedNotification added in v0.5.6 

type ItemStartedNotification struct {
	// Item is the raw upstream ThreadItem tagged union payload.
	Item json.RawMessage `json:"item"`
	// ThreadID is the thread containing the item.
	ThreadID string `json:"threadId"`
	// TurnID is the turn containing the item.
	TurnID string `json:"turnId"`
	// StartedAt is the Unix timestamp in milliseconds when the item started.
	StartedAt base.TimeMS `json:"startedAtMs"`
}

ItemStartedNotification holds params for item/started notifications.

type ItemType added in v0.4.1 

type ItemType string

ItemType is the item type discriminator for codex app-server items (camelCase). 

const (
	// ItemTypeUserMessage identifies user-submitted message items.
	ItemTypeUserMessage ItemType = "userMessage"
	// ItemTypeAgentMessage identifies assistant text message items.
	ItemTypeAgentMessage ItemType = "agentMessage"
	// ItemTypeFunctionCallOutput identifies client-provided tool output items.
	ItemTypeFunctionCallOutput ItemType = "functionCallOutput"
	// ItemTypePlan identifies plan items.
	ItemTypePlan ItemType = "plan"
	// ItemTypeReasoning identifies reasoning items.
	ItemTypeReasoning ItemType = "reasoning"
	// ItemTypeCommandExecution identifies shell command execution items.
	ItemTypeCommandExecution ItemType = "commandExecution"
	// ItemTypeFileChange identifies file change items.
	ItemTypeFileChange ItemType = "fileChange"
	// ItemTypeMCPToolCall identifies MCP tool call items.
	ItemTypeMCPToolCall ItemType = "mcpToolCall"
	// ItemTypeWebSearch identifies web search items.
	ItemTypeWebSearch ItemType = "webSearch"
	// ItemTypeImageView identifies image view items.
	ItemTypeImageView ItemType = "imageView"
	// ItemTypeImageGeneration identifies image generation items.
	ItemTypeImageGeneration ItemType = "imageGeneration"
	// ItemTypeContextCompaction identifies context compaction items.
	ItemTypeContextCompaction ItemType = "contextCompaction"
	// ItemTypeDynamicToolCall identifies dynamic tool call items.
	ItemTypeDynamicToolCall ItemType = "dynamicToolCall"
	// ItemTypeCollabAgentToolCall identifies collaborative agent tool call items.
	ItemTypeCollabAgentToolCall ItemType = "collabAgentToolCall"
	// ItemTypeSubAgentActivity identifies a sub-agent lifecycle activity item.
	ItemTypeSubAgentActivity ItemType = "subAgentActivity"
	// ItemTypeHookPrompt identifies hook prompt items.
	ItemTypeHookPrompt ItemType = "hookPrompt"
	// ItemTypeSleep identifies an interruptible sleep item.
	ItemTypeSleep ItemType = "sleep"
	// ItemTypeEnteredReviewMode identifies review-mode entry items.
	ItemTypeEnteredReviewMode ItemType = "enteredReviewMode"
	// ItemTypeExitedReviewMode identifies review-mode exit items.
	ItemTypeExitedReviewMode ItemType = "exitedReviewMode"
)

Item type constants (camelCase as emitted by Codex v2).

type JSONRPCError added in v0.4.1 

type JSONRPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

JSONRPCError is a JSON-RPC 2.0 error object.

type JSONRPCMessage added in v0.4.1 

type JSONRPCMessage struct {
	JSONRPC   string          `json:"jsonrpc"`
	EmittedAt base.TimeMS     `json:"emittedAtMs,omitzero"`
	Method    Method          `json:"method,omitzero"`
	ID        json.RawMessage `json:"id,omitzero"`
	Params    json.RawMessage `json:"params,omitzero"`
	Result    json.RawMessage `json:"result,omitzero"`
	Error     *JSONRPCError   `json:"error,omitzero"`
}

JSONRPCMessage is the JSON-RPC 2.0 envelope for codex app-server messages. Notifications have Method set, responses have an ID, and server requests have both.

func (*JSONRPCMessage) IsResponse added in v0.4.1 

func (m *JSONRPCMessage) IsResponse() bool

IsResponse reports whether the message is a response to a client request.

func (*JSONRPCMessage) IsServerRequest added in v0.8.0 

func (m *JSONRPCMessage) IsServerRequest() bool

IsServerRequest reports whether the server expects a response from the client.

type JSONRPCNotification added in v0.4.1 

type JSONRPCNotification struct {
	JSONRPC string `json:"jsonrpc"`
	Method  string `json:"method"`
}

JSONRPCNotification is a JSON-RPC 2.0 notification (no id, no response expected).

type JSONRPCRequest added in v0.4.1 

type JSONRPCRequest struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int64           `json:"id,omitzero"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitzero"`
}

JSONRPCRequest is the envelope for all JSON-RPC 2.0 requests sent to codex.

type McpAppDisplayMode added in v0.10.2 

type McpAppDisplayMode string

McpAppDisplayMode is the model-selected presentation for an MCP app UI resource. 

const (
	McpAppDisplayModeFullscreen McpAppDisplayMode = "fullscreen"
	McpAppDisplayModeInline     McpAppDisplayMode = "inline"
)

MCP app display modes.

type McpAppUi added in v0.10.2 

type McpAppUi struct {
	ResourceURI               string            `json:"resourceUri"`
	PreferredModelDisplayMode McpAppDisplayMode `json:"preferredModelDisplayMode"`
}

McpAppUi captures the tool descriptor's UI resource and preferred presentation.

type McpServerEventStreamNotification added in v0.8.0 

type McpServerEventStreamNotification struct {
	SubscriptionID string          `json:"subscriptionId"`
	Notification   json.RawMessage `json:"notification"`
}

McpServerEventStreamNotification holds an MCP event-stream update.

type McpServerOauthLoginCompletedNotification added in v0.5.6 

type McpServerOauthLoginCompletedNotification struct {
	LoginID  string `json:"loginId,omitzero"`
	ThreadID string `json:"threadId,omitzero"`
	Name     string `json:"name"`
	Success  bool   `json:"success"`
	Error    string `json:"error,omitzero"`
}

McpServerOauthLoginCompletedNotification holds params for mcpServer/oauthLogin/completed.

type McpServerStartupState added in v0.5.6 

type McpServerStartupState string

McpServerStartupState is an MCP server startup lifecycle state. 

const (
	// McpServerStartupStateStarting indicates the MCP server is starting.
	McpServerStartupStateStarting McpServerStartupState = "starting"
	// McpServerStartupStateReady indicates the MCP server is ready.
	McpServerStartupStateReady McpServerStartupState = "ready"
	// McpServerStartupStateFailed indicates MCP server startup failed.
	McpServerStartupStateFailed McpServerStartupState = "failed"
	// McpServerStartupStateCancelled indicates MCP server startup was cancelled.
	McpServerStartupStateCancelled McpServerStartupState = "cancelled"
)

MCP server startup state constants.

type McpServerStatusUpdatedNotification added in v0.5.6 

type McpServerStatusUpdatedNotification struct {
	ThreadID      string                `json:"threadId"`
	Name          string                `json:"name"`
	Status        McpServerStartupState `json:"status"`
	Error         string                `json:"error,omitzero"`
	FailureReason string                `json:"failureReason,omitzero"`
}

McpServerStatusUpdatedNotification holds params for mcpServer/startupStatus/updated.

type McpToolCallAppContext added in v0.7.3 

type McpToolCallAppContext struct {
	ConnectorID string `json:"connectorId,omitzero"`
	LinkID      string `json:"linkId,omitzero"`
	ResourceURI string `json:"resourceUri,omitzero"`
	AppName     string `json:"appName,omitzero"`
	ActionName  string `json:"actionName,omitzero"`
}

McpToolCallAppContext identifies the installed app context for an MCP tool call.

type McpToolCallError added in v0.4.1 

type McpToolCallError struct {
	Message string `json:"message"`
}

McpToolCallError holds the error from a failed MCP tool call.

type McpToolCallItem added in v0.4.1 

type McpToolCallItem struct {
	ID                string                `json:"id"`
	Type              ItemType              `json:"type"`
	Server            string                `json:"server,omitzero"`
	Tool              string                `json:"tool,omitzero"`
	Status            McpToolCallStatus     `json:"status,omitzero"`
	Arguments         json.RawMessage       `json:"arguments,omitzero"`
	AppContext        McpToolCallAppContext `json:"appContext,omitzero"`
	McpAppResourceURI string                `json:"mcpAppResourceUri,omitzero"`
	McpAppUI          *McpAppUi             `json:"mcpAppUi,omitzero"`
	PluginID          string                `json:"pluginId,omitzero"`
	ReadOnlyHint      bool                  `json:"readOnlyHint,omitzero"`
	Result            *McpToolCallResult    `json:"result,omitzero"`
	Error             *McpToolCallError     `json:"error,omitzero"`
	Duration          base.DurationMS       `json:"durationMs,omitzero"`
}

McpToolCallItem is an MCP tool call item.

type McpToolCallProgressNotification added in v0.4.1 

type McpToolCallProgressNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	ItemID   string `json:"itemId"`
	Message  string `json:"message"`
}

McpToolCallProgressNotification holds params for item/mcpToolCall/progress.

type McpToolCallResult added in v0.4.1 

type McpToolCallResult struct {
	Content           []json.RawMessage `json:"content"`
	StructuredContent json.RawMessage   `json:"structuredContent,omitzero"`
	Meta              json.RawMessage   `json:"_meta,omitzero"`
}

McpToolCallResult holds the result of a successful MCP tool call.

type McpToolCallStatus added in v0.5.6 

type McpToolCallStatus string

McpToolCallStatus is an MCP tool call lifecycle status. 

const (
	// McpToolCallStatusInProgress indicates the MCP tool call is still running.
	McpToolCallStatusInProgress McpToolCallStatus = "inProgress"
	// McpToolCallStatusCompleted indicates the MCP tool call completed.
	McpToolCallStatusCompleted McpToolCallStatus = "completed"
	// McpToolCallStatusFailed indicates the MCP tool call failed.
	McpToolCallStatusFailed McpToolCallStatus = "failed"
)

MCP tool call status constants.

type MemoryCitation added in v0.6.0 

type MemoryCitation struct {
	Entries   []MemoryCitationEntry `json:"entries"`
	ThreadIDs []string              `json:"threadIds"`
}

MemoryCitation describes memory citations attached to an agent message.

type MemoryCitationEntry added in v0.6.0 

type MemoryCitationEntry struct {
	Path      string `json:"path"`
	LineStart uint32 `json:"lineStart"`
	LineEnd   uint32 `json:"lineEnd"`
	Note      string `json:"note"`
}

MemoryCitationEntry describes one memory citation span.

type MessagePhase added in v0.5.6 

type MessagePhase string

MessagePhase classifies an assistant message. 

const (
	// MessagePhaseCommentary identifies non-final assistant commentary.
	MessagePhaseCommentary MessagePhase = "commentary"
	// MessagePhaseFinalAnswer identifies final assistant answer text.
	MessagePhaseFinalAnswer MessagePhase = "final_answer"
)

Message phase constants.

type MessageProbe added in v0.4.1 

type MessageProbe struct {
	Type   string           `json:"type,omitzero"`
	Method Method           `json:"method,omitzero"`
	ID     *json.RawMessage `json:"id,omitzero"`
}

MessageProbe extracts routing fields from a codex app-server line to distinguish injected JSON (has "type") from JSON-RPC (has "method"/"id").

type Method added in v0.4.1 

type Method string

Method is a JSON-RPC notification method string for the codex app-server protocol. 

const (
	// MethodThreadStarted reports that a thread was created.
	MethodThreadStarted Method = "thread/started"
	// MethodThreadArchived reports that a thread was archived.
	MethodThreadArchived Method = "thread/archived"
	// MethodThreadDeleted reports that a thread was deleted.
	MethodThreadDeleted Method = "thread/deleted"
	// MethodThreadUnarchived reports that a thread was unarchived.
	MethodThreadUnarchived Method = "thread/unarchived"
	// MethodThreadClosed reports that a thread was closed.
	MethodThreadClosed Method = "thread/closed"
	// MethodThreadReverted reports that a thread rollback completed.
	MethodThreadReverted Method = "thread/reverted"
	// MethodTurnStarted reports that a turn started.
	MethodTurnStarted Method = "turn/started"
	// MethodTurnCompleted reports that a turn completed.
	MethodTurnCompleted Method = "turn/completed"
	// MethodItemStarted reports that an item started.
	MethodItemStarted Method = "item/started"
	// MethodItemCompleted reports that an item completed.
	MethodItemCompleted Method = "item/completed"
	// MethodItemDelta streams text deltas for an agent message item.
	MethodItemDelta Method = "item/agentMessage/delta"
	// MethodRawItemCompleted reports an internal raw response item.
	MethodRawItemCompleted Method = "rawResponseItem/completed"
	// MethodRawResponseCompleted reports an internal completed response.
	MethodRawResponseCompleted Method = "rawResponse/completed"
	// MethodTokenUsageUpdated reports updated thread token usage.
	MethodTokenUsageUpdated Method = "thread/tokenUsage/updated"

	// MethodItemGuardianApprovalReviewStarted reports the start of an approval auto-review.
	MethodItemGuardianApprovalReviewStarted Method = "item/autoApprovalReview/started"
	// MethodItemGuardianApprovalReviewCompleted reports the completion of an approval auto-review.
	MethodItemGuardianApprovalReviewCompleted Method = "item/autoApprovalReview/completed"
	// MethodStrictReviewRequired reports that an auto-approval needs strict review.
	MethodStrictReviewRequired Method = "autoApprovalReview/strictReviewRequired"
	// MethodCommandExecOutputDelta streams output from a command/exec session.
	MethodCommandExecOutputDelta Method = "command/exec/outputDelta"
	// MethodProcessOutputDelta streams output from a spawned process.
	MethodProcessOutputDelta Method = "process/outputDelta"
	// MethodProcessExited reports that a spawned process exited.
	MethodProcessExited Method = "process/exited"
	// MethodCommandOutputDelta streams output for a command execution item.
	MethodCommandOutputDelta Method = "item/commandExecution/outputDelta"
	// MethodCommandTerminalInteract reports terminal input for a command execution item.
	MethodCommandTerminalInteract Method = "item/commandExecution/terminalInteraction"
	// MethodFileChangePatchUpdated reports an updated file change patch.
	MethodFileChangePatchUpdated Method = "item/fileChange/patchUpdated"
	// MethodFileChangeOutputDelta streams legacy file-change output.
	MethodFileChangeOutputDelta Method = "item/fileChange/outputDelta"
	// MethodReasoningSummaryTextDelta streams reasoning summary text.
	MethodReasoningSummaryTextDelta Method = "item/reasoning/summaryTextDelta"
	// MethodReasoningSummaryPartAdded reports a new reasoning summary part.
	MethodReasoningSummaryPartAdded Method = "item/reasoning/summaryPartAdded"
	// MethodReasoningTextDelta streams full reasoning text.
	MethodReasoningTextDelta Method = "item/reasoning/textDelta"
	// MethodPlanDelta streams text for a plan item.
	MethodPlanDelta Method = "item/plan/delta"
	// MethodMcpToolCallProgress reports progress for an MCP tool call item.
	MethodMcpToolCallProgress Method = "item/mcpToolCall/progress"
	// MethodTurnDiffUpdated reports the current turn diff.
	MethodTurnDiffUpdated Method = "turn/diff/updated"
	// MethodTurnPlanUpdated reports the current turn plan.
	MethodTurnPlanUpdated Method = "turn/plan/updated"
	// MethodThreadStatusChanged reports a thread status transition.
	MethodThreadStatusChanged Method = "thread/status/changed"
	// MethodThreadSettingsUpdated reports updated thread settings.
	MethodThreadSettingsUpdated Method = "thread/settings/updated"
	// MethodThreadNameUpdated reports an updated thread name.
	MethodThreadNameUpdated Method = "thread/name/updated"
	// MethodThreadAttachmentUpdated reports creation or deletion of a thread attachment.
	MethodThreadAttachmentUpdated Method = "thread/attachment/updated"
	// MethodThreadPredictionUpdated reports the result of a thread prediction.
	MethodThreadPredictionUpdated Method = "thread/prediction/updated"
	// MethodThreadGoalUpdated reports an updated thread goal.
	MethodThreadGoalUpdated Method = "thread/goal/updated"
	// MethodThreadGoalCleared reports that the thread goal was cleared.
	MethodThreadGoalCleared Method = "thread/goal/cleared"
	// MethodThreadQueueChanged reports a thread queue update.
	MethodThreadQueueChanged Method = "thread/queue/changed"
	// MethodProjectChanged reports a project update.
	MethodProjectChanged Method = "project/changed"
	// MethodThreadProjectUpdated reports a thread project assignment update.
	MethodThreadProjectUpdated Method = "thread/project/updated"
	// MethodEnvironmentConnected reports a thread environment connection.
	MethodEnvironmentConnected Method = "thread/environment/connected"
	// MethodEnvironmentDisconnected reports a thread environment disconnection.
	MethodEnvironmentDisconnected Method = "thread/environment/disconnected"
	// MethodThreadCompacted reports legacy context compaction.
	MethodThreadCompacted Method = "thread/compacted"
	// MethodModelRerouted reports that Codex changed the model for a turn.
	MethodModelRerouted Method = "model/rerouted"
	// MethodModelVerification reports model verification requirements.
	MethodModelVerification Method = "model/verification"
	// MethodAuthRecoveryStarted reports the start of provider authentication recovery.
	MethodAuthRecoveryStarted Method = "modelProvider/authRecoveryStarted"
	// MethodAuthRecoveryCompleted reports completion of provider authentication recovery.
	MethodAuthRecoveryCompleted Method = "modelProvider/authRecoveryCompleted"
	// MethodModelSafetyBufferingUpdated reports model safety-buffering state.
	MethodModelSafetyBufferingUpdated Method = "model/safetyBuffering/updated"
	// MethodTurnModerationMetadata reports moderation metadata for a turn.
	MethodTurnModerationMetadata Method = "turn/moderationMetadata"
	// MethodWarning reports a non-fatal warning.
	MethodWarning Method = "warning"
	// MethodGuardianWarning reports a guardian warning.
	MethodGuardianWarning Method = "guardianWarning"
	// MethodErrorNotification reports an app-server error notification.
	MethodErrorNotification Method = "error"

	// MethodHookStarted — Hook lifecycle notifications.
	// MethodHookStarted reports that a hook started.
	MethodHookStarted Method = "hook/started"
	// MethodHookCompleted reports that a hook completed.
	MethodHookCompleted Method = "hook/completed"

	// MethodCommandRequestApproval — Server-to-client approval requests (requires permission mode).
	// MethodCommandRequestApproval requests approval for command execution.
	MethodCommandRequestApproval Method = "item/commandExecution/requestApproval"
	// MethodFileChangeRequestApproval requests approval for a file change.
	MethodFileChangeRequestApproval Method = "item/fileChange/requestApproval"
	// MethodPermissionsRequestApproval requests approval for additional permissions.
	MethodPermissionsRequestApproval Method = "item/permissions/requestApproval"
	// MethodDynamicToolCallRequest requests execution of a client-side dynamic tool.
	MethodDynamicToolCallRequest Method = "item/tool/call"
	// MethodToolRequestUserInput requests user input for a tool call.
	MethodToolRequestUserInput Method = "item/tool/requestUserInput"
	// MethodMcpElicitationRequest requests input for an MCP elicitation.
	MethodMcpElicitationRequest Method = "mcpServer/elicitation/request"
	// MethodServerRequestResolved reports that a server request was resolved.
	MethodServerRequestResolved Method = "serverRequest/resolved"
	// MethodChatgptAuthTokensRefresh requests refreshed ChatGPT auth tokens.
	MethodChatgptAuthTokensRefresh Method = "account/chatgptAuthTokens/refresh"
	// MethodAttestationGenerate requests an attestation result.
	MethodAttestationGenerate Method = "attestation/generate"
	// MethodCurrentTimeRead requests the current time from the client.
	MethodCurrentTimeRead Method = "currentTime/read"
	// MethodApplyPatchApproval is the legacy patch approval request.
	MethodApplyPatchApproval Method = "applyPatchApproval"
	// MethodExecCommandApproval is the legacy command approval request.
	MethodExecCommandApproval Method = "execCommandApproval"

	// MethodAccountUpdated — Account and configuration notifications.
	// MethodAccountUpdated reports updated account data.
	MethodAccountUpdated Method = "account/updated"
	// MethodGatewayOAuthChanged reports provider gateway authentication status.
	MethodGatewayOAuthChanged Method = "account/gatewayOAuth/changed"
	// MethodAccountRateLimitsUpdated reports updated account rate limits.
	MethodAccountRateLimitsUpdated Method = "account/rateLimits/updated"
	// MethodAccountLoginCompleted reports completion of account login.
	MethodAccountLoginCompleted Method = "account/login/completed"
	// MethodAppListUpdated reports an updated MCP app list.
	MethodAppListUpdated Method = "app/list/updated"
	// MethodRemoteControlStatusChanged reports a remote-control status change.
	MethodRemoteControlStatusChanged Method = "remoteControl/status/changed"
	// MethodExternalAgentConfigImportCompleted reports completion of external agent config import.
	MethodExternalAgentConfigImportCompleted Method = "externalAgentConfig/import/completed"
	// MethodExternalAgentConfigImportProgress reports external agent config import progress.
	MethodExternalAgentConfigImportProgress Method = "externalAgentConfig/import/progress"
	// MethodFsChanged reports watched filesystem changes.
	MethodFsChanged Method = "fs/changed"
	// MethodConfigWarning reports a configuration warning.
	MethodConfigWarning Method = "configWarning"
	// MethodDeprecationNotice reports a deprecation notice.
	MethodDeprecationNotice Method = "deprecationNotice"
	// MethodSkillsChanged reports that skills changed.
	MethodSkillsChanged Method = "skills/changed"
	// MethodMcpOauthLoginCompleted reports completion of MCP OAuth login.
	MethodMcpOauthLoginCompleted Method = "mcpServer/oauthLogin/completed"
	// MethodMcpServerStatusUpdated reports an MCP server startup status update.
	MethodMcpServerStatusUpdated Method = "mcpServer/startupStatus/updated"
	// MethodMcpServerEventStream reports an MCP server event-stream notification.
	MethodMcpServerEventStream Method = "mcpServer/event/stream/notification"

	// MethodFuzzyFileSearchSessionUpdated — Search and realtime notifications.
	// MethodFuzzyFileSearchSessionUpdated reports updated fuzzy file search results.
	MethodFuzzyFileSearchSessionUpdated Method = "fuzzyFileSearch/sessionUpdated"
	// MethodFuzzyFileSearchSessionCompleted reports completion of a fuzzy file search session.
	MethodFuzzyFileSearchSessionCompleted Method = "fuzzyFileSearch/sessionCompleted"
	// MethodThreadRealtimeStarted reports start of a realtime thread session.
	MethodThreadRealtimeStarted Method = "thread/realtime/started"
	// MethodThreadRealtimeItemAdded reports a new realtime item.
	MethodThreadRealtimeItemAdded Method = "thread/realtime/itemAdded"
	// MethodThreadRealtimeItemStarted reports a realtime item start.
	MethodThreadRealtimeItemStarted Method = "thread/realtime/item/started"
	// MethodThreadRealtimeItemTranscriptDelta streams a realtime item transcript.
	MethodThreadRealtimeItemTranscriptDelta Method = "thread/realtime/item/transcript/delta"
	// MethodThreadRealtimeItemCompleted reports a realtime item completion.
	MethodThreadRealtimeItemCompleted Method = "thread/realtime/item/completed"
	// MethodThreadRealtimeTranscriptDelta streams realtime transcript text.
	MethodThreadRealtimeTranscriptDelta Method = "thread/realtime/transcript/delta"
	// MethodThreadRealtimeTranscriptDone reports completion of realtime transcript text.
	MethodThreadRealtimeTranscriptDone Method = "thread/realtime/transcript/done"
	// MethodThreadRealtimeOutputAudioDelta streams realtime output audio.
	MethodThreadRealtimeOutputAudioDelta Method = "thread/realtime/outputAudio/delta"
	// MethodThreadRealtimeSdp carries realtime SDP negotiation data.
	MethodThreadRealtimeSdp Method = "thread/realtime/sdp"
	// MethodThreadRealtimeError reports a realtime session error.
	MethodThreadRealtimeError Method = "thread/realtime/error"
	// MethodThreadRealtimeClosed reports that a realtime session closed.
	MethodThreadRealtimeClosed Method = "thread/realtime/closed"
	// MethodWindowsWorldWritableWarning reports unsafe world-writable Windows paths.
	MethodWindowsWorldWritableWarning Method = "windows/worldWritableWarning"
	// MethodWindowsSandboxSetupCompleted reports completion of Windows sandbox setup.
	MethodWindowsSandboxSetupCompleted Method = "windowsSandbox/setupCompleted"
)

JSON-RPC notification method constants for codex app-server.

type MethodProbe added in v0.4.1 

type MethodProbe struct {
	Method Method `json:"method,omitzero"`
}

MethodProbe extracts the method field from a JSON-RPC message.

type MisalignmentErrorDetails added in v0.8.0 

type MisalignmentErrorDetails struct {
	ErrorType           string            `json:"errorType,omitzero"`
	DetailedExplanation string            `json:"detailedExplanation,omitzero"`
	Steer               MisalignmentSteer `json:"steer,omitzero"`
	// ReviewTarget is an opaque block target echoed only on explicit continuation.
	ReviewTarget string `json:"reviewTarget,omitzero"`
}

MisalignmentErrorDetails describes a model-response alignment block.

type MisalignmentSteer added in v0.8.0 

type MisalignmentSteer struct {
	Message string `json:"message"`
}

MisalignmentSteer is the suggested follow-up instruction for an alignment block.

type ModeKind added in v0.9.0 

type ModeKind string

ModeKind identifies a collaboration mode. 

const (
	ModeKindDefault ModeKind = "default"
	ModeKindPlan    ModeKind = "plan"
)

Collaboration modes.

type ModelAccessPrograms added in v0.9.0 

type ModelAccessPrograms struct {
	Cyber []CyberAccessProgram `json:"cyber"`
}

ModelAccessPrograms lists caller-specific explicit access programs from model discovery.

type ModelAvailabilityNux added in v0.7.0 

type ModelAvailabilityNux struct {
	Message string `json:"message,omitzero"`
}

ModelAvailabilityNux holds a new-user-experience announcement for a model.

type ModelInfo added in v0.4.1 

type ModelInfo struct {
	ID                        string               `json:"id"`
	DisplayName               string               `json:"displayName,omitzero"`
	Model                     string               `json:"model,omitzero"`
	Description               string               `json:"description,omitzero"`
	DefaultReasoningEffort    ReasoningEffort      `json:"defaultReasoningEffort,omitzero"`
	Hidden                    bool                 `json:"hidden,omitzero"`
	IsDefault                 bool                 `json:"isDefault,omitzero"`
	SupportsPersonality       bool                 `json:"supportsPersonality,omitzero"`
	Upgrade                   string               `json:"upgrade,omitzero"`
	UpgradeInfo               ModelUpgradeInfo     `json:"upgradeInfo,omitzero"`
	AvailabilityNux           ModelAvailabilityNux `json:"availabilityNux,omitzero"`
	SupportedReasoningEfforts []ModelReasoningOpt  `json:"supportedReasoningEfforts,omitzero"`
	InputModalities           []InputModality      `json:"inputModalities,omitzero"`
	AdditionalSpeedTiers      []string             `json:"additionalSpeedTiers,omitzero"`
	ServiceTiers              []ModelServiceTier   `json:"serviceTiers,omitzero"`
	DefaultServiceTier        string               `json:"defaultServiceTier,omitzero"`
	ModelSpecialty            ModelSpecialty       `json:"modelSpecialty,omitzero"`
	MultiAgentVersion         MultiAgentVersion    `json:"multiAgentVersion,omitzero"`
	AvailableAccessPrograms   *ModelAccessPrograms `json:"availableAccessPrograms,omitzero"`
}

ModelInfo describes a single model in a model/list result.

type ModelListParams added in v0.8.0 

type ModelListParams struct {
	Cursor        string `json:"cursor,omitzero"`
	Limit         int    `json:"limit,omitzero"`
	IncludeHidden bool   `json:"includeHidden,omitzero"`
}

ModelListParams holds pagination options for model/list.

type ModelListResponse added in v0.8.0 

type ModelListResponse struct {
	Data       []ModelInfo `json:"data"`
	NextCursor string      `json:"nextCursor,omitzero"`
}

ModelListResponse is the result of a model/list request.

type ModelReasoningOpt added in v0.4.1 

type ModelReasoningOpt struct {
	ReasoningEffort ReasoningEffort `json:"reasoningEffort"`
	Description     string          `json:"description,omitzero"`
}

ModelReasoningOpt describes a supported reasoning effort level.

type ModelRerouteReason added in v0.5.6 

type ModelRerouteReason string

ModelRerouteReason explains why a model was rerouted. 

const (
	// ModelRerouteReasonHighRiskCyberActivity indicates rerouting due to high-risk cyber activity.
	ModelRerouteReasonHighRiskCyberActivity ModelRerouteReason = "highRiskCyberActivity"
)

Model reroute reason constants.

type ModelReroutedNotification added in v0.4.1 

type ModelReroutedNotification struct {
	ThreadID  string             `json:"threadId"`
	TurnID    string             `json:"turnId"`
	FromModel string             `json:"fromModel"`
	ToModel   string             `json:"toModel"`
	Reason    ModelRerouteReason `json:"reason,omitzero"`
}

ModelReroutedNotification holds params for model/rerouted.

type ModelSafetyBufferingUpdatedNotification added in v0.8.0 

type ModelSafetyBufferingUpdatedNotification struct {
	ThreadID        string   `json:"threadId"`
	TurnID          string   `json:"turnId"`
	Model           string   `json:"model"`
	UseCases        []string `json:"useCases"`
	Reasons         []string `json:"reasons"`
	ShowBufferingUI bool     `json:"showBufferingUi"`
	FasterModel     string   `json:"fasterModel,omitzero"`
}

ModelSafetyBufferingUpdatedNotification holds model safety-buffering state.

type ModelServiceTier added in v0.5.6 

type ModelServiceTier struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

ModelServiceTier describes an available model service tier.

type ModelSpecialty added in v0.7.6 

type ModelSpecialty string

ModelSpecialty identifies a model optimized for a specialized workload. 

const (
	ModelSpecialtyCyber ModelSpecialty = "cyber"
)

Model specialty values.

type ModelUpgradeInfo added in v0.4.1 

type ModelUpgradeInfo struct {
	MigrationMarkdown string     `json:"migrationMarkdown,omitzero"`
	Model             string     `json:"model,omitzero"`
	ModelLink         string     `json:"modelLink,omitzero"`
	UpgradeCopy       string     `json:"upgradeCopy,omitzero"`
	RetirementAt      base.TimeS `json:"retirementAt,omitzero"`
}

ModelUpgradeInfo holds upgrade migration information for a model.

type ModelVerification added in v0.5.6 

type ModelVerification string

ModelVerification describes a model verification requirement. 

const (
	// ModelVerificationTrustedAccessForCyber indicates trusted access for cyber is required.
	ModelVerificationTrustedAccessForCyber ModelVerification = "trustedAccessForCyber"
)

Model verification constants.

type ModelVerificationNotification added in v0.5.6 

type ModelVerificationNotification struct {
	ThreadID      string              `json:"threadId"`
	TurnID        string              `json:"turnId"`
	Verifications []ModelVerification `json:"verifications"`
}

ModelVerificationNotification holds params for model/verification.

type MultiAgentVersion added in v0.7.6 

type MultiAgentVersion string

MultiAgentVersion identifies the multi-agent protocol supported by a model. 

const (
	MultiAgentVersionDisabled MultiAgentVersion = "disabled"
	MultiAgentVersionV1       MultiAgentVersion = "v1"
	MultiAgentVersionV2       MultiAgentVersion = "v2"
)

Multi-agent protocol versions.

type NetworkApprovalProtocol added in v0.6.0 

type NetworkApprovalProtocol string

NetworkApprovalProtocol is the protocol for network approval review actions. 

const (
	NetworkApprovalProtocolHTTP      NetworkApprovalProtocol = "http"
	NetworkApprovalProtocolHTTPS     NetworkApprovalProtocol = "https"
	NetworkApprovalProtocolSocks5TCP NetworkApprovalProtocol = "socks5Tcp"
	NetworkApprovalProtocolSocks5UDP NetworkApprovalProtocol = "socks5Udp"
)

Network approval protocol constants.

type PatchApplyStatus added in v0.5.6 

type PatchApplyStatus string

PatchApplyStatus is a file change lifecycle status. 

const (
	// PatchApplyStatusInProgress indicates the file change is still applying.
	PatchApplyStatusInProgress PatchApplyStatus = "inProgress"
	// PatchApplyStatusCompleted indicates the file change applied.
	PatchApplyStatusCompleted PatchApplyStatus = "completed"
	// PatchApplyStatusFailed indicates the file change failed.
	PatchApplyStatusFailed PatchApplyStatus = "failed"
	// PatchApplyStatusDeclined indicates the file change was not approved.
	PatchApplyStatusDeclined PatchApplyStatus = "declined"
)

Patch apply status constants.

type PatchChangeKind added in v0.4.1 

type PatchChangeKind struct {
	Type     PatchChangeKindType `json:"type"`
	MovePath *string             `json:"movePath,omitzero"`
}

PatchChangeKind is the discriminated kind for FileUpdateChange.

type PatchChangeKindType added in v0.5.6 

type PatchChangeKindType string

PatchChangeKindType is the type discriminator for a file change kind. 

const (
	// PatchChangeKindTypeAdd identifies an added file.
	PatchChangeKindTypeAdd PatchChangeKindType = "add"
	// PatchChangeKindTypeDelete identifies a deleted file.
	PatchChangeKindTypeDelete PatchChangeKindType = "delete"
	// PatchChangeKindTypeUpdate identifies an updated file.
	PatchChangeKindTypeUpdate PatchChangeKindType = "update"
)

Patch change kind type constants.

type Personality added in v0.5.6 

type Personality string

Personality controls assistant personality instructions. 

const (
	// PersonalityNone disables additional personality instructions.
	PersonalityNone Personality = "none"
	// PersonalityFriendly requests a friendly assistant personality.
	PersonalityFriendly Personality = "friendly"
	// PersonalityPragmatic requests a pragmatic assistant personality.
	PersonalityPragmatic Personality = "pragmatic"
)

Personality constants.

type PlanDeltaNotification added in v0.4.1 

type PlanDeltaNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	ItemID   string `json:"itemId"`
	Delta    string `json:"delta"`
}

PlanDeltaNotification holds params for item/plan/delta.

type PlanItem added in v0.4.1 

type PlanItem struct {
	ID   string   `json:"id"`
	Type ItemType `json:"type"`
	Text string   `json:"text,omitzero"`
}

PlanItem is an agent plan item.

type PlanType added in v0.7.0 

type PlanType string

PlanType identifies a Codex account plan. 

const (
	PlanTypeFree                        PlanType = "free"
	PlanTypeGo                          PlanType = "go"
	PlanTypePlus                        PlanType = "plus"
	PlanTypePro                         PlanType = "pro"
	PlanTypeProLite                     PlanType = "prolite"
	PlanTypeTeam                        PlanType = "team"
	PlanTypeSelfServeBusinessUsageBased PlanType = "self_serve_business_usage_based"
	PlanTypeSelfServeBusinessProLite    PlanType = "self_serve_business_prolite"
	PlanTypeBusiness                    PlanType = "business"
	PlanTypeEnt26                       PlanType = "ent26"
	PlanTypeEnterpriseCbpAutomation     PlanType = "enterprise_cbp_automation"
	PlanTypeEnterpriseCbpUsageBased     PlanType = "enterprise_cbp_usage_based"
	PlanTypeEnterprise                  PlanType = "enterprise"
	PlanTypeEdu                         PlanType = "edu"
	PlanTypeEduPlus                     PlanType = "edu_plus"
	PlanTypeEduPro                      PlanType = "edu_pro"
	PlanTypeUnknown                     PlanType = "unknown"
)

Plan type constants.

type ProjectChangeType added in v0.8.0 

type ProjectChangeType string

ProjectChangeType identifies how a project changed. 

const (
	ProjectChangeTypeCreated ProjectChangeType = "created"
	ProjectChangeTypeUpdated ProjectChangeType = "updated"
	ProjectChangeTypeDeleted ProjectChangeType = "deleted"
)

Project change types.

type ProjectChangedNotification added in v0.8.0 

type ProjectChangedNotification struct {
	ProjectID  string            `json:"projectId"`
	ChangeType ProjectChangeType `json:"changeType"`
}

ProjectChangedNotification holds params for project/changed.

type ProviderOption added in v0.9.0 

type ProviderOption struct {
	// DangerouslySkipPermissions starts or resumes the thread with approval
	// policy "never" and sandbox "danger-full-access", so shell commands run
	// unsandboxed without approval requests.
	DangerouslySkipPermissions bool
	// ExtraArgs are appended to the `codex app-server` command line, e.g.
	// []string{"-c", "key=value"}. --listen is rejected because the provider
	// owns the stdio transport.
	ExtraArgs []string
	// contains filtered or unexported fields
}

ProviderOption configures the codex process. It implements genai.ProviderOption.

All fields are opt-in. By default turns run at ReasoningEffortMedium and Codex fails the call when it requests an approval.

func (*ProviderOption) Validate added in v0.9.0 

func (p *ProviderOption) Validate() error

Validate implements genai.ProviderOption.

type RateLimitReachedType added in v0.7.0 

type RateLimitReachedType string

RateLimitReachedType identifies which account limit was exhausted. 

const (
	RateLimitReachedTypeRateLimitReached                 RateLimitReachedType = "rate_limit_reached"
	RateLimitReachedTypeWorkspaceOwnerCreditsDepleted    RateLimitReachedType = "workspace_owner_credits_depleted"
	RateLimitReachedTypeWorkspaceMemberCreditsDepleted   RateLimitReachedType = "workspace_member_credits_depleted"
	RateLimitReachedTypeWorkspaceOwnerUsageLimitReached  RateLimitReachedType = "workspace_owner_usage_limit_reached"
	RateLimitReachedTypeWorkspaceMemberUsageLimitReached RateLimitReachedType = "workspace_member_usage_limit_reached"
)

Rate-limit reached type constants.

type RateLimitResetCredit added in v0.8.0 

type RateLimitResetCredit struct {
	ID          string                     `json:"id"`
	ResetType   RateLimitResetType         `json:"resetType"`
	Status      RateLimitResetCreditStatus `json:"status"`
	GrantedAt   base.TimeS                 `json:"grantedAt"`
	ExpiresAt   base.TimeS                 `json:"expiresAt,omitzero"`
	Title       string                     `json:"title,omitzero"`
	Description string                     `json:"description,omitzero"`
}

RateLimitResetCredit is one available account rate-limit reset credit.

type RateLimitResetCreditStatus added in v0.8.0 

type RateLimitResetCreditStatus string

RateLimitResetCreditStatus is a reset-credit lifecycle status. 

const (
	RateLimitResetCreditStatusAvailable RateLimitResetCreditStatus = "available"
	RateLimitResetCreditStatusRedeeming RateLimitResetCreditStatus = "redeeming"
	RateLimitResetCreditStatusRedeemed  RateLimitResetCreditStatus = "redeemed"
	RateLimitResetCreditStatusUnknown   RateLimitResetCreditStatus = "unknown"
)

Rate-limit reset credit statuses.

type RateLimitResetCreditsSummary added in v0.7.0 

type RateLimitResetCreditsSummary struct {
	AvailableCount int64                  `json:"availableCount"`
	Credits        []RateLimitResetCredit `json:"credits,omitzero"`
}

RateLimitResetCreditsSummary summarizes available rate-limit reset credits.

type RateLimitResetType added in v0.8.0 

type RateLimitResetType string

RateLimitResetType identifies the quota reset performed by a credit. 

const (
	RateLimitResetTypeCodexRateLimits RateLimitResetType = "codexRateLimits"
	RateLimitResetTypeUnknown         RateLimitResetType = "unknown"
)

Rate-limit reset types.

type RateLimitSnapshot added in v0.7.0 

type RateLimitSnapshot struct {
	LimitID              string                     `json:"limitId,omitzero"`
	LimitName            string                     `json:"limitName,omitzero"`
	NormalModelSlug      string                     `json:"normalModelSlug,omitzero"`
	Primary              *RateLimitWindow           `json:"primary,omitzero"`
	Secondary            *RateLimitWindow           `json:"secondary,omitzero"`
	Credits              *CreditsSnapshot           `json:"credits,omitzero"`
	IndividualLimit      *SpendControlLimitSnapshot `json:"individualLimit,omitzero"`
	SpendControlReached  bool                       `json:"spendControlReached,omitzero"`
	PlanType             PlanType                   `json:"planType,omitzero"`
	RateLimitReachedType RateLimitReachedType       `json:"rateLimitReachedType,omitzero"`
}

RateLimitSnapshot is a Codex account rate-limit snapshot.

type RateLimitWindow added in v0.7.0 

type RateLimitWindow struct {
	UsedPercent        int        `json:"usedPercent"`
	WindowDurationMins int64      `json:"windowDurationMins,omitzero"`
	ResetsAt           base.TimeS `json:"resetsAt,omitzero"`
}

RateLimitWindow is one Codex rate-limit window.

type RawResponseCompletedNotification added in v0.8.0 

type RawResponseCompletedNotification struct {
	ThreadID      string              `json:"threadId"`
	TurnID        string              `json:"turnId"`
	ResponseID    string              `json:"responseId"`
	Usage         TokenUsageBreakdown `json:"usage,omitzero"`
	UsageMetadata json.RawMessage     `json:"usageMetadata,omitzero"`
}

RawResponseCompletedNotification contains exact usage from one Responses API call.

type RawResponseItemCompletedNotification added in v0.5.6 

type RawResponseItemCompletedNotification struct {
	ThreadID string          `json:"threadId"`
	TurnID   string          `json:"turnId"`
	Item     json.RawMessage `json:"item"`
}

RawResponseItemCompletedNotification holds params for rawResponseItem/completed.

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort controls how much reasoning the model performs. 

const (
	// ReasoningEffortNone disables model reasoning effort.
	ReasoningEffortNone ReasoningEffort = "none"
	// ReasoningEffortMinimal requests minimal model reasoning effort.
	ReasoningEffortMinimal ReasoningEffort = "minimal"
	// ReasoningEffortLow requests low model reasoning effort.
	ReasoningEffortLow ReasoningEffort = "low"
	// ReasoningEffortMedium requests medium model reasoning effort.
	ReasoningEffortMedium ReasoningEffort = "medium"
	// ReasoningEffortHigh requests high model reasoning effort.
	ReasoningEffortHigh ReasoningEffort = "high"
	// ReasoningEffortXHigh requests extra-high model reasoning effort.
	ReasoningEffortXHigh ReasoningEffort = "xhigh"
	// ReasoningEffortMax requests maximum model reasoning effort.
	ReasoningEffortMax ReasoningEffort = "max"
	// ReasoningEffortUltra requests maximum model reasoning with automatic task delegation.
	ReasoningEffortUltra ReasoningEffort = "ultra"
)

Reasoning effort levels, from least to most compute.

func (ReasoningEffort) Validate 

func (p ReasoningEffort) Validate() error

Validate returns an error when p is not a known effort level.

type ReasoningItem added in v0.4.1 

type ReasoningItem struct {
	ID      string   `json:"id"`
	Type    ItemType `json:"type"`
	Summary []string `json:"summary,omitzero"`
	Content []string `json:"content,omitzero"`
}

ReasoningItem is an agent reasoning/thinking item.

type ReasoningSummary added in v0.5.6 

type ReasoningSummary string

ReasoningSummary controls whether reasoning summaries are produced. 

const (
	// ReasoningSummaryAuto lets Codex choose the reasoning summary behavior.
	ReasoningSummaryAuto ReasoningSummary = "auto"
	// ReasoningSummaryConcise requests concise reasoning summaries.
	ReasoningSummaryConcise ReasoningSummary = "concise"
	// ReasoningSummaryDetailed requests detailed reasoning summaries.
	ReasoningSummaryDetailed ReasoningSummary = "detailed"
	// ReasoningSummaryNone disables reasoning summaries.
	ReasoningSummaryNone ReasoningSummary = "none"
)

Reasoning summary constants.

type ReasoningSummaryPartAddedNotification added in v0.4.1 

type ReasoningSummaryPartAddedNotification struct {
	ThreadID     string `json:"threadId"`
	TurnID       string `json:"turnId"`
	ItemID       string `json:"itemId"`
	SummaryIndex int    `json:"summaryIndex"`
}

ReasoningSummaryPartAddedNotification holds params for item/reasoning/summaryPartAdded.

type ReasoningSummaryTextDeltaNotification added in v0.4.1 

type ReasoningSummaryTextDeltaNotification struct {
	ThreadID     string `json:"threadId"`
	TurnID       string `json:"turnId"`
	ItemID       string `json:"itemId"`
	Delta        string `json:"delta"`
	SummaryIndex int    `json:"summaryIndex"`
}

ReasoningSummaryTextDeltaNotification holds params for item/reasoning/summaryTextDelta.

type ReasoningTextDeltaNotification added in v0.4.1 

type ReasoningTextDeltaNotification struct {
	ThreadID     string `json:"threadId"`
	TurnID       string `json:"turnId"`
	ItemID       string `json:"itemId"`
	Delta        string `json:"delta"`
	ContentIndex int    `json:"contentIndex"`
}

ReasoningTextDeltaNotification holds params for item/reasoning/textDelta.

type RemoteControlConnectionStatus added in v0.10.1 

type RemoteControlConnectionStatus string

RemoteControlConnectionStatus identifies the remote-control connection state. 

const (
	RemoteControlConnected  RemoteControlConnectionStatus = "connected"
	RemoteControlConnecting RemoteControlConnectionStatus = "connecting"
	RemoteControlDisabled   RemoteControlConnectionStatus = "disabled"
	RemoteControlErrored    RemoteControlConnectionStatus = "errored"
)

Remote-control connection states.

type RemoteControlStatusChangedNotification added in v0.10.1 

type RemoteControlStatusChangedNotification struct {
	Status         RemoteControlConnectionStatus `json:"status"`
	ServerName     string                        `json:"serverName"`
	InstallationID string                        `json:"installationId"`
	EnvironmentID  *string                       `json:"environmentId"`
}

RemoteControlStatusChangedNotification holds params for remoteControl/status/changed. Its shape follows the Codex 0.159.3 app-server protocol.

type SandboxMode added in v0.5.6 

type SandboxMode string

SandboxMode controls the sandbox mode for a thread. 

const (
	// SandboxModeReadOnly allows read-only filesystem access.
	SandboxModeReadOnly SandboxMode = "read-only"
	// SandboxModeWorkspaceWrite allows writes within the workspace.
	SandboxModeWorkspaceWrite SandboxMode = "workspace-write"
	// SandboxModeDangerFullAccess disables sandbox restrictions.
	SandboxModeDangerFullAccess SandboxMode = "danger-full-access"
)

Sandbox mode constants.

type SandboxNetworkAccess added in v0.8.0 

type SandboxNetworkAccess string

SandboxNetworkAccess accepts the boolean and named network policies used by sandbox variants. 

const (
	SandboxNetworkAccessRestricted SandboxNetworkAccess = "restricted"
	SandboxNetworkAccessEnabled    SandboxNetworkAccess = "enabled"
)

Sandbox network access policies.

func (*SandboxNetworkAccess) UnmarshalJSON added in v0.8.0 

func (s *SandboxNetworkAccess) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type SandboxPolicy added in v0.8.0 

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

SandboxPolicy describes the active filesystem and network sandbox.

type ServerRequestResolvedNotification added in v0.5.6 

type ServerRequestResolvedNotification struct {
	ThreadID  string          `json:"threadId"`
	RequestID json.RawMessage `json:"requestId"`
}

ServerRequestResolvedNotification holds params for serverRequest/resolved.

type SkillsChangedNotification added in v0.7.5 

type SkillsChangedNotification struct{}

SkillsChangedNotification holds params for skills/changed notifications.

type SleepItem added in v0.7.3 

type SleepItem struct {
	ID       string          `json:"id"`
	Type     ItemType        `json:"type"`
	Duration base.DurationMS `json:"durationMs,omitzero"`
}

SleepItem is an interruptible sleep tool item.

type SpendControlLimitSnapshot added in v0.7.0 

type SpendControlLimitSnapshot struct {
	Limit            string     `json:"limit"`
	Used             string     `json:"used"`
	RemainingPercent int        `json:"remainingPercent"`
	ResetsAt         base.TimeS `json:"resetsAt"`
}

SpendControlLimitSnapshot describes a Codex workspace spend-control limit.

type StrictReviewRequiredNotification added in v0.8.0 

type StrictReviewRequiredNotification struct {
	ThreadID  string      `json:"threadId"`
	TurnID    string      `json:"turnId"`
	StartedAt base.TimeMS `json:"startedAtMs"`
}

StrictReviewRequiredNotification requests a strict auto-approval review.

type SubAgentActivityItem added in v0.7.3 

type SubAgentActivityItem struct {
	ID            string               `json:"id"`
	Type          ItemType             `json:"type"`
	Kind          SubAgentActivityKind `json:"kind,omitzero"`
	AgentThreadID string               `json:"agentThreadId,omitzero"`
	AgentPath     string               `json:"agentPath,omitzero"`
	// Model and ReasoningEffort report resolved settings at sub-agent creation.
	Model           string          `json:"model,omitzero"`
	ReasoningEffort ReasoningEffort `json:"reasoningEffort,omitzero"`
}

SubAgentActivityItem reports a sub-agent lifecycle activity.

type SubAgentActivityKind added in v0.7.3 

type SubAgentActivityKind string

SubAgentActivityKind identifies a sub-agent lifecycle activity. 

const (
	// SubAgentActivityKindStarted identifies a newly started sub-agent.
	SubAgentActivityKindStarted SubAgentActivityKind = "started"
	// SubAgentActivityKindInteracted identifies an interaction with a sub-agent.
	SubAgentActivityKindInteracted SubAgentActivityKind = "interacted"
	// SubAgentActivityKindInterrupted identifies an interrupted sub-agent.
	SubAgentActivityKindInterrupted SubAgentActivityKind = "interrupted"
	// SubAgentActivityKindCompleted identifies a completed sub-agent.
	SubAgentActivityKindCompleted SubAgentActivityKind = "completed"
)

Sub-agent activity kind constants.

type TerminalInteractionNotification added in v0.4.1 

type TerminalInteractionNotification struct {
	ThreadID  string `json:"threadId"`
	TurnID    string `json:"turnId"`
	ItemID    string `json:"itemId"`
	ProcessID string `json:"processId"`
	Stdin     string `json:"stdin"`
}

TerminalInteractionNotification holds params for item/commandExecution/terminalInteraction.

type TextElement added in v0.6.0 

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

TextElement is a UI-defined span within a user input text block.

type Thread added in v0.4.1 

type Thread struct {
	ID             string              `json:"id"`
	Environments   []ThreadEnvironment `json:"environments,omitzero"`
	SessionID      string              `json:"sessionId,omitzero"`
	ForkedFromID   string              `json:"forkedFromId,omitzero"`
	ParentThreadID string              `json:"parentThreadId,omitzero"`
	ProjectID      string              `json:"projectId,omitzero"`
	CLIVersion     string              `json:"cliVersion,omitzero"`
	CreatedAt      base.TimeS          `json:"createdAt,omitzero"`
	CWD            string              `json:"cwd,omitzero"`
	Ephemeral      bool                `json:"ephemeral,omitzero"`
	GitInfo        *GitInfo            `json:"gitInfo,omitzero"`
	// Model is the current configured model or the latest persisted model. It is empty when unavailable.
	Model         string `json:"model,omitzero"`
	ModelProvider string `json:"modelProvider,omitzero"`
	// ReasoningEffort is the current configured effort or the latest persisted effort. It is empty when unavailable.
	ReasoningEffort      ReasoningEffort `json:"reasoningEffort,omitzero"`
	Path                 string          `json:"path,omitzero"`
	Preview              string          `json:"preview,omitzero"`
	Source               json.RawMessage `json:"source,omitzero"`
	ThreadSource         ThreadSource    `json:"threadSource,omitzero"`
	UpdatedAt            base.TimeS      `json:"updatedAt,omitzero"`
	RecencyAt            base.TimeS      `json:"recencyAt,omitzero"`
	Status               ThreadStatus    `json:"status,omitzero"`
	Name                 string          `json:"name,omitzero"`
	Extra                base.Unknown    `json:"extra,omitzero"`
	Section              base.Unknown    `json:"section,omitzero"`
	SectionEnteredAt     base.Unknown    `json:"sectionEnteredAt,omitzero"`
	CanAcceptDirectInput bool            `json:"canAcceptDirectInput,omitzero"`
	DaybreakEnabled      bool            `json:"daybreakEnabled,omitzero"`
	HistoryMode          string          `json:"historyMode,omitzero"`
	Originator           string          `json:"originator,omitzero"`
	AgentNickname        string          `json:"agentNickname,omitzero"`
	AgentRole            string          `json:"agentRole,omitzero"`
	Turns                []Turn          `json:"turns,omitzero"`
}

Thread describes a thread in thread/started params.

type ThreadActiveFlag added in v0.5.6 

type ThreadActiveFlag string

ThreadActiveFlag describes why a thread is active. 

const (
	// ThreadActiveFlagWaitingOnApproval indicates work is blocked on approval.
	ThreadActiveFlagWaitingOnApproval ThreadActiveFlag = "waitingOnApproval"
	// ThreadActiveFlagWaitingOnUserInput indicates work is blocked on user input.
	ThreadActiveFlagWaitingOnUserInput ThreadActiveFlag = "waitingOnUserInput"
)

Thread active flag constants.

type ThreadArchivedNotification added in v0.5.6 

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

ThreadArchivedNotification holds params for thread/archived.

type ThreadAttachmentOperation added in v0.10.2 

type ThreadAttachmentOperation string

ThreadAttachmentOperation describes a persisted attachment change. 

const (
	ThreadAttachmentOperationCreated ThreadAttachmentOperation = "created"
	ThreadAttachmentOperationDeleted ThreadAttachmentOperation = "deleted"
)

Thread attachment operations.

type ThreadAttachmentUpdatedNotification added in v0.10.2 

type ThreadAttachmentUpdatedNotification struct {
	ThreadID       string                    `json:"threadId"`
	AttachmentType string                    `json:"attachmentType"`
	IdentityKey    string                    `json:"identityKey"`
	AttachmentID   string                    `json:"attachmentId"`
	Operation      ThreadAttachmentOperation `json:"operation"`
}

ThreadAttachmentUpdatedNotification holds params for thread/attachment/updated.

type ThreadClosedNotification added in v0.5.6 

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

ThreadClosedNotification holds params for thread/closed.

type ThreadCompactStartParams added in v0.4.1 

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

ThreadCompactStartParams holds the params for thread/compact/start.

type ThreadDeletedNotification added in v0.8.0 

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

ThreadDeletedNotification holds params for thread/deleted.

type ThreadEnvironment added in v0.8.0 

type ThreadEnvironment struct {
	EnvironmentID         string   `json:"environmentId"`
	CWD                   string   `json:"cwd"`
	RuntimeWorkspaceRoots []string `json:"runtimeWorkspaceRoots"`
}

ThreadEnvironment is an environment selected by a loaded thread.

type ThreadGoal added in v0.6.0 

type ThreadGoal struct {
	ThreadID    string           `json:"threadId"`
	Objective   string           `json:"objective"`
	Status      ThreadGoalStatus `json:"status"`
	TokenBudget *int64           `json:"tokenBudget,omitzero"`
	TokensUsed  int64            `json:"tokensUsed"`
	TimeUsed    base.DurationS   `json:"timeUsedSeconds"`
	CreatedAt   base.TimeS       `json:"createdAt"`
	UpdatedAt   base.TimeS       `json:"updatedAt"`
}

ThreadGoal is the current long-running goal state for a thread.

type ThreadGoalClearedNotification added in v0.5.6 

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

ThreadGoalClearedNotification holds params for thread/goal/cleared.

type ThreadGoalStatus added in v0.6.0 

type ThreadGoalStatus string

ThreadGoalStatus is the lifecycle status of a thread goal. 

const (
	ThreadGoalStatusActive        ThreadGoalStatus = "active"
	ThreadGoalStatusPaused        ThreadGoalStatus = "paused"
	ThreadGoalStatusBlocked       ThreadGoalStatus = "blocked"
	ThreadGoalStatusUsageLimited  ThreadGoalStatus = "usageLimited"
	ThreadGoalStatusBudgetLimited ThreadGoalStatus = "budgetLimited"
	ThreadGoalStatusComplete      ThreadGoalStatus = "complete"
)

Thread goal status constants.

type ThreadGoalUpdatedNotification added in v0.5.6 

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

ThreadGoalUpdatedNotification holds params for thread/goal/updated.

type ThreadNameUpdatedNotification added in v0.4.1 

type ThreadNameUpdatedNotification struct {
	ThreadID   string  `json:"threadId"`
	ThreadName *string `json:"threadName,omitzero"`
}

ThreadNameUpdatedNotification holds params for thread/name/updated.

type ThreadPredictionResult added in v0.10.2 

type ThreadPredictionResult struct {
	Type ThreadPredictionResultType `json:"type"`
	Text *string                    `json:"text,omitzero"`
}

ThreadPredictionResult is the tagged result of a thread prediction.

type ThreadPredictionResultType added in v0.10.2 

type ThreadPredictionResultType string

ThreadPredictionResultType identifies the outcome of a thread prediction. 

const (
	ThreadPredictionResultTypeCompleted ThreadPredictionResultType = "completed"
	ThreadPredictionResultTypeFailed    ThreadPredictionResultType = "failed"
)

Thread prediction outcomes.

type ThreadPredictionUpdatedNotification added in v0.10.2 

type ThreadPredictionUpdatedNotification struct {
	ThreadID     string                 `json:"threadId"`
	SourceTurnID string                 `json:"sourceTurnId"`
	Result       ThreadPredictionResult `json:"result"`
}

ThreadPredictionUpdatedNotification holds params for thread/prediction/updated.

type ThreadProjectUpdatedNotification added in v0.8.0 

type ThreadProjectUpdatedNotification struct {
	ThreadID  string `json:"threadId"`
	ProjectID string `json:"projectId,omitzero"`
}

ThreadProjectUpdatedNotification holds params for thread/project/updated.

type ThreadQueueChangedNotification added in v0.8.0 

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

ThreadQueueChangedNotification holds params for thread/queue/changed.

type ThreadRealtimeItemCompletedNotification added in v0.8.0 

type ThreadRealtimeItemCompletedNotification struct {
	ThreadID string          `json:"threadId"`
	Item     json.RawMessage `json:"item"`
}

ThreadRealtimeItemCompletedNotification holds a completed realtime item.

type ThreadRealtimeItemStartedNotification added in v0.8.0 

type ThreadRealtimeItemStartedNotification struct {
	ThreadID string          `json:"threadId"`
	Item     json.RawMessage `json:"item"`
}

ThreadRealtimeItemStartedNotification holds a realtime item start.

type ThreadRealtimeItemTranscriptDeltaNotification added in v0.8.0 

type ThreadRealtimeItemTranscriptDeltaNotification struct {
	ThreadID string `json:"threadId"`
	ItemID   string `json:"itemId"`
	Delta    string `json:"delta"`
}

ThreadRealtimeItemTranscriptDeltaNotification holds realtime item transcript text.

type ThreadResumeParams added in v0.4.1 

type ThreadResumeParams struct {
	ThreadID              string                     `json:"threadId"`
	Model                 string                     `json:"model,omitzero"`
	ModelProvider         string                     `json:"modelProvider,omitzero"`
	ServiceTier           *string                    `json:"serviceTier,omitzero"`
	Cwd                   string                     `json:"cwd,omitzero"`
	ApprovalPolicy        json.RawMessage            `json:"approvalPolicy,omitzero"`
	ApprovalsReviewer     ApprovalsReviewer          `json:"approvalsReviewer,omitzero"`
	Sandbox               SandboxMode                `json:"sandbox,omitzero"`
	Config                map[string]json.RawMessage `json:"config,omitzero"`
	BaseInstructions      string                     `json:"baseInstructions,omitzero"`
	DeveloperInstructions string                     `json:"developerInstructions,omitzero"`
	Personality           Personality                `json:"personality,omitzero"`
	ExcludeTurns          bool                       `json:"excludeTurns,omitzero"`
}

ThreadResumeParams holds the params for thread/resume.

type ThreadResumeResponse added in v0.8.0 

type ThreadResumeResponse struct {
	ThreadStartResponse

	TurnsBackwardsCursor string             `json:"turnsBackwardsCursor,omitzero"`
	ItemsBackwardsCursor string             `json:"itemsBackwardsCursor,omitzero"`
	CollaborationMode    *CollaborationMode `json:"collaborationMode,omitzero"`
}

ThreadResumeResponse is the result object from a thread/resume JSON-RPC response.

type ThreadRevertedNotification added in v0.8.0 

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

ThreadRevertedNotification holds params for thread/reverted.

type ThreadRollbackParams added in v0.4.1 

type ThreadRollbackParams struct {
	ThreadID string `json:"threadId"`
	NumTurns uint32 `json:"numTurns"`
}

ThreadRollbackParams holds the params for thread/rollback.

type ThreadSettings added in v0.6.0 

type ThreadSettings struct {
	Cwd                     string                   `json:"cwd"`
	ApprovalPolicy          json.RawMessage          `json:"approvalPolicy"`
	ApprovalsReviewer       ApprovalsReviewer        `json:"approvalsReviewer"`
	SandboxPolicy           json.RawMessage          `json:"sandboxPolicy"`
	ActivePermissionProfile *ActivePermissionProfile `json:"activePermissionProfile,omitzero"`
	Model                   string                   `json:"model"`
	ModelProvider           string                   `json:"modelProvider"`
	ServiceTier             *string                  `json:"serviceTier,omitzero"`
	Effort                  *ReasoningEffort         `json:"effort,omitzero"`
	Summary                 *ReasoningSummary        `json:"summary,omitzero"`
	CollaborationMode       json.RawMessage          `json:"collaborationMode"`
	MultiAgentMode          string                   `json:"multiAgentMode,omitzero"`
	Personality             *Personality             `json:"personality,omitzero"`
	DisabledPluginIDs       []string                 `json:"disabledPluginIds,omitzero"`
}

ThreadSettings contains the active settings for a thread.

type ThreadSettingsUpdatedNotification added in v0.5.6 

type ThreadSettingsUpdatedNotification struct {
	ThreadID       string         `json:"threadId"`
	ThreadSettings ThreadSettings `json:"threadSettings"`
}

ThreadSettingsUpdatedNotification holds params for thread/settings/updated.

type ThreadSource added in v0.5.6 

type ThreadSource string

ThreadSource classifies the analytics source for a thread. 

const (
	// ThreadSourceUser indicates a user-created thread.
	ThreadSourceUser ThreadSource = "user"
	// ThreadSourceSubagent indicates a subagent-created thread.
	ThreadSourceSubagent ThreadSource = "subagent"
	// ThreadSourceMemoryConsolidation indicates a memory consolidation thread.
	ThreadSourceMemoryConsolidation ThreadSource = "memory_consolidation"
)

Thread source constants.

type ThreadStartParams added in v0.4.1 

type ThreadStartParams struct {
	Model                 string                     `json:"model,omitzero"`
	ModelProvider         string                     `json:"modelProvider,omitzero"`
	ServiceTier           *string                    `json:"serviceTier,omitzero"`
	Cwd                   string                     `json:"cwd,omitzero"`
	RuntimeWorkspaceRoots []string                   `json:"runtimeWorkspaceRoots,omitzero"`
	ApprovalPolicy        json.RawMessage            `json:"approvalPolicy,omitzero"`
	ApprovalsReviewer     ApprovalsReviewer          `json:"approvalsReviewer,omitzero"`
	Sandbox               SandboxMode                `json:"sandbox,omitzero"`
	Permissions           string                     `json:"permissions,omitzero"`
	Config                map[string]json.RawMessage `json:"config,omitzero"`
	ServiceName           string                     `json:"serviceName,omitzero"`
	BaseInstructions      string                     `json:"baseInstructions,omitzero"`
	DeveloperInstructions string                     `json:"developerInstructions,omitzero"`
	Personality           Personality                `json:"personality,omitzero"`
	Ephemeral             bool                       `json:"ephemeral,omitzero"`
	SessionStartSource    ThreadStartSource          `json:"sessionStartSource,omitzero"`
	ThreadSource          ThreadSource               `json:"threadSource,omitzero"`
}

ThreadStartParams holds the params for thread/start.

type ThreadStartResponse added in v0.8.0 

type ThreadStartResponse struct {
	Thread                  Thread                   `json:"thread"`
	Model                   string                   `json:"model,omitzero"`
	ModelProvider           string                   `json:"modelProvider,omitzero"`
	ServiceTier             *string                  `json:"serviceTier,omitzero"`
	Cwd                     string                   `json:"cwd,omitzero"`
	RuntimeWorkspaceRoots   []string                 `json:"runtimeWorkspaceRoots,omitzero"`
	InstructionSources      []string                 `json:"instructionSources,omitzero"`
	ApprovalPolicy          json.RawMessage          `json:"approvalPolicy,omitzero"`
	ApprovalsReviewer       ApprovalsReviewer        `json:"approvalsReviewer,omitzero"`
	Sandbox                 SandboxPolicy            `json:"sandbox,omitzero"`
	ActivePermissionProfile *ActivePermissionProfile `json:"activePermissionProfile,omitzero"`
	ReasoningEffort         *ReasoningEffort         `json:"reasoningEffort,omitzero"`
	MultiAgentMode          string                   `json:"multiAgentMode,omitzero"`
	DisabledPluginIDs       []string                 `json:"disabledPluginIds,omitzero"`
	InitialTurnsPage        base.Unknown             `json:"initialTurnsPage,omitzero"`
}

ThreadStartResponse is the result object from a thread/start JSON-RPC response.

type ThreadStartSource added in v0.5.6 

type ThreadStartSource string

ThreadStartSource describes why a new thread was started. 

const (
	// ThreadStartSourceStartup indicates a thread was started during startup.
	ThreadStartSourceStartup ThreadStartSource = "startup"
	// ThreadStartSourceClear indicates a thread was started by clearing state.
	ThreadStartSourceClear ThreadStartSource = "clear"
)

Thread start source constants.

type ThreadStartedNotification added in v0.4.1 

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

ThreadStartedNotification holds the params for thread/started notifications.

type ThreadStatus added in v0.4.1 

type ThreadStatus struct {
	Type        ThreadStatusType   `json:"type"`
	ActiveFlags []ThreadActiveFlag `json:"activeFlags,omitzero"`
}

ThreadStatus is a tagged union representing thread lifecycle state. Variants: notLoaded, idle, systemError, active (with activeFlags).

type ThreadStatusChangedNotification added in v0.4.1 

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

ThreadStatusChangedNotification holds params for thread/status/changed.

type ThreadStatusType added in v0.5.6 

type ThreadStatusType string

ThreadStatusType is the type discriminator for thread status. 

const (
	// ThreadStatusTypeNotLoaded indicates the thread status was not loaded.
	ThreadStatusTypeNotLoaded ThreadStatusType = "notLoaded"
	// ThreadStatusTypeIdle indicates the thread has no active turn.
	ThreadStatusTypeIdle ThreadStatusType = "idle"
	// ThreadStatusTypeSystemError indicates a system-level thread error.
	ThreadStatusTypeSystemError ThreadStatusType = "systemError"
	// ThreadStatusTypeActive indicates the thread has active work.
	ThreadStatusTypeActive ThreadStatusType = "active"
)

Thread status type constants.

type ThreadTokenUsage added in v0.4.1 

type ThreadTokenUsage struct {
	Total              TokenUsageBreakdown `json:"total"`
	Last               TokenUsageBreakdown `json:"last"`
	ModelContextWindow *int64              `json:"modelContextWindow,omitzero"`
}

ThreadTokenUsage holds cumulative and per-turn token usage for a thread.

type ThreadTokenUsageUpdatedNotification added in v0.4.1 

type ThreadTokenUsageUpdatedNotification struct {
	ThreadID   string           `json:"threadId"`
	TurnID     string           `json:"turnId"`
	TokenUsage ThreadTokenUsage `json:"tokenUsage"`
}

ThreadTokenUsageUpdatedNotification holds params for thread/tokenUsage/updated notifications.

type ThreadUnarchivedNotification added in v0.5.6 

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

ThreadUnarchivedNotification holds params for thread/unarchived.

type TokenUsageBreakdown added in v0.4.1 

type TokenUsageBreakdown struct {
	TotalTokens           int64 `json:"totalTokens"`
	InputTokens           int64 `json:"inputTokens"`
	CachedInputTokens     int64 `json:"cachedInputTokens"`
	CacheWriteInputTokens int64 `json:"cacheWriteInputTokens"`
	OutputTokens          int64 `json:"outputTokens"`
	ReasoningOutputTokens int64 `json:"reasoningOutputTokens"`
}

TokenUsageBreakdown contains a detailed breakdown of token counts.

type Turn added in v0.4.1 

type Turn struct {
	ID          string            `json:"id"`
	RootTurnID  string            `json:"rootTurnId,omitzero"`
	Items       []json.RawMessage `json:"items,omitzero"`
	ItemsView   TurnItemsView     `json:"itemsView,omitzero"`
	Status      TurnStatus        `json:"status"`
	Error       *TurnError        `json:"error,omitzero"`
	StartedAt   base.TimeS        `json:"startedAt,omitzero"`
	CompletedAt base.TimeS        `json:"completedAt,omitzero"`
	Duration    *base.DurationMS  `json:"durationMs,omitzero"`
}

Turn describes a turn in turn/started and turn/completed params.

type TurnCompletedNotification added in v0.4.1 

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

TurnCompletedNotification holds the params for turn/completed notifications.

type TurnDiffUpdatedNotification added in v0.4.1 

type TurnDiffUpdatedNotification struct {
	ThreadID string `json:"threadId"`
	TurnID   string `json:"turnId"`
	Diff     string `json:"diff"`
}

TurnDiffUpdatedNotification holds params for turn/diff/updated.

type TurnEnvironmentParams added in v0.6.0 

type TurnEnvironmentParams struct {
	EnvironmentID         string   `json:"environmentId"`
	Cwd                   string   `json:"cwd"`
	RuntimeWorkspaceRoots []string `json:"runtimeWorkspaceRoots,omitzero"`
}

TurnEnvironmentParams selects a turn or thread environment.

type TurnError added in v0.4.1 

type TurnError struct {
	Message           string                   `json:"message"`
	CodexErrorInfo    json.RawMessage          `json:"codexErrorInfo,omitzero"`
	AdditionalDetails string                   `json:"additionalDetails,omitzero"`
	Misalignment      MisalignmentErrorDetails `json:"misalignment,omitzero"`
}

TurnError describes a turn failure.

type TurnInput added in v0.4.1 

type TurnInput struct {
	Type         TurnInputType `json:"type"`
	Text         string        `json:"text,omitzero"`
	TextElements []TextElement `json:"textElements,omitzero"`
	Detail       ImageDetail   `json:"detail,omitzero"`
	URL          string        `json:"url,omitzero"`
	Path         string        `json:"path,omitzero"`
	Name         string        `json:"name,omitzero"`
}

TurnInput is a single item in the turn/start input array. Type is "text", "image" (with URL as data URI), "localImage" (with Path), "skill" (with Name + Path), or "mention" (with Name + Path).

type TurnInputType added in v0.5.6 

type TurnInputType string

TurnInputType is the type discriminator for turn input entries. 

const (
	// TurnInputTypeText identifies text input.
	TurnInputTypeText TurnInputType = "text"
	// TurnInputTypeImage identifies image input by URL or data URL.
	TurnInputTypeImage TurnInputType = "image"
	// TurnInputTypeLocalImage identifies image input by local path.
	TurnInputTypeLocalImage TurnInputType = "localImage"
	// TurnInputTypeAudio identifies audio input by URL.
	TurnInputTypeAudio TurnInputType = "audio"
	// TurnInputTypeLocalAudio identifies audio input by local path.
	TurnInputTypeLocalAudio TurnInputType = "localAudio"
	// TurnInputTypeSkill identifies skill input.
	TurnInputTypeSkill TurnInputType = "skill"
	// TurnInputTypeMention identifies mention input.
	TurnInputTypeMention TurnInputType = "mention"
)

Turn input type constants.

type TurnInterruptParams added in v0.4.1 

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

TurnInterruptParams holds the params for turn/interrupt.

type TurnItemsView added in v0.5.6 

type TurnItemsView string

TurnItemsView describes how much item detail is included in a turn payload. 

const (
	// TurnItemsViewNotLoaded indicates turn items were not loaded.
	TurnItemsViewNotLoaded TurnItemsView = "notLoaded"
	// TurnItemsViewSummary indicates a summary view of turn items.
	TurnItemsViewSummary TurnItemsView = "summary"
	// TurnItemsViewFull indicates full turn item payloads.
	TurnItemsViewFull TurnItemsView = "full"
)

Turn items view constants.

type TurnModerationMetadataNotification added in v0.6.0 

type TurnModerationMetadataNotification struct {
	ThreadID string          `json:"threadId"`
	TurnID   string          `json:"turnId"`
	Metadata json.RawMessage `json:"metadata"`
}

TurnModerationMetadataNotification holds params for turn/moderationMetadata.

type TurnPlanStep added in v0.6.0 

type TurnPlanStep struct {
	Step   string             `json:"step"`
	Status TurnPlanStepStatus `json:"status"`
}

TurnPlanStep is one step in a turn plan update.

type TurnPlanStepStatus added in v0.6.0 

type TurnPlanStepStatus string

TurnPlanStepStatus is a plan step lifecycle state. 

const (
	TurnPlanStepStatusPending    TurnPlanStepStatus = "pending"
	TurnPlanStepStatusInProgress TurnPlanStepStatus = "inProgress"
	TurnPlanStepStatusCompleted  TurnPlanStepStatus = "completed"
)

Turn plan step status constants.

type TurnPlanUpdatedNotification added in v0.4.1 

type TurnPlanUpdatedNotification struct {
	ThreadID    string         `json:"threadId"`
	TurnID      string         `json:"turnId"`
	Explanation *string        `json:"explanation,omitzero"`
	Plan        []TurnPlanStep `json:"plan,omitzero"`
}

TurnPlanUpdatedNotification holds params for turn/plan/updated.

type TurnStartParams added in v0.4.1 

type TurnStartParams struct {
	ThreadID string `json:"threadId"`
	// ParentTurnID identifies the completed turn whose work this turn continues.
	ParentTurnID string `json:"parentTurnId,omitzero"`
	// RootTurnID attributes descendant work to the first turn in the chain.
	RootTurnID string `json:"rootTurnId,omitzero"`
	// DisabledPluginIDs overrides the thread's saved disabled plugin selection.
	DisabledPluginIDs   []string          `json:"disabledPluginIds,omitzero"`
	ClientUserMessageID string            `json:"clientUserMessageId,omitzero"`
	Input               []TurnInput       `json:"input"`
	TurnTrigger         string            `json:"turnTrigger,omitzero"`
	ToolOutput          TurnToolOutput    `json:"toolOutput,omitzero"`
	Cwd                 string            `json:"cwd,omitzero"`
	ApprovalPolicy      json.RawMessage   `json:"approvalPolicy,omitzero"`
	ApprovalsReviewer   ApprovalsReviewer `json:"approvalsReviewer,omitzero"`
	SandboxPolicy       json.RawMessage   `json:"sandboxPolicy,omitzero"`
	Model               string            `json:"model,omitzero"`
	ServiceTier         *string           `json:"serviceTier,omitzero"`
	ServiceTierForTurn  string            `json:"serviceTierForTurn,omitzero"`
	Effort              ReasoningEffort   `json:"effort,omitzero"`
	Summary             ReasoningSummary  `json:"summary,omitzero"`
	Personality         Personality       `json:"personality,omitzero"`
	OutputSchema        json.RawMessage   `json:"outputSchema,omitzero"`
}

TurnStartParams holds the params for turn/start.

type TurnStartedNotification added in v0.4.1 

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

TurnStartedNotification holds the params for turn/started notifications.

type TurnStatus added in v0.5.6 

type TurnStatus string

TurnStatus is a turn lifecycle status. 

const (
	// TurnStatusCompleted indicates the turn completed normally.
	TurnStatusCompleted TurnStatus = "completed"
	// TurnStatusInterrupted indicates the turn was interrupted.
	TurnStatusInterrupted TurnStatus = "interrupted"
	// TurnStatusFailed indicates the turn failed.
	TurnStatusFailed TurnStatus = "failed"
	// TurnStatusInProgress indicates the turn is still running.
	TurnStatusInProgress TurnStatus = "inProgress"
)

Turn status constants.

type TurnSteerParams added in v0.4.1 

type TurnSteerParams struct {
	ThreadID                   string                            `json:"threadId"`
	ClientUserMessageID        string                            `json:"clientUserMessageId,omitzero"`
	Input                      []TurnInput                       `json:"input"`
	ResponsesAPIClientMetadata map[string]string                 `json:"responsesapiClientMetadata,omitzero"`
	AdditionalContext          map[string]AdditionalContextEntry `json:"additionalContext,omitzero"`
	ExpectedTurnID             string                            `json:"expectedTurnId"`
}

TurnSteerParams holds the params for turn/steer.

type TurnToolOutput added in v0.8.0 

type TurnToolOutput struct {
	Name      string          `json:"name"`
	Namespace string          `json:"namespace,omitzero"`
	Output    json.RawMessage `json:"output"`
}

TurnToolOutput is a function-call result supplied while starting a turn.

type UserInput added in v0.6.0 

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

UserInput is a single inbound user input content block in a userMessage item.

type UserMessageItem added in v0.4.1 

type UserMessageItem struct {
	ID       string      `json:"id"`
	Type     ItemType    `json:"type"`
	ClientID *string     `json:"clientId,omitzero"`
	Content  []UserInput `json:"content,omitzero"`
}

UserMessageItem is a user-submitted message item.

type WarningNotification added in v0.5.6 

type WarningNotification struct {
	ThreadID *string `json:"threadId,omitzero"`
	Message  string  `json:"message"`
}

WarningNotification holds params for warning.

type WebSearchAction added in v0.4.1 

type WebSearchAction struct {
	Type    WebSearchActionType `json:"type"`
	Query   string              `json:"query,omitzero"`
	Queries []string            `json:"queries,omitzero"`
	URL     string              `json:"url,omitzero"`
	Pattern string              `json:"pattern,omitzero"`
}

WebSearchAction is the action object within a webSearch item.

type WebSearchActionType added in v0.5.6 

type WebSearchActionType string

WebSearchActionType is the type discriminator for a web search action. 

const (
	// WebSearchActionTypeSearch identifies a search query action.
	WebSearchActionTypeSearch WebSearchActionType = "search"
	// WebSearchActionTypeOpenPage identifies an open-page action.
	WebSearchActionTypeOpenPage WebSearchActionType = "openPage"
	// WebSearchActionTypeFindInPage identifies an in-page find action.
	WebSearchActionTypeFindInPage WebSearchActionType = "findInPage"
	// WebSearchActionTypeOther identifies an action outside the typed cases.
	WebSearchActionTypeOther WebSearchActionType = "other"
)

Web search action type constants.

type WebSearchItem added in v0.4.1 

type WebSearchItem struct {
	ID      string            `json:"id"`
	Type    ItemType          `json:"type"`
	Query   string            `json:"query,omitzero"`
	Action  *WebSearchAction  `json:"action,omitzero"`
	Results []json.RawMessage `json:"results,omitzero"`
}

WebSearchItem is a web search item.

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.