agent

package
v0.67.0 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: AGPL-3.0 Imports: 54 Imported by: 0

Documentation

Overview

Package agent runs Stella's agents: the pool of live agent services, the session registry, the runner factory, and the per-agent Settings policy that decides which management tools a turn may reach.

Index

Constants

View Source 
const (
	ToolOverrideScopeSystem      = "system"
	ToolOverrideScopeSystemAgent = "system_agent"
	ToolOverrideScopeUser        = "user"
	ToolOverrideScopeUserAgent   = "user_agent"

	ToolOverrideOriginDefault = "default"
)
View Source 
const SettingsAgentToolPrefix = "settings_agent"

SettingsAgentToolPrefix is the family every generated settings_agent tool name starts with.

View Source 
const SettingsAgentToolToolPrefix = "settings_agent_tool"

SettingsAgentToolToolPrefix is the family every generated settings_agent_tool tool name starts with.

View Source 
const ToolOverrideAbsentVersion = "absent"

ToolOverrideAbsentVersion is the only version accepted when creating an exact override row. It makes a first write conditional without inventing a row to version before the user has chosen an override.

Variables

View Source 
var (
	// ErrProjectNotFound is the opaque "not found" for a missing project, a
	// project owned by another user, or one bound to a different route agent (a
	// route-agent mismatch never confirms the project exists).
	ErrProjectNotFound = errors.New("project not found")
	// ErrInvalidBaseDir reports a base_dir that escapes the agent workspace (400).
	ErrInvalidBaseDir = errors.New("invalid base_dir")
)

Project use-case errors. Agent-gate denials propagate the agentaccess sentinels unchanged.

View Source 
var ErrChatTimeout = agenterr.ErrChatTimeout

ErrChatTimeout is returned when the main agent chat exceeds its wall-clock timeout.

View Source 
var ErrGroupCompactionUnsupported = errors.New("compaction is not supported for group sessions")

ErrGroupCompactionUnsupported is returned by CompactSession for a group session. Group history lives in the group event log, not the LCM conversation, so LCM compaction does not apply; callers surface this as a user-facing notice rather than silently compacting an event-log conversation.

View Source 
var MessageText = agentruntime.MessageText

MessageText extracts and joins all text from a MessageContent.

Functions

func BuildGroupSessionKey added in v0.42.0 

func BuildGroupSessionKey(agentID, groupID string) string

BuildGroupSessionKey constructs a session key for a group chat. All participants in the same group share one session per agent. Format: {agentID}:group:{groupID}

func BuildSessionKey 

func BuildSessionKey(agentID, platform, externalUserID, channelContext string) string

BuildSessionKey constructs a session key from agent, platform, user, and context. Format: {agentID}:{platform}:{externalUserID}:{channelContext}

func BuildUserSessionKey 

func BuildUserSessionKey(agentID string, authUserID string, channelContext string) string

BuildUserSessionKey constructs a session key for a linked auth user. Linked users share a single session across all channels (for the same agent and channel context), so the key omits the platform-specific external ID. Format: {agentID}:user:{authUserID}:{channelContext}

func BuiltinToolAvailable added in v0.60.0 

func BuiltinToolAvailable(_ context.Context, params RunnerParams) (bool, error)

func ChannelFromContext 

func ChannelFromContext(ctx context.Context) (string, bool)

ChannelFromContext returns the current chat channel when present.

func ExcludedToolsFromContext 

func ExcludedToolsFromContext(ctx context.Context) []string

ExcludedToolsFromContext returns the per-run excluded tool names when present.

func FilterToolEnabled added in v0.60.0 

func FilterToolEnabled(defaultEnabled bool, toolName string, rows []ToolOverride) bool

func IsCoreToolName added in v0.60.0 

func IsCoreToolName(name string) bool

func SettingsAgentDispatch added in v0.66.0 

func SettingsAgentDispatch(ctx context.Context, h SettingsAgentHandler, action string, args map[string]any) (any, error)

func SettingsAgentToolDispatch added in v0.66.0 

func SettingsAgentToolDispatch(ctx context.Context, h SettingsAgentToolHandler, action string, args map[string]any) (any, error)

func SettingsAgentToolNames added in v0.66.0 

func SettingsAgentToolNames() []string

SettingsAgentToolNames lists every generated tool name, for callers that gate on names.

func SettingsAgentToolToolNames added in v0.66.0 

func SettingsAgentToolToolNames() []string

SettingsAgentToolToolNames lists every generated tool name, for callers that gate on names.

func SystemOverrideFromContext 

func SystemOverrideFromContext(ctx context.Context) (string, bool)

SystemOverrideFromContext returns the per-run system prompt override when present.

func ValidateProjectDir added in v0.34.0 

func ValidateProjectDir(baseDir, userRoot string) error

ValidateProjectDir checks that baseDir is a safe subpath of userRoot. It rejects paths containing ".." traversal or paths outside the workspace.

func WithChannel 

func WithChannel(ctx context.Context, channel string) context.Context

WithChannel returns a child context that carries the current chat channel.

func WithExcludedTools 

func WithExcludedTools(ctx context.Context, names ...string) context.Context

WithExcludedTools returns a child context that hides the named tools for a single run.

func WithSystemOverride 

func WithSystemOverride(ctx context.Context, system string) context.Context

WithSystemOverride returns a child context that carries a per-run system prompt override.

Types

type AgentActivityStore added in v0.60.0 

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

AgentActivityStore is the conversation-activity read model backing the Agent management service: it reports the last-active time per agent for one user's own conversations. It owns the sqlc row and nullable-time decoding so the transport receives only a domain map.

func NewAgentActivityStore added in v0.60.0 

func NewAgentActivityStore(db *pgxpool.Pool) *AgentActivityStore

NewAgentActivityStore builds the read model over the given pool.

func (*AgentActivityStore) ListAgentLastActive added in v0.60.0 

func (s *AgentActivityStore) ListAgentLastActive(ctx context.Context, userID string) (map[string]time.Time, error)

ListAgentLastActive returns agentID -> last-active UTC time for the user's conversations. Rows without a valid agent id or a zero/absent timestamp are omitted, so a caller can treat a missing key as "no activity".

type AuthorizedProjectSnapshot added in v0.64.0 

type AuthorizedProjectSnapshot struct {
	Descriptor ProjectDescriptor
	Context    prompt.ProjectContext
	Skills     *skill.ProjectSnapshot
}

AuthorizedProjectSnapshot is an immutable project generation used by prompt construction. Descriptor, context, and Skills come from one resolution and one read-only root capability, which is closed before downstream plugin work.

func SnapshotAuthorizedProject added in v0.64.0 

func SnapshotAuthorizedProject(ctx context.Context, resolve ProjectResolverFunc, opener home.RootOpener, projectID, userID, agentID string) (snapshot AuthorizedProjectSnapshot, resultErr error)

