sdk

package
v1.2.13 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2026 License: Apache-2.0 Imports: 52 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// SandboxKindLocal is the zero value — Landlock on Linux, unconfined
	// elsewhere unless RequireSandbox is also set. Today's existing behavior.
	SandboxKindLocal = sandbox.EnvironmentLocal
	// SandboxKindDocker routes bash execution through a persistent Docker
	// container (internal/sandbox.DockerExecutor) — real filesystem/process
	// isolation plus enforced CPU/memory caps and optional network isolation.
	// Falls back to SandboxKindLocal with a logged warning if Docker isn't
	// reachable when the client is constructed.
	SandboxKindDocker = sandbox.EnvironmentDocker
)

Sandbox backend kind values for ClientConfig.SandboxKind.

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"
View Source 
const RemoteExecKindRemote = sandbox.EnvironmentRemote

RemoteExecKindRemote is the Kind a RemoteExecutor implementation should report — it isn't the local host (EnvironmentLocal) or a Dagger container (EnvironmentDocker), it's an external channel back to the host app.

Variables

This section is empty.

Functions

func BuildWorkflowNodePrompt added in v1.2.0 

func BuildWorkflowNodePrompt(node WorkflowNode, inputs map[string]WorkflowNodeResult) string

func SandboxAvailable added in v0.2.3 

func SandboxAvailable() bool

SandboxAvailable reports whether an OS-level sandbox (currently: Landlock, Linux-only) is available on this host to confine bash tool execution. Host applications use this to surface the unconfined-execution tradeoff to the end user (e.g. in a settings UI) rather than leaving it as a backend-log-only warning.

func ValidateWorkflow added in v1.2.0 

func ValidateWorkflow(def WorkflowDefinition) error

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) RunWorkflow added in v1.2.0 

func (c *Client) RunWorkflow(ctx context.Context, def WorkflowDefinition, options WorkflowOptions) (WorkflowResult, error)

func (*Client) SandboxKind added in v1.2.11 

func (c *Client) SandboxKind() SandboxKind

SandboxKind reports which sandbox backend this client's bash tool actually resolved to at construction (SandboxKindDocker only if it was requested via ClientConfig.SandboxKind AND Docker passed its health check at startup; SandboxKindLocal otherwise). Host applications use this instead of the package-level SandboxAvailable(), which only ever checks Landlock and so can't reflect a Docker sandbox this specific client is actually using.

func (*Client) SearchTranscriptsByContent added in v1.0.1 

func (c *Client) SearchTranscriptsByContent(needle string, limit int) ([]SessionID, error)

SearchTranscriptsByContent lists sessions whose stored transcript contains needle.

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:"-"`
	Companion            *companion.Profile `json:"companion,omitempty"`

	// 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:"-"`

	// UserID identifies the caller for PlanStore.CreateOrUpdate (submit_plan)
	// - a host embedding this SDK for more than one user must set this per
	// request/session so plan documents get persisted against the actual
	// caller, not left unattributed. Never sent anywhere itself; only
	// threaded through to PlanStore.
	UserID string `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"`

	// RequireSandbox makes the bash tool refuse to run commands when no
	// OS-level sandbox (currently: Landlock, Linux-only) is available on the
	// host, instead of silently falling back to unconfined execution. Leave
	// false for desktop use where refusing to run bash entirely is worse UX
	// than a visible unsandboxed-execution warning; set true for multi-tenant
	// server deployments where unconfined execution must never happen.
	RequireSandbox bool `json:"require_sandbox"`

	// SandboxKind selects the OS-level sandbox backend for bash tool
	// execution. Empty (SandboxKindLocal) preserves existing behavior.
	// SandboxKindDocker routes execution through a persistent Docker
	// container — see SandboxDocker.
	SandboxKind SandboxKind `json:"sandbox_kind,omitempty"`
	// SandboxDocker configures the Docker sandbox backend when SandboxKind
	// is SandboxKindDocker. Zero value uses sane, security-conscious
	// defaults (see sandbox.DefaultDockerConfig).
	SandboxDocker SandboxDockerConfig `json:"-"`
}

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 RemoteExecKind added in v0.2.3 

type RemoteExecKind = sandbox.EnvironmentKind

RemoteExecKind identifies a RemoteExecutor backend (RemoteExecutor.Kind).

type RemoteExecRequest added in v0.2.3 

type RemoteExecRequest = sandbox.RunRequest

RemoteExecRequest is the input to a RemoteExecutor.Run call.

type RemoteExecResult added in v0.2.3 

type RemoteExecResult = sandbox.RunResult

RemoteExecResult is the output of a RemoteExecutor.Run call.

type RemoteExecutor added in v0.2.3 

type RemoteExecutor = sandbox.Executor

