sdk

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RoleUser      = types.RoleUser
	RoleAssistant = types.RoleAssistant
	RoleSystem    = types.RoleSystem

	APIProviderAnthropic = types.APIProviderAnthropic

	APIProviderBedrock    = types.APIProviderBedrock
	APIProviderCodex      = types.APIProviderCodex
	APIProviderDeepSeek   = types.APIProviderDeepSeek
	APIProviderFoundry    = types.APIProviderFoundry
	APIProviderGemini     = types.APIProviderGemini
	APIProviderMistral    = types.APIProviderMistral
	APIProviderMiniMax    = types.APIProviderMiniMax
	APIProviderOllama     = types.APIProviderOllama
	APIProviderOpenCode   = types.APIProviderOpenCode
	APIProviderOpenAI     = types.APIProviderOpenAI
	APIProviderOpenRouter = types.APIProviderOpenRouter
	APIProviderVertex     = types.APIProviderVertex
	APIProviderWorkersAI  = types.APIProviderWorkersAI
	APIProviderZAi        = types.APIProviderZAi
	APIProviderKimi       = types.APIProviderKimi

	ExecutionModeExecute         = modes.ExecutionModeExecute
	ExecutionModePlan            = modes.ExecutionModePlan
	ExecutionModePairProgramming = modes.ExecutionModePairProgramming

	PermissionModeAuto        = types.PermissionModeAuto
	PermissionModeBypass      = types.PermissionModeBypass
	PermissionModeOnRequest   = types.PermissionModeOnRequest
	PermissionModeNever       = types.PermissionModeNever
	PermissionModeAcceptEdits = types.PermissionModeAcceptEdits
	PermissionModeGranular    = types.PermissionModeGranular

	SessionStatusActive = types.SessionStatusActive
	SessionStatusClosed = types.SessionStatusClosed

	EntryTypeMessage = types.EntryTypeMessage
	EntryTypeTurn    = types.EntryTypeTurn
	EntryTypeCompact = types.EntryTypeCompact
	EntryTypeSystem  = types.EntryTypeSystem
	EntryTypeControl = types.EntryTypeControl

	ResponseChunkTypeContentBlockStart = types.APIChunkTypeContentBlockStart
	ResponseChunkTypeContentBlockDelta = types.APIChunkTypeContentBlockDelta
	ResponseChunkTypeContentBlockStop  = types.APIChunkTypeContentBlockStop
	ResponseChunkTypeMessageDelta      = types.APIChunkTypeMessageDelta
	ResponseChunkTypeMessageStop       = types.APIChunkTypeMessageStop
	ResponseChunkTypeError             = types.APIChunkTypeError

	ToolHookStagePre  = execution.ToolHookStagePre
	ToolHookStagePost = execution.ToolHookStagePost

	ToolProgressStagePending   = types.ToolProgressStagePending
	ToolProgressStageRunning   = types.ToolProgressStageRunning
	ToolProgressStageCompleted = types.ToolProgressStageCompleted
	ToolProgressStageFailed    = types.ToolProgressStageFailed

	NamespaceDocuments          = storage.NamespaceDocuments
	NamespaceWebArtifacts       = storage.NamespaceWebArtifacts
	NamespaceBrowserScreenshots = storage.NamespaceBrowserScreenshots
	NamespaceBrowserDownloads   = storage.NamespaceBrowserDownloads
	NamespaceRAGDocuments       = storage.NamespaceRAGDocuments

	RetentionDurable   = storage.RetentionDurable
	RetentionTemporary = storage.RetentionTemporary
	RetentionSession   = storage.RetentionSession

	RuntimeEventTypeTurnStarted          = types.RuntimeEventTypeTurnStarted
	RuntimeEventTypeTurnCompleted        = types.RuntimeEventTypeTurnCompleted
	RuntimeEventTypeTurnFailed           = types.RuntimeEventTypeTurnFailed
	RuntimeEventTypeResponseChunk        = types.RuntimeEventTypeResponseChunk
	RuntimeEventTypeToolProgress         = types.RuntimeEventTypeToolProgress
	RuntimeEventTypePlanSubmitted        = types.RuntimeEventTypePlanSubmitted
	RuntimeEventTypePlanStatusChanged    = types.RuntimeEventTypePlanStatusChanged
	RuntimeEventTypeExecutionModeChanged = types.RuntimeEventTypeExecutionModeChanged
	RuntimeEventTypeTaskChanged          = types.RuntimeEventTypeTaskChanged
	RuntimeEventTypeBrowserSession       = types.RuntimeEventTypeBrowserSession
	RuntimeEventTypeBrowserAction        = types.RuntimeEventTypeBrowserAction
	RuntimeEventTypeBrowserPage          = types.RuntimeEventTypeBrowserPage
	RuntimeEventTypeBrowserSnapshot      = types.RuntimeEventTypeBrowserSnapshot
	RuntimeEventTypeBrowserScreenshot    = types.RuntimeEventTypeBrowserScreenshot

	// HookEvent constants — lifecycle events emitted throughout the engine.
	HookEventSessionStart       = types.HookEventSessionStart
	HookEventSessionEnd         = types.HookEventSessionEnd
	HookEventQueryStart         = types.HookEventQueryStart
	HookEventQueryComplete      = types.HookEventQueryComplete
	HookEventIterationStart     = types.HookEventIterationStart
	HookEventIterationStop      = types.HookEventIterationStop
	HookEventIterationContinue  = types.HookEventIterationContinue
	HookEventIterationComplete  = types.HookEventIterationComplete
	HookEventToolUsesStart      = types.HookEventToolUsesStart
	HookEventToolUsesComplete   = types.HookEventToolUsesComplete
	HookEventTurnStart          = types.HookEventTurnStart
	HookEventTurnEnd            = types.HookEventTurnEnd
	HookEventTurnStop           = types.HookEventTurnStop
	HookEventStopFailure        = types.HookEventStopFailure
	HookEventPreToolUse         = types.HookEventPreToolUse
	HookEventPostToolUse        = types.HookEventPostToolUse
	HookEventPostToolUseFail    = types.HookEventPostToolUseFail
	HookEventPreCompact         = types.HookEventPreCompact
	HookEventPostCompact        = types.HookEventPostCompact
	HookEventPreAPICall         = types.HookEventPreAPICall
	HookEventPostAPICall        = types.HookEventPostAPICall
	HookEventOnError            = types.HookEventOnError
	HookEventNotification       = types.HookEventNotification
	HookEventUserPromptSubmit   = types.HookEventUserPromptSubmit
	HookEventSubagentStart      = types.HookEventSubagentStart
	HookEventSubagentStop       = types.HookEventSubagentStop
	HookEventPermissionRequest  = types.HookEventPermissionRequest
	HookEventPermissionDenied   = types.HookEventPermissionDenied
	HookEventSetup              = types.HookEventSetup
	HookEventConfigChange       = types.HookEventConfigChange
	HookEventTeammateIdle       = types.HookEventTeammateIdle
	HookEventTaskCreated        = types.HookEventTaskCreated
	HookEventTaskCompleted      = types.HookEventTaskCompleted
	HookEventElicitation        = types.HookEventElicitation
	HookEventElicitationResult  = types.HookEventElicitationResult
	HookEventWorktreeCreate     = types.HookEventWorktreeCreate
	HookEventWorktreeRemove     = types.HookEventWorktreeRemove
	HookEventInstructionsLoaded = types.HookEventInstructionsLoaded
	HookEventCwdChanged         = types.HookEventCwdChanged
	HookEventFileChanged        = types.HookEventFileChanged

	// HookState constants
	HookStateActive   = hooks.HookStateActive
	HookStatePaused   = hooks.HookStatePaused
	HookStateInactive = hooks.HookStateInactive
	HookStateDead     = hooks.HookStateDead

	// PermissionBehavior constants
	PermissionBehaviorAllow       = types.PermissionBehaviorAllow
	PermissionBehaviorDeny        = types.PermissionBehaviorDeny
	PermissionBehaviorAsk         = types.PermissionBehaviorAsk
	PermissionBehaviorPassthrough = types.PermissionBehaviorPassthrough

	// MCPTransport constants
	MCPTransportStdio     MCPTransportType = mcp.TransportTypeStdio
	MCPTransportHTTP      MCPTransportType = mcp.TransportTypeHTTP
	MCPTransportSSE       MCPTransportType = mcp.TransportTypeSSE
	MCPTransportWebSocket MCPTransportType = mcp.TransportTypeWebSocket
)
View Source 
const DefaultOpenAIDeviceClientID = "app_EMoamEEZ73f0CkXaXp7hrann"