SnapshotAuthorizedProject resolves the exact owner tuple once and snapshots all project prompt inputs while one read-only owner gate is held. The named return and deferred errors.Join close the root on ordinary errors and panics.

type BeforeRunBuilder 

type BeforeRunBuilder func(ctx context.Context, build pkgplugins.BeforeRunContext) (pkgplugins.BeforeRunResult, error)

type BuiltinTool added in v0.60.0 

type BuiltinTool struct {
	Tool  tools.Tool
	Build func(pkgplugins.ToolBuildContext) (tools.Tool, error)
	Spec  tools.Definition
	// UnavailableReason is backend-owned metadata for a known unavailable
	// state. It is exposed only after Available returns false, never inferred
	// from a tool name by a client.
	UnavailableReason ToolUnavailableReason
	// Available reports whether this tool belongs in the runner's registry for
	// the given run. An error means the answer is unknown; callers must fail the
	// build instead of guessing, so a transient dependency outage can never be
	// cached as either a missing capability or a wrongly granted one.
	Available func(context.Context, RunnerParams) (bool, error)
}

func (BuiltinTool) Definition added in v0.66.0 

func (b BuiltinTool) Definition() (tools.Definition, bool)

type ChatChannelRequest added in v0.61.0 

type ChatChannelRequest struct {
	Authority authz.Authority
	// UserID owns the session. For a group chat the caller may leave it empty:
	// the group-ownership invariant (UserID == GroupID) is established here.
	UserID  string
	GroupID string
	// GuestID is the durable channel_guest UUID. When set it owns the session.
	GuestID string
	AgentID string
	Channel session.Channel
	// SessionKey is the chat's derived key. Sessions are no longer created under
	// it; it is kept as the legacy lookup for chats pinned to it before the
	// binding existed.
	SessionKey string
}

ChatChannelRequest identifies the durable binding of a channel chat: the chat itself rather than one of the sessions it has run through. A group binds on its owning group, a private chat channel on user + channel; either way the binding survives `/new` rotating the chat onto a fresh session.

type ChatRequest added in v0.40.0 

type ChatRequest struct {
	SessionID string
	UserID    string
	AgentID   string
	ProjectID string
	Channel   session.Channel
	// TelemetryChannel is the low-cardinality transport name. BindingID keeps
	// the durable routing key separate from observability dimensions.
	TelemetryChannel string
	BindingID        string
	// Kind overrides the default session kind (KindChat). Used by non-chat
	// callers such as the scheduler (KindScheduler).
	Kind    session.Kind
	GroupID string // non-empty for group sessions; overlaid onto session.Info after Ensure
	GuestID string // durable channel_guest UUID; runtime restriction plumbing
	Message MessageContent
	Model   string
	// CurrentSpeaker is the human speaking this group turn. Personalization
	// target only (D9): forwarded to the runtime as WithCurrentSpeaker, never
	// used as the session/runtime UserID. Zero value for DM turns.
	CurrentSpeaker memory.CurrentSpeaker
	// GroupWake is why this group turn is running (triage outcome, HOLD
	// recovery). Per-turn model context only; never persisted.
	GroupWake memory.GroupWake
	// InputActor overrides derived provenance for trusted system coordination
	// messages. GroupAgent authority still confines execution to the group.
	InputActor eventlog.MessageActor
	// RuntimeOpts are forwarded verbatim to Runtime.Chat.
	RuntimeOpts []agentruntime.Option
	// Authority is the trusted capability for resolving/using this session. It is
	// minted by the entry adapter from persisted identity, never from model text.
	Authority authz.Authority
}

ChatRequest describes a foreground chat turn.

type CompactionConfig 

type CompactionConfig struct {
	// MaxTokens triggers compaction when the estimated token count exceeds this.
	// 0 (or omitted) uses the default of 80000. Negative values disable
	// automatic compaction. Manual /compact still works.
	MaxTokens int `yaml:"max_tokens"`
	// KeepTail is the number of recent user turns to preserve verbatim
	// after compaction. Default: 6.
	KeepTail int `yaml:"keep_tail"`
}

CompactionConfig controls automatic session compaction.

func (CompactionConfig) WithDefaults 

func (c CompactionConfig) WithDefaults() CompactionConfig

WithDefaults returns a copy with zero-value fields replaced by defaults. MaxTokens 0 -> 80000; negative values are preserved (meaning disabled).

type DelegateRequest added in v0.40.0 

type DelegateRequest struct {
	// SessionID, when non-empty, resumes an existing delegate session.
	// When empty, a new delegate session is created.
	SessionID     string
	UserID        string
	AgentID       string
	ProjectID     string
	Task          string
	System        string
	Model         string
	ExcludedTools []string
	Authority     authz.Authority
}

DelegateRequest describes a delegate session turn.

type DelegateResult added in v0.40.0 

type DelegateResult struct {
	SessionID       string
	Output          string
	OutputTruncated bool
	Complete        bool
}

DelegateResult is the output of a delegate turn.

type Event 

type Event = agentruntime.Event

Event is the consumer-facing stream event.

type FileEvent 

type FileEvent = agentruntime.FileEvent

FileEvent carries a local file path to be sent to the channel.

type ImageEvent 

type ImageEvent = agentruntime.ImageEvent

ImageEvent carries a base64-encoded image to be sent to the channel.

type MCPToolProvider added in v0.60.0 

type MCPToolProvider interface {
	ToolsForContext(ctx context.Context, userID, agentID string) []tools.Tool
}

MCPToolProvider surfaces external MCP-server tools into an agent's tool registry for a (user, agent) context. Implemented by *mcp.ToolProvider; kept as an interface here so the agent package need not depend on the MCP client internals and tests can stub it.

type ManagementTool added in v0.66.0 

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

ManagementTool is one exact Agent or Agent-tool-override action. It is kept separate from the runtime's ordinary AgentActor tools: Settings require the fresh direct-human Authority installed only for an admitted Stella turn.

func NewManagementTool added in v0.66.0 

func NewManagementTool(spec SettingsAgentActionTool, management func() *agentaccess.Management) *ManagementTool

func NewToolOverrideManagementTool added in v0.66.0 

func NewToolOverrideManagementTool(spec SettingsAgentToolActionTool, management func() *agentaccess.Management, overrides *ToolOverrideStore, registry func() *toolmeta.Registry) *ManagementTool

func (*ManagementTool) Definition added in v0.66.0 

func (t *ManagementTool) Definition() tools.Definition

func (*ManagementTool) Execute added in v0.66.0 

func (t *ManagementTool) Execute(ctx context.Context, args map[string]any) (string, error)

type MessageContent 

type MessageContent = agentruntime.MessageContent