RemoteExecutor lets a host application (e.g. seshat-backend, driven by Electron's terminal relay) route a session's bash-tool execution through an external channel instead of the engine's own local subprocess — see Session.SetRemoteExecutor. Implementations satisfy internal/sandbox.Executor; this alias is the exported SDK surface for it.

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 SandboxDockerConfig added in v0.2.3 

type SandboxDockerConfig = sandbox.DockerExecutorConfig

SandboxDockerConfig configures the Docker sandbox backend used when ClientConfig.SandboxKind is SandboxKindDocker. See sandbox.DockerExecutorConfig for field-by-field documentation.

type SandboxKind added in v0.2.3 

type SandboxKind = sandbox.EnvironmentKind

SandboxKind selects an OS-level sandbox backend for bash tool execution.

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) ClearRemoteExecutor added in v0.2.3 

func (s *Session) ClearRemoteExecutor()

ClearRemoteExecutor detaches this session's remote execution backend — subsequent bash-tool calls fall back to local execution.

func (*Session) Close 

func (s *Session) Close() error

func (*Session) ForcePlanMode added in v0.2.3 

func (s *Session) ForcePlanMode()

ForcePlanMode enters plan mode in the session context directly, allowing the host to force a session into plan mode without waiting for the model to call enter_plan_mode itself.

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) SetRemoteExecutor added in v0.2.3 

func (s *Session) SetRemoteExecutor(executor RemoteExecutor)

SetRemoteExecutor registers executor as this session's remote execution backend — subsequent bash-tool calls in this session run through it instead of a local subprocess (see bash.Tool.executeCommand). A re-registration replaces any previous executor for the session.

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)
	SearchTranscriptsByContent(needle string, limit int) ([]SessionID, error)
	SaveCheckpoint(sessionID SessionID, checkpoint *Checkpoint) error
	LoadCheckpoint(sessionID SessionID) (*Checkpoint, 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)
	SearchTranscriptsByContent(needle string, limit int) ([]SessionID, 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 TranscribeOption added in v0.2.3 

type TranscribeOption func(*transcribeConfig)

TranscribeOption configures an optional TranscribeAudio setting.

func WithTranscribeBaseURL added in v0.2.3 

func WithTranscribeBaseURL(baseURL string) TranscribeOption

WithTranscribeBaseURL overrides the API base URL (default OpenAI's), mainly for tests.

func WithTranscribeLanguage added in v0.2.3 

func WithTranscribeLanguage(language string) TranscribeOption

WithTranscribeLanguage hints the spoken language as an IETF tag (e.g. "en"); omit to auto-detect.

func WithTranscribeModel added in v0.2.3 

func WithTranscribeModel(model string) TranscribeOption

WithTranscribeModel overrides the Whisper model (default "whisper-1").

type TranscriptEntry 

type TranscriptEntry = types.TranscriptEntry

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

type TranscriptionResult added in v0.2.3 

type TranscriptionResult = stt.Response

TranscriptionResult mirrors internal/audio/stt.Response — re-exported so hosts outside this module (which cannot import internal/ packages) can name the return type of TranscribeAudio.

func TranscribeAudio added in v0.2.3 

func TranscribeAudio(ctx context.Context, apiKey string, audioData []byte, opts ...TranscribeOption) (*TranscriptionResult, error)

TranscribeAudio performs a one-off speech-to-text transcription using OpenAI's Whisper API, independent of any chat session. Use this when a host needs raw audio-to-text directly (e.g. a voice-input control in its own UI) rather than the agent-facing speech_to_text tool, which only runs when the model itself decides to call it mid-turn.

audioData may be MP3, MP4, MPEG, MPGA, M4A, WAV, or WebM.

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.

type WorkflowDefinition added in v1.2.0 

type WorkflowDefinition = workflow.Definition

func LoadWorkflowFile added in v1.2.0 

func LoadWorkflowFile(path string) (WorkflowDefinition, error)

type WorkflowDraftOptions added in v1.2.0 

type WorkflowDraftOptions = workflow.DraftOptions

type WorkflowDraftResult added in v1.2.0 

type WorkflowDraftResult = workflow.DraftResult

func DraftWorkflow added in v1.2.0 

func DraftWorkflow(options WorkflowDraftOptions) (WorkflowDraftResult, error)

type WorkflowNode added in v1.2.0 

type WorkflowNode = workflow.Node

type WorkflowNodeResult added in v1.2.0 

type WorkflowNodeResult = workflow.NodeResult

type WorkflowOptions added in v1.2.0 

type WorkflowOptions struct {
	MaxParallel int
	Tools       []Tool
	Executor    workflow.Executor
}

type WorkflowResult added in v1.2.0 

type WorkflowResult = workflow.Result

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.