sdk

type APIProvider = types.APIProvider

type ArtifactGCOptions = storage.GCOptions

type ArtifactGCReport = storage.GCReport

type ArtifactListOptions = storage.ListOptions

type ArtifactMetadata = storage.ArtifactMetadata

type ArtifactNamespace = storage.ArtifactNamespace

type ArtifactPutRequest = storage.ArtifactPutRequest

type ArtifactRef = storage.ArtifactRef

type ArtifactRetentionClass = storage.ArtifactRetentionClass

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)
}

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"`
}

type CallResult = contract.CallResult

type Checkpoint = state.Checkpoint

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

type ClientConfig struct {
	APIKey     string          `json:"api_key"`
	Model      ModelIdentifier `json:"model"`
	TitleModel ModelIdentifier `json:"title_model,omitempty"`
	// CompactSummaryModel overrides which model generates compaction summaries.
	// Zero value means "use Model" (the session's own model), so compaction
	// works on any provider without needing an Anthropic key.
	CompactSummaryModel ModelIdentifier `json:"compact_summary_model,omitempty"`

	// TrustProjectInstructions gates SESHAT.md/AGENTS.md/.seshat/instructions.md
	// found in WorkingDir behind project trust before they are injected into
	// the system prompt (see docs/project-trust.md). It is called with the
	// file's exact path and content; return true to trust and inject it. nil
	// fails closed - no project you didn't write or explicitly trust can put
	// its own instructions in the model's prompt. A host that already trusts
	// projects for other configuration (the terminal interface's `seshat
	// trust`) should wire this to the same hash-based check.
	TrustProjectInstructions func(path string, content []byte) bool `json:"-"`
	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"`
	// BrowserSessionTargetResolver, when set, lets a caller (the desktop app)
	// attach a session's browser tool calls directly to an existing CDP tab
	// it already shows live to the user, instead of opening an invisible
	// incognito context - see internal/web/browser.Config.TargetResolver for
	// the full rationale. Optional; nil preserves the default behavior.
	BrowserSessionTargetResolver func(ctx context.Context, sessionID SessionID) (targetID string, ok bool) `json:"-"`

	// 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:"-"`
	// TitleProviderConfig overrides the provider client used only for automatic
	// session title generation. This allows a tiny local/Hugging Face-served
	// model to title chats while the main chat model stays unchanged.
	TitleProviderConfig *providers.Config `json:"-"`
	// TitleGenerator takes precedence over TitleProviderConfig/TitleModel.
	// Use this for local, no-server title models.
	TitleGenerator TitleGenerator `json:"-"`
	// LocalTitle configures the default local title generator. It is ignored
	// when TitleGenerator is set.
	LocalTitle *LocalTitleConfig `json:"local_title,omitempty"`

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

	// ManagedPolicy is what the organization that runs the host imposes on every agent: a text to
	// follow and tools never to use. Set it from an administrator's configuration, not from the end
	// user's. See ManagedPolicy.
	ManagedPolicy *ManagedPolicy `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:"-"`

	// 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
	// DocumentReaderURL is the base URL of a document-reader service. Used
	// to build the default DocumentConverter when that field is left nil.
	DocumentReaderURL string `json:"document_reader_url,omitempty"`

	// DocumentConverter, when set, is used instead of building a
	// service client from DocumentReaderURL. Inject a custom converter
	// implementation (local native reader, seshat-intelligence, marker, etc.)
	// to back the SDK's document-conversion tools. Takes precedence over
	// DocumentReaderURL.
	DocumentConverter documentreader.Converter `json:"-"`

	// DocumentPageRenderer, when set, backs render_document_page so agents can
	// inspect visual pages with a multimodal model after markdown extraction.
	DocumentPageRenderer pdfsmart.PageRenderer `json:"-"`

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

	// ResearchKeys provides per-execution credentials for the research tools: reddit_client_id,
	// reddit_client_secret, youtube_api_key, google_places_api_key, trustpilot_api_key. When set, only
	// these are used and the process environment is not read, preventing key leakage across concurrent
	// sessions of a shared server. Without them the environment variables of the same names (upper case)
	// are used, which suits a single-user host. A research tool without its keys is not offered to the model.
	ResearchKeys 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:"-"`

	// EnableToolSearch keeps deferred tools (MCP tools, and any built-in
	// tool registering with ShouldDefer, e.g. skill) out of the model's
	// initial tool list - the model calls the tool_search tool to discover
	// and use them instead. False (the default) leaves the
	// ENABLE_TOOL_SEARCH environment variable as the decider (so existing
	// deployments setting it keep working); true enables it regardless of
	// that variable. There is no way to force it off through this field
	// alone if the environment variable is also set - unset that variable
	// too for a host that wants this field to be the single source of truth.
	EnableToolSearch bool `json:"enable_tool_search,omitempty"`
}

type CompactionRuntimeEvent = types.CompactionRuntimeEvent

type ContentBlock = types.ContentBlock

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

type DenialLimitConfig = types.DenialLimitConfig

type DenialTrackingState = types.DenialTrackingState

type EntryType = types.EntryType

type EventQueue = execution.EventQueue

type EventQueueStats = execution.EventQueueStats

type ExecutionMode = modes.ExecutionMode

type ExecutionStage = prompt.ExecutionStage

type HookEvent = types.HookEvent

type HookHandler = hooks.HookHandler

type HookProgress = types.HookProgress

type HookRegistration = hooks.HookRegistration

type HookRegistry = hooks.Registry

type HookResult = types.HookResult

type HookState = hooks.HookState

type ImageContent = types.ImageContent

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"`
}