MessageContent is the type for user messages passed through the runner pipeline. It is either string (text-only) or []ai.ContentBlock (multimodal).

type NewRunnerFunc 

type NewRunnerFunc = agentruntime.NewRunnerFunc

NewRunnerFunc creates a new Runner with the given params.

type PluginHooksBuilder 

type PluginHooksBuilder func(ctx context.Context) []hooks.HookPlugin

PluginHooksBuilder creates hook plugins from enabled plugin state.

type PluginToolsBuilder 

type PluginToolsBuilder func(ctx context.Context, build pkgplugins.ToolBuildContext) []tools.Tool

PluginToolsBuilder creates tools from enabled plugin state.

type PoolManager 

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

PoolManager manages one Service per enabled agent. It reads enabled agents from the config Store and creates a Service (session.Registry + runtime.Runtime) per agent.

func NewPoolManager 

func NewPoolManager(store config.Store, mem memory.Provider, opts ...PoolManagerOption) *PoolManager

func (*PoolManager) AcquireHomeOwnerFence added in v0.64.0 

func (pm *PoolManager) AcquireHomeOwnerFence(ctx context.Context, kind home.OwnerKind, ownerID string) (home.OwnerFenceLease, error)

AcquireHomeOwnerFence closes matching cached execution while retaining process-local lifecycle exclusion through the caller's database commit. Home owner gates are acquired by the caller after this lease, preserving the fixed lifecycle -> Home process gate -> PostgreSQL lock order.

func (*PoolManager) AddBuiltinTool 

func (pm *PoolManager) AddBuiltinTool(_ context.Context, tool tools.Tool) error

AddBuiltinTool appends a builtin tool before StartAll. It is a one-shot pre-start bind: it rejects a nil tool, a duplicate tool name, and any add after StartAll (post-start rejection), since the builtin-tool set is sealed once agents start. Runtime tool changes go through the plugin-tool path (pluginToolsBuilder / ReloadPluginTools), not here.

func (*PoolManager) ApplyAgentSkillPolicyMutation added in v0.64.0 

func (pm *PoolManager) ApplyAgentSkillPolicyMutation(agentID string, mutate func() error) error

ApplyAgentSkillPolicyMutation commits mutate and makes every locally published Service observe that committed policy before a subsequent turn can use its old factory. It owns the complete orchestration so callers cannot accidentally call a barrier-assuming invalidator without the barrier.

A refresh failure is deliberately logged but not returned after mutate has committed: the database response remains truthful while the target Service is poisoned fail-closed until a later successful refresh.

func (*PoolManager) BindMCPToolProvider added in v0.60.0 

func (pm *PoolManager) BindMCPToolProvider(p MCPToolProvider) error

BindMCPToolProvider binds the MCP tool provider before StartAll. One-shot pre-start bind: rejects nil (missing), a second bind (duplicate), and any bind after StartAll (late). No runner rebuild is needed because agents have not yet started.

func (*PoolManager) BindOAuthRegistry added in v0.60.0 

func (pm *PoolManager) BindOAuthRegistry(r *oauth.ProviderRegistry) error

BindOAuthRegistry binds the OAuth provider registry before StartAll. It is a one-shot pre-start bind: it rejects a nil registry (missing), a second bind (duplicate), and any bind after StartAll (late).

func (*PoolManager) BindSessionAccess added in v0.60.0 

func (pm *PoolManager) BindSessionAccess(access SessionAccessService) error

BindSessionAccess binds the shared Session PEP before StartAll. All non-HTTP entry session lifecycle in Service goes through this port.

func (*PoolManager) BindVaultEnvLoader added in v0.60.0 

func (pm *PoolManager) BindVaultEnvLoader(v sandbox.VaultEnvLoader) error

BindVaultEnvLoader binds the sandbox vault env loader (and the derived OAuth token manager) before StartAll. One-shot pre-start bind: rejects nil (missing), a second bind (duplicate), and any bind after StartAll (late). Because it runs before agents start, no runner rebuild is needed.

func (*PoolManager) Close 

func (pm *PoolManager) Close() error

Close shuts down all services and hook plugins.

func (*PoolManager) Default added in v0.40.0 

func (pm *PoolManager) Default() *Service

Default returns any service (first found).

func (*PoolManager) GetService added in v0.40.0 

func (pm *PoolManager) GetService(agentID string) *Service

GetService returns the Service for the given agent ID, or nil if not found.

func (*PoolManager) HookPlugins 

func (pm *PoolManager) HookPlugins() []hooks.HookPlugin

HookPlugins returns a snapshot of the active hook plugins: the reloadable user plugins plus the stable core hooks. Ordering is irrelevant — NewHookSet sorts by Priority — so core hooks are simply appended.

func (*PoolManager) InvalidateAgent added in v0.48.0 

func (pm *PoolManager) InvalidateAgent(agentID string) error

InvalidateAgent closes all live runners for one agent across every user.

func (*PoolManager) InvalidateAll added in v0.48.0 

func (pm *PoolManager) InvalidateAll() error

InvalidateAll closes every live runner across all services.

func (*PoolManager) InvalidateUser 

func (pm *PoolManager) InvalidateUser(userID string) error

InvalidateUser closes all live runners for userID across all services.

func (*PoolManager) InvalidateUserAgent added in v0.60.0 

func (pm *PoolManager) InvalidateUserAgent(userID, agentID string) error

InvalidateUserAgent closes live runners for one user on one agent.

func (*PoolManager) ReloadModelDefaults added in v0.66.0 

func (pm *PoolManager) ReloadModelDefaults(ctx context.Context) error

ReloadModelDefaults rebuilds every runner factory from a fresh snapshot so newly admitted runners see the current deployment-wide default models. Every agent is rebuilt, not just the ones with no override: an agent inherits field by field, so a default change can move a single tier under an otherwise fully-configured agent.

func (*PoolManager) ReloadPluginHooks 

func (pm *PoolManager) ReloadPluginHooks(ctx context.Context) error

ReloadPluginHooks rebuilds the hook plugin set and propagates to every service.

func (*PoolManager) ReloadPluginProviders 

func (pm *PoolManager) ReloadPluginProviders(ctx context.Context) error

ReloadPluginProviders rebuilds the runner factory for every service.

func (*PoolManager) ReloadPluginTools 

func (pm *PoolManager) ReloadPluginTools(ctx context.Context) error

ReloadPluginTools rebuilds the runner factory for every service.

func (*PoolManager) StartAll 

func (pm *PoolManager) StartAll(ctx context.Context) error

StartAll reads enabled agents from the store and creates a Service per agent.

func (*PoolManager) SyncAgent 

func (pm *PoolManager) SyncAgent(ctx context.Context, agentID string) error