Variables

This section is empty.

Functions

This section is empty.

Types

type APIProvider 

type APIProvider = types.APIProvider

Core types

type ArtifactGCOptions 

type ArtifactGCOptions = storage.GCOptions

Storage data types — re-exported so SDK callers don't need to import internal/storage.

type ArtifactGCReport 

type ArtifactGCReport = storage.GCReport

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactListOptions 

type ArtifactListOptions = storage.ListOptions

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactMetadata 

type ArtifactMetadata = storage.ArtifactMetadata

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactNamespace 

type ArtifactNamespace = storage.ArtifactNamespace

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactPutRequest 

type ArtifactPutRequest = storage.ArtifactPutRequest

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactRef 

type ArtifactRef = storage.ArtifactRef

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactRetentionClass 

type ArtifactRetentionClass = storage.ArtifactRetentionClass

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ArtifactStore 

type ArtifactStore interface {
	Put(ctx context.Context, key string, body []byte, contentType string) (ArtifactRef, error)
	PutArtifact(ctx context.Context, request ArtifactPutRequest, body []byte) (ArtifactRef, error)
	Get(ctx context.Context, key string) ([]byte, error)
	OpenReader(ctx context.Context, key string) (io.ReadCloser, ArtifactRef, error)
	Stat(ctx context.Context, key string) (ArtifactRef, error)
	List(ctx context.Context, options ArtifactListOptions) ([]ArtifactRef, error)
	Metadata(ctx context.Context, key string) (ArtifactMetadata, error)
	ListMetadata(ctx context.Context, options ArtifactListOptions) ([]ArtifactMetadata, error)
	GarbageCollect(ctx context.Context, options ArtifactGCOptions) (ArtifactGCReport, error)
	Delete(ctx context.Context, key string) error
	Exists(ctx context.Context, key string) (bool, error)
	URL(ctx context.Context, key string) (string, error)
}

ArtifactStore is the SDK-owned artifact storage contract.