type LocalTitleConfig struct {
	Enabled        bool          `json:"enabled,omitempty"`
	Runtime        string        `json:"runtime,omitempty"`
	ExecutablePath string        `json:"executable_path,omitempty"`
	ModelPath      string        `json:"model_path,omitempty"`
	HFRepo         string        `json:"hf_repo,omitempty"`
	HFFile         string        `json:"hf_file,omitempty"`
	CacheDir       string        `json:"cache_dir,omitempty"`
	Args           []string      `json:"args,omitempty"`
	Timeout        time.Duration `json:"timeout,omitempty"`
}

type LongTermMemory = longterm.Store

type MCPIntegrationOptions = mcp.IntegrationOptions

type MCPIntegrationResult = mcp.IntegrationResult

type MCPServerConfig = mcp.ServerConfig

type MCPServerResult = mcp.ServerResult

type MCPTransportType = mcp.TransportType

type ManagedPolicy struct {
	// Instructions is the text every agent must follow, appended to its system prompt.
	Instructions string `json:"instructions,omitempty"`

	// ForbiddenTools lists tool names that no agent may use. A name matches the tool and its
	// aliases; an MCP tool is named like "mcp__server__tool".
	ForbiddenTools []string `json:"forbidden_tools,omitempty"`
}

type Message = types.Message

type MessageID = types.MessageID

type ModelIdentifier = types.ModelIdentifier

type MonitoringSystem = monitoring.System

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

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

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

type PermissionBehavior = types.PermissionBehavior

type PermissionContext = types.PermissionContext

type PermissionMode = types.PermissionMode

type PermissionResult = types.PermissionResult

type PlanRuntimeEvent = types.PlanRuntimeEvent

type PlanStore = builtin.PlanStore

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)
}

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"`
}

type PromptFn = types.PromptFn

type PromptOption = types.PromptOption

type PromptRequest = types.PromptRequest

type PromptResponse = types.PromptResponse

type RAGService = rag.Service

type RemoteExecKind = sandbox.EnvironmentKind

type RemoteExecRequest = sandbox.RunRequest

type RemoteExecResult = sandbox.RunResult

type RemoteExecutor = sandbox.Executor

type ResponseChunk = types.APIResponseChunk

type ResponseChunkType = types.APIChunkType

type Role = types.Role

type RuntimeEvent = types.RuntimeEvent

type RuntimeEventQueue = execution.RuntimeEventQueue

type RuntimeEventQueueStats = execution.RuntimeEventQueueStats

type RuntimeEventType = types.RuntimeEventType

type SandboxDockerConfig = sandbox.DockerExecutorConfig

type SandboxKind = sandbox.EnvironmentKind

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

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)
}

type SessionID = types.SessionID

type SessionInfo = state.SessionInfo

type SessionMetadata = types.SessionMetadata

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"`
	CompactPreTokens  int              `json:"compact_pre_tokens,omitempty"`
	CompactPostTokens int              `json:"compact_post_tokens,omitempty"`
}

type SessionStatus = types.SessionStatus

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
}

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"`
}

type StageRuntimeEvent = types.StageRuntimeEvent

type StopHook = engine.StopHook

type StopHookInput = engine.StopHookInput

type StopHookResult = engine.StopHookResult

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

type StorageProviderType string

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

type StoredCredentialResolverConfig struct {
	AuthPath string
	EnvFirst bool
}

type Surface = registry.Surface

type TaskRuntimeEvent = types.TaskRuntimeEvent

type TextContent = types.TextContent

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"`
}

type ThinkingContent = types.ThinkingContent

type TitleGenerator interface {
	GenerateTitle(ctx context.Context, firstUserMsg string) (string, error)
}

type TokenUsage = types.TokenUsage

type Tool = contract.Tool

type ToolDefinition = registry.ToolDefinition

type ToolHook = execution.ToolHook

type ToolHookInput = execution.ToolHookInput

type ToolHookResult = execution.ToolHookResult

type ToolHookStage = execution.ToolHookStage

type ToolHookStop = execution.ToolHookStop

type ToolProgress = types.ToolProgress

type ToolProgressStage = types.ToolProgressStage

type ToolResultContent = types.ToolResultContent

type ToolUseContent = types.ToolUseContent

type TranscribeOption func(*transcribeConfig)

type TranscriptEntry = types.TranscriptEntry

type TranscriptionResult = stt.Response

type TurnID = types.TurnID

type WebSearchRunnerFn = websearchtool.RunnerFn

type WorkflowDefinition = workflow.Definition

type WorkflowDraftOptions = workflow.DraftOptions

type WorkflowDraftResult = workflow.DraftResult

type WorkflowNode = workflow.Node

type WorkflowNodeResult = workflow.NodeResult

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

type WorkflowResult = workflow.Result