SyncAgent reloads one agent's configuration. If the agent was deleted or disabled, its service is closed and removed. Otherwise the factory and runners are rebuilt.

func (*PoolManager) WaitInFlight added in v0.60.0 

func (pm *PoolManager) WaitInFlight(ctx context.Context) error

WaitInFlight blocks until no runtime has an in-flight chat turn or ctx expires, returning ctx's error on expiry. Graceful shutdown calls it after ingress has stopped and HTTP has drained, so accepted turns that hold no HTTP connection (channel messages, webhook runs, scheduler run-now) finish before the work contexts are cancelled (#744). It snapshots the service set once: ingress is already stopped, so no new agent service can be minted while it waits.

type PoolManagerOption 

type PoolManagerOption func(*PoolManager)

PoolManagerOption configures a PoolManager.

func WithBeforeRunBuilderPM 

func WithBeforeRunBuilderPM(b BeforeRunBuilder) PoolManagerOption

func WithBuiltinTools 

func WithBuiltinTools(tools []BuiltinTool) PoolManagerOption

func WithCodeToolSurface added in v0.66.0 

func WithCodeToolSurface(surface coreagent.CodeToolSurface) PoolManagerOption

WithCodeToolSurface selects the Code Mode provider-visible treatment. The production default remains the established hot-tool surface.

func WithCompactionPM 

func WithCompactionPM(cfg CompactionConfig) PoolManagerOption

func WithCoreHooks added in v0.41.0 

func WithCoreHooks(h []hooks.HookPlugin) PoolManagerOption

WithCoreHooks registers server-level hooks (e.g. the OTel trace hook) that live for the whole PoolManager lifetime. Unlike plugin hooks they are never rebuilt or closed on reload, so in-flight runners can keep calling them; they are closed exactly once in Close.

func WithGroupRosterLoader added in v0.65.0 

func WithGroupRosterLoader(loader func(context.Context, string, string) prompt.GroupRoster) PoolManagerOption

WithGroupRosterLoader projects group membership into a group runner prompt so an agent knows which name in the transcript is its own.

func WithHomeWorkspace added in v0.64.0 

func WithHomeWorkspace(v home.Workspace) PoolManagerOption

WithHomeWorkspace supplies the sole persistent Home resolver for runners.

func WithPluginHooksBuilder 

func WithPluginHooksBuilder(b PluginHooksBuilder) PoolManagerOption

func WithPluginToolsBuilder 

func WithPluginToolsBuilder(b PluginToolsBuilder) PoolManagerOption

func WithProjectResolver added in v0.34.0 

func WithProjectResolver(r ProjectResolverFunc) PoolManagerOption

func WithPromptSectionsBuilder 

func WithPromptSectionsBuilder(b prompt.SectionsBuilder) PoolManagerOption

func WithProviderStreamBuilder added in v0.28.0 

func WithProviderStreamBuilder(b ProviderStreamBuilder) PoolManagerOption

func WithSessionImagePipeline added in v0.61.0 

func WithSessionImagePipeline(images SessionImagePipeline) PoolManagerOption

WithSessionImagePipeline wires the ordinary-session canonical image boundary. Groups deliberately bypass it until their separate ownership model exists.

func WithSessionInboxPM added in v0.63.3 

func WithSessionInboxPM(inbox SessionInbox) PoolManagerOption

WithSessionInboxPM injects durable Agent-to-Session input persistence into every service. The inbox does not own execution; turnqueue remains caller-driven.

func WithSessionPluginViewBuilder 

func WithSessionPluginViewBuilder(b SessionPluginViewBuilder) PoolManagerOption

func WithSkillReadAuthorizer added in v0.60.0 

func WithSkillReadAuthorizer(a skillstool.SkillReadAuthorizer) PoolManagerOption

WithSkillReadAuthorizer injects Skill domain read access into every runner's skills tool, so DB-backed reads (load/search_installed) are authorized.

func WithSkillRevisionReader added in v0.64.0 

func WithSkillRevisionReader(r skillstool.RuntimeReader) PoolManagerOption

func WithSnapshotLoader added in v0.61.0 

func WithSnapshotLoader(loader config.SnapshotLoader) PoolManagerOption

WithSnapshotLoader overrides the loader used for per-agent Snapshots. The composition root passes the credential-aware loader so every runner factory resolves per-Agent Provider key overrides. A nil loader leaves the base store.

func WithToolLifecyclePM 

func WithToolLifecyclePM(tl *coreagent.ToolLifecycle) PoolManagerOption

func WithToolMetaRegistry added in v0.66.0 

func WithToolMetaRegistry(reg *toolmeta.Registry) PoolManagerOption

WithToolMetaRegistry supplies the declarations of the generated tools this build registers. Family and legacy selectors resolve through it, so a runner built without one falls back to exact-name matching rather than guessing a family from the underscores in a name.

func WithToolOverrideFetcher added in v0.60.0 

func WithToolOverrideFetcher(f ToolOverrideFetcher) PoolManagerOption

type Project added in v0.60.0 