func DefaultArtifactStore 

func DefaultArtifactStore() (ArtifactStore, error)

DefaultArtifactStore returns the process-wide artifact store configured for the runtime.

func NewArtifactStoreFromConfig 

func NewArtifactStoreFromConfig(cfg StorageConfig) (ArtifactStore, error)

NewArtifactStoreFromConfig constructs an artifact store from an explicit SDK storage config without touching the process-wide singleton.

type AskResponse 

type AskResponse struct {
	Content     string           `json:"content"`
	Thinking    string           `json:"thinking,omitempty"`
	ToolUses    []ToolUseContent `json:"tool_uses"`
	ToolResults []CallResult     `json:"tool_results"`
	Usage       *TokenUsage      `json:"usage"`
	IsComplete  bool             `json:"is_complete"`
}

AskResponse represents the response from a single-turn query.

type CallResult 

type CallResult = contract.CallResult

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type Checkpoint 

type Checkpoint = state.Checkpoint

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type Client 

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

Client provides a high-level SDK for headless AI operations.

func NewClient 

func NewClient(config *ClientConfig) (*Client, error)

NewClient creates a new SDK client.

func (*Client) AddToolHook 

func (c *Client) AddToolHook(hook ToolHook)

AddToolHook registers a host-side tool hook on the shared orchestrator.

func (*Client) Ask 

func (c *Client) Ask(ctx context.Context, prompt string, tools []Tool) (*AskResponse, error)

Ask performs a single-turn query (convenience method).

func (*Client) AutoModeAvailable 

func (c *Client) AutoModeAvailable() bool

AutoModeAvailable reports whether the permission integrator has an AI-backed auto-mode classifier wired and ready.

func (*Client) BuildToolSurface 

func (c *Client) BuildToolSurface(ctx context.Context) (*Surface, error)

BuildToolSurface builds the current external tool surface for the client.

func (*Client) Close 

func (c *Client) Close() error

Close releases SDK-owned resources. Safe to call multiple times.

func (*Client) CreateSession 

func (c *Client) CreateSession(ctx context.Context) (*Session, error)

CreateSession creates a new session for multi-turn conversations. The session is assigned a sequential human-readable title of the form "untitled_session_N" where N is 1 + the highest N already in use.

func (*Client) CreateSessionWithAdditional 

func (c *Client) CreateSessionWithAdditional(ctx context.Context, additional map[string]any) (*Session, error)

CreateSessionWithAdditional creates a new session with pre-populated additional metadata.

func (*Client) DeleteSession 

func (c *Client) DeleteSession(sessionID SessionID) error

DeleteSession deletes a session and all associated artifacts from storage.

func (*Client) GetArtifactStore 

func (c *Client) GetArtifactStore() ArtifactStore

GetArtifactStore returns the configured SDK-visible artifact store.

func (*Client) GetMonitoring 

func (c *Client) GetMonitoring() *MonitoringSystem

GetMonitoring returns the underlying monitoring system.

func (*Client) GetSessionStore 

func (c *Client) GetSessionStore() SessionStore

GetSessionStore returns the configured SDK-visible session store.

func (*Client) HookRegistry 

func (c *Client) HookRegistry() *HookRegistry

HookRegistry returns the engine's lifecycle hook registry.

func (*Client) ListSessions 

func (c *Client) ListSessions() ([]*SessionInfo, error)

ListSessions lists all sessions.

func (*Client) LoadSession 

func (c *Client) LoadSession(ctx context.Context, sessionID SessionID) (*Session, error)

LoadSession loads an existing session.

func (*Client) LoadSessionWithAdditional 

func (c *Client) LoadSessionWithAdditional(ctx context.Context, sessionID SessionID, additional map[string]any) (*Session, error)

LoadSessionWithAdditional loads an existing session and merges additional metadata keys. Keys already present in the session are not overwritten.

func (*Client) MCPResult 

func (c *Client) MCPResult() *MCPIntegrationResult

MCPResult returns the outcome of MCP server integration.

func (*Client) MemoryInitError 

func (c *Client) MemoryInitError() error

MemoryInitError returns the error from memory service initialization, if any.

func (*Client) RegisterHook 

func (c *Client) RegisterHook(event HookEvent, handler HookHandler) string

RegisterHook registers a handler for a single lifecycle event.

func (*Client) RegisterTool 

func (c *Client) RegisterTool(tool Tool) error

RegisterTool registers a tool globally.

func (*Client) RegisterTools 

func (c *Client) RegisterTools(tools []Tool) error

RegisterTools registers multiple tools globally.

func (*Client) ReloadMCPServers 

func (c *Client) ReloadMCPServers(ctx context.Context, servers []MCPServerConfig) error

ReloadMCPServers hot-reloads MCP server integrations without restarting the client.

func (*Client) SetProgressFn 

func (c *Client) SetProgressFn(progressFn func(ToolProgress))

SetProgressFn updates the host callback for live tool execution progress.

func (*Client) SetPromptFn 

func (c *Client) SetPromptFn(promptFn PromptFn)

SetPromptFn updates the runtime prompt bridge.

func (*Client) SetResponseChunkFn 

func (c *Client) SetResponseChunkFn(chunkFn func(ResponseChunk))

SetResponseChunkFn updates the host callback for live model stream chunks.

func (*Client) SetRuntimeEventFn 

func (c *Client) SetRuntimeEventFn(runtimeEventFn func(RuntimeEvent))

SetRuntimeEventFn updates the host callback for structured runtime events.

func (*Client) SetWebSearchRunner 

func (c *Client) SetWebSearchRunner(fn websearchtool.RunnerFn)

SetWebSearchRunner installs a per-request runner on the web_search tool.

func (*Client) ToolNames 

func (c *Client) ToolNames() []string

ToolNames returns the registered primary tool names in stable order.

type ClientConfig 

type ClientConfig struct {
	APIKey         string          `json:"api_key"`
	Model          ModelIdentifier `json:"model"`
	PermissionMode PermissionMode  `json:"permission_mode"`
	MaxTurns       int             `json:"max_turns"`
	AutoCompact    bool            `json:"auto_compact"`

	// Session persistence
	PersistSessions   bool           `json:"persist_sessions"`
	SessionStorageDir string         `json:"session_storage_dir"`
	SessionSQLitePath string         `json:"session_sqlite_path"`
	SessionBackend    SessionBackend `json:"-"`
	SessionStore      SessionStore   `json:"-"`

	// MCP
	MCPServers []MCPServerConfig `json:"mcp_servers"`

	// Callbacks
	PromptFn        PromptFn            `json:"-"`
	ProgressFn      func(ToolProgress)  `json:"-"`
	ResponseChunkFn func(ResponseChunk) `json:"-"`
	RuntimeEventFn  func(RuntimeEvent)  `json:"-"`
	// OnSessionTitled is called after the engine auto-generates a title for a
	// session (once, after the first completed turn). The id is the session ID
	// and title is the short, AI-generated label. Use this to refresh the UI.
	OnSessionTitled func(id SessionID, title string) `json:"-"`

	// Filesystem
	WorkingDir string `json:"working_dir"`

	// Browser
	BrowserRemoteControlURL string `json:"browser_remote_control_url"`
	BrowserExecutablePath   string `json:"browser_executable_path"`

	// Storage
	StorageConfig       *StorageConfig `json:"-"`
	ArtifactStore       ArtifactStore  `json:"-"`
	StorageGCEnabled    bool           `json:"storage_gc_enabled"`
	StorageGCInterval   time.Duration  `json:"storage_gc_interval"`
	StorageGCLimit      int            `json:"storage_gc_limit"`
	StorageGCNamespaces []string       `json:"storage_gc_namespaces"`

	// CredentialResolver, if set, is called at client creation to resolve the
	// API key for the configured provider. Takes precedence over APIKey.
	// Use in server mode to inject per-user credentials from a database.
	CredentialResolver CredentialResolver `json:"-"`

	// Provider override
	ProviderConfig *providers.Config `json:"-"`

	// Monitoring
	Monitoring *MonitoringSystem `json:"-"`

	// Interactive prompting
	EnablePromptReaderFallback bool `json:"enable_prompt_reader_fallback"`

	// Memory
	EnableMemory   bool `json:"enable_memory"`
	MemoryFailFast bool `json:"memory_fail_fast"`

	// Feature flags
	EnableHooks            bool `json:"enable_hooks"`
	EnableMonitoring       bool `json:"enable_monitoring"`
	DisableTitleGeneration bool `json:"disable_title_generation"`

	// Model parameters
	MaxTokens               int `json:"max_tokens"`
	MaxIterations           int `json:"max_iterations"`
	TurnTokenBudget         int `json:"turn_token_budget"`
	BudgetContinuationLimit int `json:"budget_continuation_limit"`
	ContinuationNudgeLimit  int `json:"continuation_nudge_limit"`
	MaxConsecutiveDenials   int `json:"max_consecutive_denials"`

	// System prompt
	SystemPromptTemplate string        `json:"system_prompt_template"`
	PromptConfig         *PromptConfig `json:"-"`

	// Stop hooks
	StopHooks []StopHook `json:"-"`

	// PreToolHooks are shell-based hooks that fire before each tool execution.
	// Each entry is a HookConfig: {Matcher, Command, Timeout}.
	// Compatible with crush's pre_tool_use hook format:
	//   - exit 0 + no JSON → allow (no-op)
	//   - exit 0 + {"decision":"allow"} → allow + skip permission prompt
	//   - exit 0 + {"updatedInput":"..."} → rewrite tool input
	//   - exit 2 + stderr → deny with reason
	//   - exit 49 → halt entire turn
	// Set via ClientConfig.PreToolHooks or loaded automatically from
	// config.Hooks["pre_tool_use"] by newClient().
	PreToolHooks []PreToolHookConfig `json:"-"`

	// RAG / Plan / Memory
	RAGService     *RAGService    `json:"-"`
	PlanStore      PlanStore      `json:"-"`
	LongTermMemory LongTermMemory `json:"-"`

	// Document conversion
	DoclingURL string `json:"docling_url,omitempty"`

	// Automation daemon connection (seshat-automation).
	// When set, the schedule_job / list_jobs / update_job / delete_job / pause_job /
	// resume_job / run_job_now tools become functional.
	AutomationServiceURL string `json:"automation_service_url,omitempty"`
	AutomationAPIKey     string `json:"-"`

	// WebSearchKeys provides per-execution web search provider keys.
	// When set, the web_search tool uses these keys instead of reading from the
	// process environment, preventing key leakage across concurrent sessions.
	// Keys are keyed by provider name: "tavily", "exa", "jina", "langsearch".
	WebSearchKeys map[string]string `json:"-"`

	// Optional capability-specific providers for multimodal built-in tools.
	ImageGeneration *ImageGenerationConfig `json:"image_generation,omitempty"`
	TextToSpeech    *TextToSpeechConfig    `json:"text_to_speech,omitempty"`
	SpeechToText    *SpeechToTextConfig    `json:"speech_to_text,omitempty"`
}