type Project struct {
	ID            string
	AgentID       string
	UserID        string
	Name          string
	BaseDir       string
	Description   string
	Archived      bool
	IsUnavailable bool
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

Project is the transport-neutral view of a project row. Description is a plain string ("" when unset) and timestamps are UTC.

type ProjectAgentAuthorizer added in v0.60.0 

type ProjectAgentAuthorizer interface {
	Authorize(ctx context.Context, authority authz.Authority, agentID string, action authz.Action) error
}

ProjectAgentAuthorizer is the narrow Agent PEP port the project use cases gate on: a project belongs to an agent, so every use case first authorizes the caller's read access to that agent. agentaccess.Service satisfies it.

type ProjectDescriptor added in v0.64.0 

type ProjectDescriptor struct {
	ID      string
	UserID  string
	AgentID string
	Path    string
}

ProjectDescriptor is the authorized logical identity of a project. Path is a canonical agent-workspace-relative name; it is never a provider/host path.

func SnapshotAuthorizedProjectSkills added in v0.64.0 

func SnapshotAuthorizedProjectSkills(ctx context.Context, resolve ProjectResolverFunc, opener home.RootOpener, projectID, userID, agentID string) (snapshot *skill.ProjectSnapshot, descriptor ProjectDescriptor, resultErr error)

SnapshotAuthorizedProjectSkills resolves the exact project authority, opens a read-only workspace capability, snapshots Skills, and closes the capability before returning it to downstream prompt/tool consumers.

type ProjectResolverFunc added in v0.34.0 

type ProjectResolverFunc func(ctx context.Context, projectID, userID, agentID string) (ProjectDescriptor, error)

ProjectResolverFunc resolves the exact (user, agent, project) tuple without exposing the workspace provider's physical path.

type ProjectStore added in v0.60.0 

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

ProjectStore owns the project application use cases (Authority-bound list/create/get/update/delete) plus the runtime workspace resolution the pool manager binds: Resolve satisfies ProjectResolverFunc. A project is owned by (user, agent); the CRUD use cases enforce that ownership, the route-agent binding, and the workspace-containment invariant, and return the transport-neutral Project value.

func NewProjectStore added in v0.60.0 

func NewProjectStore(db *pgxpool.Pool, agents ProjectAgentAuthorizer, opts ...ProjectStoreOption) *ProjectStore

func (*ProjectStore) Create added in v0.60.0 

func (s *ProjectStore) Create(ctx context.Context, authority authz.Authority, agentID, name, baseDir string, description *string) (Project, error)

Create persists a new project for the caller under the agent, after validating that base_dir is contained in the agent workspace. Gated on agent read access.

func (*ProjectStore) Delete added in v0.60.0 

func (s *ProjectStore) Delete(ctx context.Context, authority authz.Authority, agentID, projectID string) error

Delete removes an owned project bound to the route agent.

func (*ProjectStore) Get added in v0.60.0 

func (s *ProjectStore) Get(ctx context.Context, authority authz.Authority, agentID, projectID string) (Project, error)

Get returns one owned project bound to the route agent. A row waiting for coordinate repair is returned unavailable so callers can repair or delete it. A missing project, foreign owner, or route-agent mismatch returns not found.

func (*ProjectStore) List added in v0.60.0 

func (s *ProjectStore) List(ctx context.Context, authority authz.Authority, agentID string, includeArchived bool) ([]Project, error)

List returns the agent's projects owned by the caller, optionally including archived ones. Rows waiting for coordinate repair remain visible but cannot expose their historical host path. Gated on agent read access.

func (*ProjectStore) Resolve added in v0.60.0 

func (s *ProjectStore) Resolve(ctx context.Context, projectID, userID, agentID string) (ProjectDescriptor, error)

Resolve returns the logical descriptor for the exact project owner tuple.

func (*ProjectStore) SnapshotSkills added in v0.64.0 

func (ps *ProjectStore) SnapshotSkills(ctx context.Context, projectID, userID, agentID string) (*skill.ProjectSnapshot, ProjectDescriptor, error)

SnapshotSkills resolves exact project ownership and snapshots through Home.

func (*ProjectStore) Update added in v0.60.0 

func (s *ProjectStore) Update(ctx context.Context, authority authz.Authority, agentID, projectID string, in ProjectUpdate) (Project, error)

Update merges the provided fields into an owned project bound to the route agent and persists it. A supplied base_dir is re-validated for containment.

type ProjectStoreOption added in v0.64.0 

type ProjectStoreOption func(*ProjectStore)

NewProjectStore builds a ProjectStore over the given pool and config store. agents is the Agent PEP the CRUD use cases gate on; it may be nil for the runtime-only Resolve/Ensure paths (which perform no authorization).

func WithProjectHomeWorkspace added in v0.64.0 

func WithProjectHomeWorkspace(viewer home.Workspace) ProjectStoreOption

type ProjectUpdate added in v0.60.0 

type ProjectUpdate struct {
	Name        *string
	BaseDir     *string
	Description *string
}

ProjectUpdate carries the optional fields of an update; a nil field leaves the stored value unchanged.

type ProviderStreamBuilder added in v0.28.0 

type ProviderStreamBuilder func(api, apiKey, baseURL string) (providers.StreamFunc, error)

type Runner 

type Runner = agentruntime.Runner

Runner executes prompts against an AI backend.

type RunnerParams 

type RunnerParams = agentruntime.RunnerParams

RunnerParams holds parameters for creating a new Runner instance.

type SchedulerChatRequest added in v0.40.0 

type SchedulerChatRequest struct {
	SessionID string // scheduler-derived session ID
	UserID    string
	AgentID   string
	Message   MessageContent
	Model     string
	Authority authz.Authority
}

SchedulerChatRequest describes a scheduler-initiated chat turn.

type Service added in v0.40.0 

type Service struct {
	Sessions      *session.Registry // legacy fallback for tests only; production lifecycle goes through SessionAccess.
	Runtime       *agentruntime.Runtime
	SessionAccess SessionAccessService
	SessionInbox  SessionInbox
	// AgentID is the executor this service belongs to.
	AgentID string
	// contains filtered or unexported fields
}

func (*Service) ArchiveSession added in v0.60.0 

func (s *Service) ArchiveSession(ctx context.Context, authority authz.Authority, userID, agentID, sessionID string) error

func (*Service) Chat added in v0.40.0 

func (s *Service) Chat(ctx context.Context, req ChatRequest) <-chan Event

Chat resolves (or creates) a session and executes a chat turn.

When SessionID is empty, a new session is created with a generated ID. When SessionID is non-empty, the session must already exist (resume-only); unknown IDs return an error instead of silently creating. A rejected admission remains its historic immediate error event; callers needing that distinction use ChatAdmitted.

func (*Service) ChatAdmitted added in v0.61.0 

func (s *Service) ChatAdmitted(ctx context.Context, req ChatRequest) (<-chan Event, error)

ChatAdmitted resolves (or creates) a session and synchronously admits one chat turn. A non-nil error means session access, session resolution, or the runtime busy guard rejected the turn before any run/session/tool side effect began. Once it returns a stream, the turn is admitted and all later runtime failures arrive on the stream — the call returns at admission, not completion.

func (*Service) ChatForGoalDecomposition added in v0.50.0 

func (s *Service) ChatForGoalDecomposition(ctx context.Context, req TaskChatRequest) <-chan Event

ChatForGoalDecomposition runs one persisted worker turn on a goal's decomposition planning session. Unlike a worker (execution) session that session is KindDelegate (#525: the plan session is resumable through the delegate tool and re-openable in the UI), so it must be resolved with RequireKind=KindDelegate — routing it through ChatForTask fails with a kind mismatch and starves the goal's decomposition budget. The session is pre-minted at BeginDecomposition, so this is resume-only and never creates.

func (*Service) ChatForScheduler added in v0.40.0 

func (s *Service) ChatForScheduler(ctx context.Context, req SchedulerChatRequest) <-chan Event

ChatForScheduler resolves or creates a scheduler session using a trusted scheduler-derived session ID. Exact-ID creation is allowed because the scheduler system owns the ID derivation.

func (*Service) ChatForTask added in v0.46.0 

func (s *Service) ChatForTask(ctx context.Context, req TaskChatRequest) <-chan Event

ChatForTask runs one persisted chat turn on a task session. Exact-ID creation is allowed because the task system owns the ID. The per-run extra tools force a fresh runner, which is evicted once the turn finishes so the tools never leak into later turns on the same session.

func (*Service) CompactAuthorizedSession added in v0.60.0 

func (s *Service) CompactAuthorizedSession(ctx context.Context, info session.Info) (string, error)

CompactSession runs full compaction on the session identified by sessionID. This is a best-effort operation: it returns the compaction summary or an error.

Group sessions are unsupported: their history is assembled from the group event log, not the LCM conversation, and NeedsCompaction already declines them. The manual path rejects a group session up front (before touching the compactor) with ErrGroupCompactionUnsupported rather than run a private-style compaction over an event-log conversation. CompactAuthorizedSession performs compaction after the caller has authorized ActionExecute for info under its current Session Access evaluation.

func (*Service) Delegate added in v0.40.0 

func (s *Service) Delegate(ctx context.Context, req DelegateRequest) (DelegateResult, error)

Delegate runs a delegate turn through a persisted child session.

When SessionID is empty, a new delegate session is created with a generated ID. When SessionID is non-empty, the session must already exist (resume-only); this prevents model-supplied session_id from reserving arbitrary future IDs.

func (*Service) History added in v0.40.0 

func (s *Service) History(ctx context.Context, info session.Info) []ai.Message

func (*Service) MintTaskSession added in v0.40.0 

func (s *Service) MintTaskSession(ctx context.Context, authority authz.Authority, userID, executorAgentID, projectID string) (session.Info, error)

MintTaskSession creates a new task worker session under the resolved agent. The session is always new (generated ID) and uses KindTask/ChannelTask.

func (*Service) NewSession added in v0.40.0 

func (s *Service) NewSession(ctx context.Context, authority authz.Authority, userID, agentID, projectID string, kind session.Kind, channel session.Channel) (session.Info, error)

NewSession creates a new session with a generated ID. Used by the HTTP API when the web UI creates a session — always new, never resume.

func (*Service) ResolveChatChannelSession added in v0.61.0 

func (s *Service) ResolveChatChannelSession(ctx context.Context, req ChatChannelRequest) (session.Info, error)

ResolveChatChannelSession resolves the session a channel chat is currently bound to, creating one when the chat is new. It returns the Info without executing a chat turn.

func (*Service) ResolveChatChannelSessionForUse added in v0.61.0 

func (s *Service) ResolveChatChannelSessionForUse(ctx context.Context, req ChatChannelRequest) (session.Info, error)

ResolveChatChannelSessionForUse is ResolveChatChannelSession plus the fresh execute decision a turn (or a compaction) needs on the exact durable session.

func (*Service) ResolveMainSession added in v0.40.0 

func (s *Service) ResolveMainSession(ctx context.Context, authority authz.Authority, userID, agentID string) (session.Info, error)

ResolveMainSession resolves the main session for a user+agent pair, creating one if missing. It is the canonical replacement for Pool.ResolveSession on private user channels.

func (*Service) ResolveMainSessionForUse added in v0.60.0 

func (s *Service) ResolveMainSessionForUse(ctx context.Context, authority authz.Authority, userID, agentID string) (session.Info, error)

func (*Service) ResolvePrivateChannelSession added in v0.60.0 

func (s *Service) ResolvePrivateChannelSession(ctx context.Context, authority authz.Authority, sessionKey, userID, agentID string, channel session.Channel) (session.Info, error)

ResolvePrivateChannelSession resolves or creates a chat session whose id IS the caller's trusted system-derived key.

Webhook ingress is the only remaining caller: a persistent webhook addresses exactly one durable session per webhook id, has no `/new`, and its channel (ChannelWebhook) is deliberately not its key — so it cannot use the chat-channel binding, which would either miss it or merge every webhook of a user into one session. Chat adapters use ResolveChatChannelSession instead.

func (*Service) RotateChatChannelSession added in v0.61.0 

func (s *Service) RotateChatChannelSession(ctx context.Context, req ChatChannelRequest, expectedSessionID string) (session.Info, error)

RotateChatChannelSession archives the chat's current session and returns the successor, which starts empty. It is the `/new` counterpart to ResolveChatChannelSessionForUse: rotation is one authorized compare-and-rotate use case, so a command that raced another rotation cannot archive the successor that one just created.

expectedSessionID is the session the caller observed; an empty value rotates whatever is current. A mismatch reports session.ErrStaleRotation.

func (*Service) RotateMainSession added in v0.61.0 

func (s *Service) RotateMainSession(ctx context.Context, authority authz.Authority, userID, agentID, expectedSessionID string) (session.Info, error)

RotateMainSession archives the user's current main session and returns the successor, which starts empty. It is the `/new` counterpart to ResolveMainSessionForUse: rotation is one authorized compare-and-rotate use case rather than a resolve followed by a separate archive, so a turn that raced another rotation cannot archive the successor.

expectedSessionID is the main session the caller observed; an empty value rotates whatever is current. A mismatch reports session.ErrStaleRotation.

func (*Service) RunConversationSession added in v0.63.3 

func (s *Service) RunConversationSession(ctx context.Context, target session.Info, message MessageContent) <-chan Event

RunConversationSession starts one transcript-only turn from an active source agent Session into an already-authorized owned conversation Session. This is the trusted authority-mint boundary used by session.send; connector delivery is intentionally absent.

func (*Service) RunDelegateSession added in v0.40.0 

func (s *Service) RunDelegateSession(ctx context.Context, req delegatetool.SessionRunRequest) (delegatetool.SessionRunResult, error)

RunDelegateSession implements delegatetool.SessionRunner so that Service can be passed directly to delegate tool constructors. Its identity is the parent runtime's validated session identity: a delegate tool cannot choose an owner, executor, or project through its model arguments.

func (*Service) RunManagedSession added in v0.63.3 

func (s *Service) RunManagedSession(ctx context.Context, req delegatetool.ManagedSessionRequest) (delegatetool.ManagedSessionResult, error)

RunManagedSession invokes the delegate configured on the current source runner. The request carries no principal, Agent, project, model, or tool identity: those remain trusted runtime-context facts.

func (*Service) SessionLive added in v0.49.3 

func (s *Service) SessionLive(sessionID string) bool

SessionLive reports whether a turn is currently in flight on the session.

func (*Service) StopSession added in v0.63.0 

func (s *Service) StopSession(ctx context.Context, sessionID string) bool

StopSession cancels the active turn for sessionID. Authorization belongs to the Session access boundary; this method only exposes the runtime operation.

func (*Service) SubscribeSession added in v0.49.3 

func (s *Service) SubscribeSession(sessionID string) (<-chan Event, func())

SubscribeSession registers a read-only listener for a session's live turn events, regardless of who initiated the turn. Used by the SSE endpoint to let the web UI watch scheduler/task/delegate turns in real time.

type ServiceManager added in v0.40.0 

type ServiceManager interface {
	// GetService returns the Service for the given agent ID, or nil if not found.
	GetService(agentID string) *Service
	// Default returns any service (first found). Useful for single-agent deployments.
	Default() *Service
}

ServiceManager provides multi-agent Service lookup. It replaces PoolManager for callers migrated to the new model.

type SessionAccess added in v0.60.0 

type SessionAccess interface {
	Create(context.Context, string, string, string, session.Kind, session.Channel) (session.Info, error)
	ResolveMain(context.Context, string, string) (session.Info, error)
	RotateMain(context.Context, string, string, string) (session.Info, error)
	ResolveChatChannel(context.Context, session.ChannelRequest) (session.Info, error)
	RotateChannel(context.Context, session.ChannelRequest) (session.Info, error)
	Use(context.Context, string, string) (session.Info, error)
	EnsureRead(context.Context, session.Request) (session.Info, error)
	EnsureUse(context.Context, session.Request) (session.Info, error)
	Delete(context.Context, string, string) (session.Info, error)
	Archive(context.Context, session.Info) error
}

type SessionAccessService added in v0.60.0 

type SessionAccessService interface {
	Begin(context.Context, authz.Authority) (SessionAccess, error)
}

Service is a thin composition facade over session.Registry and runtime.Runtime. It provides ergonomic entry points for common use cases without hiding the conceptual split: policy lives in Session, execution lives in Runtime.

Runtime owns execution; SessionAccess owns every lifecycle and policy decision. Sessions remains only as a legacy test fixture field and must not become a production entry point again.

type SessionImagePipeline added in v0.61.0 

type SessionImagePipeline interface {
	Enrich(context.Context, sessionmedia.Owner, string, []ai.ContentBlock) ([]ai.ContentBlock, error)
	Load(context.Context, sessionmedia.Owner, string) (ai.ImageContent, error)
}

SessionImagePipeline is the complete session image boundary. Both operations are owner-scoped: a group session's media belongs to the group, a direct session's to its user.

type SessionInbox added in v0.63.3 

type SessionInbox interface {
	Enqueue(context.Context, sessioninbox.Input) (sessioninbox.Message, error)
	FailPending(context.Context, string, sessioninbox.ErrorCode) (bool, error)
}

SessionInbox persists Agent-originated inputs independently of live execution.

type SessionPluginViewBuilder 

type SessionPluginViewBuilder func(ctx context.Context) (pkgplugins.SessionPluginView, error)

type SettingsAgentActionTool added in v0.66.0 

type SettingsAgentActionTool = toolmeta.ActionTool

SettingsAgentActionTool describes one generated tool: an exact schema bound to one action.

func SettingsAgentActionTools added in v0.66.0 

func SettingsAgentActionTools() []SettingsAgentActionTool

SettingsAgentActionTools lists every generated tool in a stable order.

type SettingsAgentCreateInput added in v0.66.0 

type SettingsAgentCreateInput struct {
	Enabled             *bool  `json:"enabled,omitempty"`
	Id                  string `json:"id,omitempty"`
	Model               string `json:"model,omitempty"`
	ModelFast           string `json:"model_fast,omitempty"`
	ModelFastThinking   string `json:"model_fast_thinking,omitempty"`
	ModelStrong         string `json:"model_strong,omitempty"`
	ModelStrongThinking string `json:"model_strong_thinking,omitempty"`
	ModelThinking       string `json:"model_thinking,omitempty"`
	Name                string `json:"name,omitempty"`
	Scope               string `json:"scope,omitempty"`
	Soul                string `json:"soul,omitempty"`
	SystemPrompt        string `json:"system_prompt,omitempty"`
}

type SettingsAgentDeleteInput added in v0.66.0 

type SettingsAgentDeleteInput struct {
	ExpectedVersion string `json:"expected_version,omitempty"`
	Id              string `json:"id,omitempty"`
}

type SettingsAgentGetInput added in v0.66.0 

type SettingsAgentGetInput struct {
	Id string `json:"id,omitempty"`
}

type SettingsAgentHandler added in v0.66.0 

type SettingsAgentHandler interface {
	Create(context.Context, SettingsAgentCreateInput) (any, error)
	Delete(context.Context, SettingsAgentDeleteInput) (any, error)
	Get(context.Context, SettingsAgentGetInput) (any, error)
	List(context.Context, SettingsAgentListInput) (any, error)
	Update(context.Context, SettingsAgentUpdateInput) (any, error)
}

type SettingsAgentListInput added in v0.66.0 

type SettingsAgentListInput struct {
	Limit int `json:"limit,omitempty"`
}

type SettingsAgentToolActionTool added in v0.66.0 

type SettingsAgentToolActionTool = toolmeta.ActionTool

SettingsAgentToolActionTool describes one generated tool: an exact schema bound to one action.

func SettingsAgentToolActionTools added in v0.66.0 

func SettingsAgentToolActionTools() []SettingsAgentToolActionTool

SettingsAgentToolActionTools lists every generated tool in a stable order.

type SettingsAgentToolDeleteInput added in v0.66.0 

type SettingsAgentToolDeleteInput struct {
	ExpectedVersion string `json:"expected_version,omitempty"`
	TargetAgentId   string `json:"target_agent_id,omitempty"`
	ToolName        string `json:"tool_name,omitempty"`
}

type SettingsAgentToolHandler added in v0.66.0 

type SettingsAgentToolHandler interface {
	Delete(context.Context, SettingsAgentToolDeleteInput) (any, error)
	List(context.Context, SettingsAgentToolListInput) (any, error)
	Update(context.Context, SettingsAgentToolUpdateInput) (any, error)
}

type SettingsAgentToolListInput added in v0.66.0 

type SettingsAgentToolListInput struct {
	TargetAgentId string `json:"target_agent_id,omitempty"`
}

type SettingsAgentToolUpdateInput added in v0.66.0 

type SettingsAgentToolUpdateInput struct {
	Enabled         bool   `json:"enabled,omitempty"`
	ExpectedVersion string `json:"expected_version,omitempty"`
	TargetAgentId   string `json:"target_agent_id,omitempty"`
	ToolName        string `json:"tool_name,omitempty"`
}

type SettingsAgentUpdateInput added in v0.66.0 

type SettingsAgentUpdateInput struct {
	Enabled             *bool   `json:"enabled,omitempty"`
	ExpectedVersion     string  `json:"expected_version,omitempty"`
	Id                  string  `json:"id,omitempty"`
	Model               *string `json:"model,omitempty"`
	ModelFast           string  `json:"model_fast,omitempty"`
	ModelFastThinking   string  `json:"model_fast_thinking,omitempty"`
	ModelStrong         string  `json:"model_strong,omitempty"`
	ModelStrongThinking string  `json:"model_strong_thinking,omitempty"`
	ModelThinking       string  `json:"model_thinking,omitempty"`
	Name                string  `json:"name,omitempty"`
	Scope               string  `json:"scope,omitempty"`
	Soul                *string `json:"soul,omitempty"`
	SystemPrompt        *string `json:"system_prompt,omitempty"`
}

type StepEvent added in v0.33.0 

type StepEvent = agentruntime.StepEvent

StepEvent marks the boundary of an agentic step.

type TaskChatRequest added in v0.46.0 

type TaskChatRequest struct {
	SessionID        string // task session minted at task creation
	UserID           string
	AgentID          string
	ProjectID        string
	Message          MessageContent
	ExtraTools       []tools.Tool // per-run tools (e.g. task_control)
	ExcludedTools    []string
	OnSandboxSession func(sandbox.Session) error
	Authority        authz.Authority
}

TaskChatRequest describes one worker turn on a durable task session.

type ToolOverride added in v0.60.0 

type ToolOverride struct {
	ToolName string
	Scope    string
	Enabled  bool
}

ToolOverride is the runner-facing view of a persisted tool visibility row.

type ToolOverrideDecision added in v0.60.0 

type ToolOverrideDecision struct {
	Enabled bool
	Origin  string
}

func ResolveToolOverride added in v0.60.0 

func ResolveToolOverride(defaultEnabled bool, toolName string, rows []ToolOverride) ToolOverrideDecision

type ToolOverrideFetcher added in v0.60.0 

type ToolOverrideFetcher func(ctx context.Context, userID, agentID string) ([]ToolOverride, error)

type ToolOverrideKey added in v0.60.0 

type ToolOverrideKey struct {
	ToolName string
	Scope    string
	UserID   string
	AgentID  string
}

ToolOverrideKey identifies one override row for clearing.

type ToolOverrideStore added in v0.60.0 

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

ToolOverrideStore reads persisted tool-visibility overrides for an agent+user context. Its Fetch method satisfies ToolOverrideFetcher.

func NewToolOverrideStore added in v0.60.0 

func NewToolOverrideStore(db *pgxpool.Pool) *ToolOverrideStore

NewToolOverrideStore builds a ToolOverrideStore over the given pool.

func (*ToolOverrideStore) Clear added in v0.60.0 

func (s *ToolOverrideStore) Clear(ctx context.Context, k ToolOverrideKey) error

Clear deletes a tool visibility override if present for existing HTTP callers.

func (*ToolOverrideStore) ClearIfVersion added in v0.66.0 

func (s *ToolOverrideStore) ClearIfVersion(ctx context.Context, k ToolOverrideKey, expected string) error

ClearIfVersion deletes only an existing row at the version returned by Get.

func (*ToolOverrideStore) Fetch added in v0.60.0 

func (s *ToolOverrideStore) Fetch(ctx context.Context, userID, agentID string) ([]ToolOverride, error)

Fetch returns the tool overrides that apply to the given user+agent pair.

func (*ToolOverrideStore) Get added in v0.66.0 

func (s *ToolOverrideStore) Get(ctx context.Context, k ToolOverrideKey) (ToolOverrideVersion, error)

func (*ToolOverrideStore) ListVersions added in v0.66.0 

func (s *ToolOverrideStore) ListVersions(ctx context.Context, userID, agentID string) (map[string]ToolOverrideVersion, error)

Get returns one exact owner-bound override. Missing rows receive the stable absent sentinel so a caller can conditionally create rather than race an unguarded upsert. ListVersions returns every exact user+agent override in one query. Missing tools are represented by callers with ToolOverrideAbsentVersion.

func (*ToolOverrideStore) Set added in v0.60.0 

func (s *ToolOverrideStore) Set(ctx context.Context, w ToolOverrideWrite) error

Set upserts a tool visibility override for existing HTTP callers, which keep their historical unconditional-write contract.

func (*ToolOverrideStore) SetIfVersion added in v0.66.0 

func (s *ToolOverrideStore) SetIfVersion(ctx context.Context, w ToolOverrideWrite, expected string) (ToolOverrideVersion, error)

SetIfVersion updates an existing row or creates an absent row only when its version still matches. A zero-row conditional write is a conflict, never a silent retry or an unconditional upsert.

type ToolOverrideVersion added in v0.66.0 

type ToolOverrideVersion struct {
	ToolName string `json:"tool_name"`
	Scope    string `json:"scope"`
	Enabled  bool   `json:"enabled"`
	Version  string `json:"version"`
	Present  bool   `json:"present"`
}

ToolOverrideVersion is the safe exact-row projection used by management tools.

type ToolOverrideWrite added in v0.60.0 

type ToolOverrideWrite struct {
	ToolName string
	Scope    string
	UserID   string
	AgentID  string
	Enabled  bool
}

ToolOverrideWrite is the durable owner+scope key plus the desired enabled state for one tool visibility override.

type ToolUnavailableReason added in v0.66.0 

type ToolUnavailableReason string
const (
	// ToolUnavailableReasonEmailConfigRequired is emitted only after the email
	// availability predicate confirms the signed-in user has no EMAIL_CONFIG.
	ToolUnavailableReasonEmailConfigRequired ToolUnavailableReason = "email_config_required"
)

type ToolUseEvent 

type ToolUseEvent = agentruntime.ToolUseEvent

ToolUseEvent describes a tool invocation in progress or completed.

Source Files

View all Source files

Directories

Path Synopsis
Package runtime executes agent conversations in already-resolved sessions.
 Package runtime executes agent conversations in already-resolved sessions.
Package sandbox resolves an agent's sandbox config into a live session and provides that session's agent-facing tool projections (bash, read, write, edit).
 Package sandbox resolves an agent's sandbox config into a live session and provides that session's agent-facing tool projections (bash, read, write, edit).
Package session owns agent-session lifecycle.
 Package session owns agent-session lifecycle.
access
Package access is the authoritative Session and Workspace application service.
 Package access is the authoritative Session and Workspace application service.
inbox
Package inbox persists Agent-originated Session inputs without owning their execution.
 Package inbox persists Agent-originated Session inputs without owning their execution.
turnqueue
Package turnqueue serializes synchronous agent-originated turns per Session.
 Package turnqueue serializes synchronous agent-originated turns per Session.
Package settingspolicy owns the narrow discovery and turn-capability boundary for conversational Settings tools.
 Package settingspolicy owns the narrow discovery and turn-capability boundary for conversational Settings tools.
Package tracehook is the core agent trace hook: it logs LLM, tool, and memory activity via slog and, when OTel tracing is enabled, records the session/turn/LLM/tool/memory span hierarchy.
 Package tracehook is the core agent trace hook: it logs LLM, tool, and memory activity via slog and, when OTel tracing is enabled, records the session/turn/LLM/tool/memory span hierarchy.

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.