ClientConfig represents the client configuration.

func DefaultClientConfig 

func DefaultClientConfig() *ClientConfig

DefaultClientConfig returns default client configuration.

type ContentBlock 

type ContentBlock = types.ContentBlock

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type CredentialResolver 

type CredentialResolver interface {
	ResolveAPIKey(ctx context.Context, provider string) (string, error)
}

CredentialResolver resolves the API key for an LLM provider at client creation time. The provider argument matches types.APIProvider values (e.g. "anthropic", "openai", "codex").

CLI / headless mode: not needed — the default env-var → FileStore resolution in internal/providers/auth.go applies automatically.

Server mode: implement this interface to inject per-user credentials from a database instead of relying on a single global API key.

type DenialLimitConfig 

type DenialLimitConfig = types.DenialLimitConfig

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type DenialTrackingState 

type DenialTrackingState = types.DenialTrackingState

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type EntryType 

type EntryType = types.EntryType

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type EventQueue 

type EventQueue = execution.EventQueue

SDK-owned eventing, monitoring, and MCP integration types.

type EventQueueStats 

type EventQueueStats = execution.EventQueueStats

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ExecutionMode 

type ExecutionMode = modes.ExecutionMode

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ExecutionStage 

type ExecutionStage = prompt.ExecutionStage

ExecutionStage is the re-exported execution stage type. Use the Stage* constants to specify the desired behavior overlay. 

const (
	// StageDefault is the baseline mode — no overlay injected.
	StageDefault ExecutionStage = prompt.StageDefault

	// StageToolCall tells the model it is expected to dispatch tool calls.
	StageToolCall ExecutionStage = prompt.StageToolCall

	// StageToolResult tells the model to integrate the received tool results.
	StageToolResult ExecutionStage = prompt.StageToolResult

	// StageContinuation tells the model to resume from where it stopped.
	StageContinuation ExecutionStage = prompt.StageContinuation

	// StagePlan puts the engine in plan mode: tools are shown but not executed.
	StagePlan ExecutionStage = prompt.StagePlan
)

Stage constants for use in PromptConfig.

type HookEvent 

type HookEvent = types.HookEvent

Lifecycle hooks

type HookHandler 

type HookHandler = hooks.HookHandler

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type HookProgress 

type HookProgress = types.HookProgress

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type HookRegistration 

type HookRegistration = hooks.HookRegistration

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type HookRegistry 

type HookRegistry = hooks.Registry

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type HookResult 

type HookResult = types.HookResult

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type HookState 

type HookState = hooks.HookState

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ImageContent 

type ImageContent = types.ImageContent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ImageGenerationConfig 

type ImageGenerationConfig struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	APIKey   string `json:"api_key,omitempty"`
	BaseURL  string `json:"base_url,omitempty"`
}

ImageGenerationConfig controls the generate_image built-in tool.

type LongTermMemory 

type LongTermMemory = longterm.Store

LongTermMemory — re-exported so SDK callers can inject it without importing internal/memory/longterm.

type MCPIntegrationOptions 

type MCPIntegrationOptions = mcp.IntegrationOptions

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type MCPIntegrationResult 

type MCPIntegrationResult = mcp.IntegrationResult

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type MCPServerConfig 

type MCPServerConfig = mcp.ServerConfig

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type MCPServerResult 

type MCPServerResult = mcp.ServerResult

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type MCPTransportType 

type MCPTransportType = mcp.TransportType

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type Message 

type Message = types.Message

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type MessageID 

type MessageID = types.MessageID

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ModelIdentifier 

type ModelIdentifier = types.ModelIdentifier

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type MonitoringSystem 

type MonitoringSystem = monitoring.System

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type OAuthDeviceChallenge 

type OAuthDeviceChallenge struct {
	DeviceCode              string
	UserCode                string
	VerificationURL         string
	VerificationURLComplete string
	ExpiresIn               int
	Interval                int
}

OAuthDeviceChallenge is the user-facing challenge returned by a device flow.

type OAuthDeviceFlow 

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

OAuthDeviceFlow is a reusable public wrapper around the OpenAI / Codex device flow. It can persist the resulting token and expose a resolver that plugs directly into sdk.ClientConfig.

func NewOAuthDeviceFlow 

func NewOAuthDeviceFlow(config OAuthDeviceFlowConfig) (*OAuthDeviceFlow, error)

NewOAuthDeviceFlow creates a public SDK-friendly device flow for providers backed by ChatGPT OAuth, currently codex and openai.

func (*OAuthDeviceFlow) AuthPath 

func (f *OAuthDeviceFlow) AuthPath() string

AuthPath returns the auth-store path used by the flow.

func (*OAuthDeviceFlow) CredentialResolver 

func (f *OAuthDeviceFlow) CredentialResolver() CredentialResolver

CredentialResolver returns a resolver that uses the same auth store.

func (*OAuthDeviceFlow) ResolveAccessToken 

func (f *OAuthDeviceFlow) ResolveAccessToken(ctx context.Context) (string, error)

ResolveAccessToken resolves a valid access token from the configured auth store, refreshing it when possible.

func (*OAuthDeviceFlow) SaveToken 

func (f *OAuthDeviceFlow) SaveToken(ctx context.Context, token *publicoauth.Token) error

SaveToken persists the token into the SDK auth store for this provider.

func (*OAuthDeviceFlow) Start 

func (f *OAuthDeviceFlow) Start(ctx context.Context) (*OAuthDeviceChallenge, error)

Start begins the device flow and returns the user challenge to display.

func (*OAuthDeviceFlow) Wait 

func (f *OAuthDeviceFlow) Wait(ctx context.Context, challenge *OAuthDeviceChallenge) (*publicoauth.Token, error)

Wait blocks until the device flow completes, optionally persisting the resulting token for later SDK sessions.

type OAuthDeviceFlowConfig 

type OAuthDeviceFlowConfig struct {
	Provider string
	ClientID string
	AuthPath string
	Persist  bool
}

OAuthDeviceFlowConfig configures a public device-flow login that can be used by SDK hosts to authenticate Codex / ChatGPT-backed providers without going through the CLI.

type PermissionBehavior 

type PermissionBehavior = types.PermissionBehavior

Permissions

type PermissionContext 

type PermissionContext = types.PermissionContext

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PermissionMode 

type PermissionMode = types.PermissionMode

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PermissionResult 

type PermissionResult = types.PermissionResult

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PlanRuntimeEvent 

type PlanRuntimeEvent = types.PlanRuntimeEvent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PlanStore 

type PlanStore = builtin.PlanStore

PlanStore — re-exported so SDK callers can inject it without importing internal/tools/builtin.

type PreToolHookConfig 

type PreToolHookConfig struct {
	Matcher string // regex against tool name; empty = match all
	Command string // shell command to execute
	Timeout int    // timeout in seconds (default 30)
}

PreToolHookConfig is a single shell hook that runs before a tool call.

type PromptConfig 

type PromptConfig struct {
	// SystemPrompt replaces the entire default system prompt.
	// When set, CorePromptSections and StageOverlay are not used.
	SystemPrompt *string `json:"system_prompt,omitempty"`

	// AppendSystemPrompt is appended after all other sections every turn.
	AppendSystemPrompt *string `json:"append_system_prompt,omitempty"`

	// Stage sets the execution stage context for this session.
	// The corresponding overlay is injected into the dynamic section each turn.
	//
	// Use StageDefault (the zero value) for normal operation.
	// Use StagePlan to suspend tool execution and request a plan description.
	// Use StageToolResult / StageContinuation when wiring the loop manually.
	Stage ExecutionStage `json:"stage,omitempty"`

	// StageOverrides replaces the built-in overlay text for specific stages.
	// Key: stage constant (e.g. StagePlan), Value: replacement overlay text.
	StageOverrides map[ExecutionStage]string `json:"stage_overrides,omitempty"`

	// ToolHints provides per-tool guidance appended to provider-facing descriptions.
	// This is an app-level layer: it adds guidance without modifying tool definitions.
	// Key: canonical tool name (e.g. "bash", "read"), Value: hint text.
	ToolHints map[string]string `json:"tool_hints,omitempty"`
}

PromptConfig provides structured customization of the system prompt.

It is a first-class SDK concept: apps configure it once at the client or session level, and the engine applies it every turn without modifying the core prompt sections.

Structure of the assembled system prompt: 

[CorePromptSections]        — identity, runtime_contract, working_rules, tool_use, output_discipline
[dynamic boundary]
[RuntimeContext]            — session_id, turn_number, model, available_tools, …
[RuntimeGuidance]
[MemoryContext]             — if memory is enabled
[StageOverlay]              — injected from Stage / StageOverrides when Stage != StageDefault
[AppendSystemPrompt]        — appended after all other sections

Tool definitions sent to the provider are built from the tool registry. ToolHints are appended to the provider-facing description of individual tools without requiring changes to the tool definition itself.

type PromptFn 

type PromptFn = types.PromptFn

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PromptOption 

type PromptOption = types.PromptOption

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PromptRequest 

type PromptRequest = types.PromptRequest

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type PromptResponse 

type PromptResponse = types.PromptResponse

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type RAGService 

type RAGService = rag.Service

RAGService — re-exported so SDK callers can inject it without importing internal/rag.

type ResponseChunk 

type ResponseChunk = types.APIResponseChunk

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ResponseChunkType 

type ResponseChunkType = types.APIChunkType

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type Role 

type Role = types.Role

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type RuntimeEvent 

type RuntimeEvent = types.RuntimeEvent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type RuntimeEventQueue 

type RuntimeEventQueue = execution.RuntimeEventQueue

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type RuntimeEventQueueStats 

type RuntimeEventQueueStats = execution.RuntimeEventQueueStats

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type RuntimeEventType 

type RuntimeEventType = types.RuntimeEventType

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type Session 

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

Session represents a multi-turn conversation session.

func (*Session) ClearPlanMode 

func (s *Session) ClearPlanMode()

ClearPlanMode exits plan mode in the session context, restoring the previous permission mode. This allows the host to pre-exit plan mode on user approval without the model needing to call exit_plan_mode itself.

func (*Session) Close 

func (s *Session) Close() error

func (*Session) GetEventQueue 

func (s *Session) GetEventQueue() *EventQueue

func (*Session) GetExecutionMode 

func (s *Session) GetExecutionMode() ExecutionMode

func (*Session) GetID 

func (s *Session) GetID() SessionID

func (*Session) GetMessages 

func (s *Session) GetMessages() []Message

func (*Session) GetMetadata 

func (s *Session) GetMetadata() *SessionMetadata

func (*Session) GetPermissionContext 

func (s *Session) GetPermissionContext() *PermissionContext

func (*Session) GetPermissionMode 

func (s *Session) GetPermissionMode() PermissionMode

func (*Session) GetRuntimeEventQueue 

func (s *Session) GetRuntimeEventQueue() *RuntimeEventQueue

func (*Session) GetStatus 

func (s *Session) GetStatus() SessionStatus

func (*Session) GetToolNames 

func (s *Session) GetToolNames() []string

func (*Session) GetTotalTokens 

func (s *Session) GetTotalTokens() int

func (*Session) GetTurnNumber 

func (s *Session) GetTurnNumber() int

func (*Session) Interrupt 

func (s *Session) Interrupt() error

func (*Session) RegisterTool 

func (s *Session) RegisterTool(tool Tool) error

func (*Session) SetAppendSystemPrompt 

func (s *Session) SetAppendSystemPrompt(text string)

func (*Session) SetPermissionMode 

func (s *Session) SetPermissionMode(mode PermissionMode)

func (*Session) SetProgressFn 

func (s *Session) SetProgressFn(progressFn func(ToolProgress))

func (*Session) SetResponseChunkFn 

func (s *Session) SetResponseChunkFn(chunkFn func(ResponseChunk))

func (*Session) SetRuntimeEventFn 

func (s *Session) SetRuntimeEventFn(runtimeEventFn func(RuntimeEvent))

func (*Session) SetSystemPromptTemplate 

func (s *Session) SetSystemPromptTemplate(text string)

func (*Session) SetWorkingDirectory 

func (s *Session) SetWorkingDirectory(path string)

func (*Session) SubmitMessage 

func (s *Session) SubmitMessage(ctx context.Context, content string) (*SessionResponse, error)

func (*Session) SubmitMessageWithContent 

func (s *Session) SubmitMessageWithContent(ctx context.Context, text string, images []ImageContent) (*SessionResponse, error)

func (*Session) UnregisterTool 

func (s *Session) UnregisterTool(name string) error

type SessionBackend 

type SessionBackend interface {
	SaveSession(sessionID SessionID, metadata *SessionMetadata) error
	LoadSession(sessionID SessionID) (*SessionMetadata, error)
	DeleteSession(sessionID SessionID) error
	ListSessions() ([]SessionID, error)
	AppendTranscriptEntries(sessionID SessionID, entries []TranscriptEntry) error
	ReplaceTranscript(sessionID SessionID, entries []TranscriptEntry) error
	LoadTranscript(sessionID SessionID) ([]TranscriptEntry, error)
	SaveCheckpoint(sessionID SessionID, checkpoint *Checkpoint) error
	LoadCheckpoint(sessionID SessionID) (*Checkpoint, error)
	SearchTranscriptsByContent(needle string, limit int) ([]SessionID, error)
}

SessionBackend is the SDK-owned low-level persistence backend contract. It matches the runtime's session backend responsibilities without forcing SDK consumers to depend on internal packages.

func NewFilesystemSessionBackend 

func NewFilesystemSessionBackend(baseDir string) (SessionBackend, error)

NewFilesystemSessionBackend returns a filesystem-backed session backend rooted at baseDir.

func NewMemorySessionBackend 

func NewMemorySessionBackend() SessionBackend

NewMemorySessionBackend returns an in-memory persistence backend suitable for tests or fully in-process runtimes.

func OpenSQLiteSessionBackend 

func OpenSQLiteSessionBackend(path string) (SessionBackend, error)

OpenSQLiteSessionBackend opens a SQLite-backed session backend using the shared runtime DB initialization path.

type SessionID 

type SessionID = types.SessionID

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type SessionInfo 

type SessionInfo = state.SessionInfo

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type SessionMetadata 

type SessionMetadata = types.SessionMetadata

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type SessionResponse 

type SessionResponse struct {
	Messages    []Message        `json:"messages"`
	StopReason  string           `json:"stop_reason"`
	ToolUses    []ToolUseContent `json:"tool_uses"`
	ToolResults []CallResult     `json:"tool_results"`
	Usage       *TokenUsage      `json:"usage"`
	TotalTokens int              `json:"total_tokens"`
	TurnNumber  int              `json:"turn_number"`
	IsComplete  bool             `json:"is_complete"`
	Compacted   bool             `json:"compacted,omitempty"`
}

SessionResponse represents the response from a multi-turn session.

type SessionStatus 

type SessionStatus = types.SessionStatus

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type SessionStore 

type SessionStore interface {
	SaveSession(sessionID SessionID, metadata *SessionMetadata) error
	LoadSession(sessionID SessionID) (*SessionMetadata, error)
	DeleteSession(sessionID SessionID) error
	ListSessions() ([]SessionID, error)
	AppendTranscriptEntries(sessionID SessionID, entries []TranscriptEntry) error
	ReplaceTranscript(sessionID SessionID, entries []TranscriptEntry) error
	LoadTranscript(sessionID SessionID) ([]TranscriptEntry, error)
	SaveCheckpoint(sessionID SessionID, checkpoint *Checkpoint) error
	LoadCheckpoint(sessionID SessionID) (*Checkpoint, error)
	LoadCanonicalMessages(sessionID SessionID) ([]Message, error)
	SaveCanonicalMessages(sessionID SessionID, messages []Message) error
	RestoreSessionState(sessionID SessionID) (*SessionMetadata, []Message, error)
	SaveSessionState(sessionID SessionID, metadata *SessionMetadata, previousMessages []Message, currentMessages []Message) error
	GetSessionInfo(sessionID SessionID) (*SessionInfo, error)
	GetAllSessionsInfo() ([]*SessionInfo, error)
	Close() error
}

SessionStore is the SDK-owned contract for persisted runtime sessions. It keeps callers on pkg/sdk while remaining compatible with the runtime's internal store implementations.

func NewSessionStore 

func NewSessionStore(baseDir string) (SessionStore, error)

NewSessionStore creates the default filesystem-backed session store rooted at baseDir.

func NewSessionStoreWithBackend 

func NewSessionStoreWithBackend(backend SessionBackend) (SessionStore, error)

NewSessionStoreWithBackend adapts a caller-provided backend into the SDK's public SessionStore contract.

type SpeechToTextConfig 

type SpeechToTextConfig struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	Language string `json:"language,omitempty"`
	APIKey   string `json:"api_key,omitempty"`
	BaseURL  string `json:"base_url,omitempty"`
}

SpeechToTextConfig controls the speech_to_text built-in tool.

type StopHook 

type StopHook = engine.StopHook

Stop hooks — post-turn policy hooks that can request one more loop cycle.

type StopHookInput 

type StopHookInput = engine.StopHookInput

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type StopHookResult 

type StopHookResult = engine.StopHookResult

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type StorageConfig 

type StorageConfig struct {
	Provider          StorageProviderType
	LocalPath         string
	S3Endpoint        string
	S3Bucket          string
	S3AccessKeyID     string
	S3SecretAccessKey string
	S3Region          string
	S3KeyPrefix       string
}

StorageConfig is the SDK-owned artifact storage configuration.

type StorageProviderType 

type StorageProviderType string

StorageProviderType selects the underlying artifact storage backend. 

const (
	StorageProviderLocal StorageProviderType = "local"
	StorageProviderS3    StorageProviderType = "s3"
)

type StoredCredentialResolver 

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

StoredCredentialResolver resolves provider credentials from env vars and the local auth store. It implements CredentialResolver.

func NewStoredCredentialResolver 

func NewStoredCredentialResolver(config StoredCredentialResolverConfig) *StoredCredentialResolver

NewStoredCredentialResolver creates a resolver that can inject saved API keys or refreshed OAuth access tokens into sdk.NewClient.

func (*StoredCredentialResolver) ResolveAPIKey 

func (r *StoredCredentialResolver) ResolveAPIKey(ctx context.Context, provider string) (string, error)

ResolveAPIKey implements CredentialResolver.

type StoredCredentialResolverConfig 

type StoredCredentialResolverConfig struct {
	AuthPath string
	EnvFirst bool
}

StoredCredentialResolverConfig configures an auth-store backed resolver for SDK client creation. This is the clean bridge between a host-managed login flow and sdk.NewClient.

type Surface 

type Surface = registry.Surface

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type TaskRuntimeEvent 

type TaskRuntimeEvent = types.TaskRuntimeEvent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type TextContent 

type TextContent = types.TextContent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type TextToSpeechConfig 

type TextToSpeechConfig struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	Voice    string `json:"voice,omitempty"`
	Format   string `json:"format,omitempty"`
	APIKey   string `json:"api_key,omitempty"`
	BaseURL  string `json:"base_url,omitempty"`
}

TextToSpeechConfig controls the text_to_speech built-in tool.

type ThinkingContent 

type ThinkingContent = types.ThinkingContent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type TokenUsage 

type TokenUsage = types.TokenUsage

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type Tool 

type Tool = contract.Tool

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolDefinition 

type ToolDefinition = registry.ToolDefinition

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolHook 

type ToolHook = execution.ToolHook

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolHookInput 

type ToolHookInput = execution.ToolHookInput

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolHookStage 

type ToolHookStage = execution.ToolHookStage

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolProgress 

type ToolProgress = types.ToolProgress

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolProgressStage 

type ToolProgressStage = types.ToolProgressStage

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolResultContent 

type ToolResultContent = types.ToolResultContent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type ToolUseContent 

type ToolUseContent = types.ToolUseContent

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type TranscriptEntry 

type TranscriptEntry = types.TranscriptEntry

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type TurnID 

type TurnID = types.TurnID

Public aliases keep the SDK consumable without forcing callers onto internal packages.

type WebSearchRunnerFn 

type WebSearchRunnerFn = websearchtool.RunnerFn

WebSearchRunnerFn — re-exported so the query layer can wire the DB-backed provider chain into the web_search tool without importing the tool package directly.

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.