Documentation
¶
Overview ¶
Package systemchat owns system conversation admission and durable execution state.
Index ¶
- func AsyncPrincipal(ctx context.Context, q *dbq.Queries, originID pgtype.UUID) (authz.Principal, error)
- func CaptureAsyncOrigin(ctx context.Context, q *dbq.Queries, p authz.Principal, agentID uuid.UUID, ...) (pgtype.UUID, error)
- func CaptureHostedAsyncOrigin(ctx context.Context, q *dbq.Queries, agentID, runID uuid.UUID) (pgtype.UUID, error)
- func FreshPrincipal(ctx context.Context, q *dbq.Queries, p authz.Principal) (authz.Principal, error)
- func OriginRunID(ctx context.Context) uuid.UUID
- func Platform(p authz.Principal) string
- func ToolAvailable(ctx context.Context, q *dbq.Queries, p authz.Principal, action authz.Action) bool
- type ConversationDetail
- type ListRunsResult
- type PromptInput
- type RunSummary
- type Service
- func (s *Service) AgentAccess(ctx context.Context, p authz.Principal, agentID uuid.UUID) (string, error)
- func (s *Service) AppendNotification(ctx context.Context, agentID, conversationID, originRunID uuid.UUID, ...) (dbq.SystemConversation, error)
- func (s *Service) CancelRun(ctx context.Context, p authz.Principal, runID uuid.UUID) (bool, error)
- func (s *Service) CheckRun(ctx context.Context, p authz.Principal, runID uuid.UUID) error
- func (s *Service) Control(ctx context.Context, p authz.Principal, conversationID uuid.UUID, ...) (bool, error)
- func (s *Service) CreateConversation(ctx context.Context, p authz.Principal, title string) (dbq.SystemConversation, error)
- func (s *Service) DeleteConversation(ctx context.Context, p authz.Principal, conversationID uuid.UUID) error
- func (s *Service) EnsureBridgeConversation(ctx context.Context, p authz.Principal) (dbq.SystemConversation, error)
- func (s *Service) FinishRun(ctx context.Context, runID uuid.UUID, status, message string) error
- func (s *Service) GetConversation(ctx context.Context, p authz.Principal, conversationID uuid.UUID) (ConversationDetail, error)
- func (s *Service) ListConversations(ctx context.Context, p authz.Principal) ([]dbq.SystemConversation, error)
- func (s *Service) ListRuns(ctx context.Context, p authz.Principal, cursor time.Time, limit int32) (ListRunsResult, error)
- func (s *Service) ObserveRun(ctx context.Context, p authz.Principal, runID uuid.UUID, ...)
- func (s *Service) PersistSuspension(ctx context.Context, conversationID, runID uuid.UUID, checkpoint []byte) error
- func (s *Service) RecordSystemRunUsage(runID, userID uuid.UUID, providerCatalogID, providerSlug, model string, ...)
- func (s *Service) ResumePrincipal(ctx context.Context, conversationID, originRunID uuid.UUID) (authz.Principal, error)
- func (s *Service) RunContext(ctx context.Context, p authz.Principal, runID uuid.UUID) (context.Context, error)
- func (s *Service) RunPrincipal(ctx context.Context, runID uuid.UUID) (authz.Principal, error)
- func (s *Service) SessionStore(ctx context.Context, p authz.Principal, conversationID, runID uuid.UUID) (*sessionStore, error)
- func (s *Service) Settings(ctx context.Context, p authz.Principal) (dbq.SystemSetting, error)
- func (s *Service) StartRun(ctx context.Context, p authz.Principal, conversationID uuid.UUID, ...) (uuid.UUID, dbq.SystemConversation, error)
- func (s *Service) User(ctx context.Context, p authz.Principal) (dbq.User, error)
- func (s *Service) UserAgentGrants(ctx context.Context, p authz.Principal) ([]dbq.ListUserAgentGrantsRow, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AsyncPrincipal ¶
func AsyncPrincipal(ctx context.Context, q *dbq.Queries, originID pgtype.UUID) (authz.Principal, error)
AsyncPrincipal resolves a system-originated operation through its persisted initiating run. The caller must also authorize the operation's target resource.
func CaptureAsyncOrigin ¶
func CaptureAsyncOrigin(ctx context.Context, q *dbq.Queries, p authz.Principal, agentID uuid.UUID, conversation string) (pgtype.UUID, error)
CaptureAsyncOrigin persists the server-installed system run before async dispatch. A request's conversation field is a consistency check, not authority.
func CaptureHostedAsyncOrigin ¶
func CaptureHostedAsyncOrigin(ctx context.Context, q *dbq.Queries, agentID, runID uuid.UUID) (pgtype.UUID, error)
CaptureHostedAsyncOrigin receives a host-resolved runtime run, not the builder's codegen correlation UUID or a client-supplied sourceRunId.
func FreshPrincipal ¶
func FreshPrincipal(ctx context.Context, q *dbq.Queries, p authz.Principal) (authz.Principal, error)
FreshPrincipal accepts only an admission proof and resolves its live authority.
func OriginRunID ¶
OriginRunID is zero for operations that do not originate in system chat.
Types ¶
type ConversationDetail ¶
type ConversationDetail struct {
Conversation dbq.SystemConversation
Messages []dbq.SystemMessage
}
ConversationDetail bundles a conversation with its full message history. The caller decides whether to also request paginated tails separately for very long conversations (we don't paginate on the initial Get because chat conversations rarely grow beyond a few dozen messages — agent chat pages from the same shape).
type ListRunsResult ¶
type ListRunsResult struct {
Runs []RunSummary
NextCursor time.Time
}
ListRunsResult bundles a page of runs with the cursor for the next page (zero StartedAt when no further pages exist).
type PromptInput ¶
type RunSummary ¶
type RunSummary struct {
ID uuid.UUID
ConversationID uuid.UUID
ConversationTitle string
Status string // 'running' | 'suspended' | 'complete' | 'error' | 'cancelled'
TriggerType string // 'prompt' | 'bridge' | 'event'
MessagePreview string // first linked message for the turn (” when no message is bound)
ErrorMessage string
CostEstimate float64
StartedAt time.Time
FinishedAt *time.Time
}
RunSummary is one row from the caller's sysagent activity view — run lifecycle (status + timestamps) plus the parent conversation's title so the UI can render without a per-row fetch.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func (*Service) AgentAccess ¶
func (*Service) AppendNotification ¶
func (*Service) CancelRun ¶
CancelRun serializes with admission and suspension on the conversation row.
func (*Service) CheckRun ¶
CheckRun rechecks the original credential and durable cancellation before work.
func (*Service) Control ¶
func (s *Service) Control(ctx context.Context, p authz.Principal, conversationID uuid.UUID, command, args string) (bool, error)
Control serializes conversation controls with run admission and history writes.
func (*Service) CreateConversation ¶
func (s *Service) CreateConversation(ctx context.Context, p authz.Principal, title string) (dbq.SystemConversation, error)
CreateConversation inserts a fresh conversation for the caller. title is optional; the DB default is "New chat".
func (*Service) DeleteConversation ¶
func (s *Service) DeleteConversation(ctx context.Context, p authz.Principal, conversationID uuid.UUID) error
DeleteConversation removes a conversation (and via ON DELETE CASCADE its messages, runs, and any pending checkpoint state). audit rows for the conversation stay (ON DELETE SET NULL preserves forensics — what happened in a now-deleted conversation is still recoverable).
func (*Service) EnsureBridgeConversation ¶
func (s *Service) EnsureBridgeConversation(ctx context.Context, p authz.Principal) (dbq.SystemConversation, error)
EnsureBridgeConversation derives every routing coordinate from the poller's live admission proof. No user ID, bridge ID or chat ID is accepted separately.
func (*Service) GetConversation ¶
func (s *Service) GetConversation(ctx context.Context, p authz.Principal, conversationID uuid.UUID) (ConversationDetail, error)
GetConversation returns the conversation + its full message history (including pre-checkpoint rows + checkpoint markers — the UI's full timeline, not the LLM context filter). 404 for a missing conversation, 404 (not 403) for someone else's — exposing existence to non-owners would leak metadata.
func (*Service) ListConversations ¶
func (s *Service) ListConversations(ctx context.Context, p authz.Principal) ([]dbq.SystemConversation, error)
ListConversations returns the caller's own conversations, newest-active first. Ownership is enforced at the query level — conversations aren't shared.
func (*Service) ListRuns ¶
func (s *Service) ListRuns(ctx context.Context, p authz.Principal, cursor time.Time, limit int32) (ListRunsResult, error)
ListRuns returns the caller's recent sysagent runs across all their conversations, newest first. Cursor is the started_at of the last row from the previous page; zero fetches the newest page. Caller must be authenticated; the query is owner-scoped (user_id = p.UserID) so no cross-user leak is possible.
func (*Service) ObserveRun ¶
func (s *Service) ObserveRun(ctx context.Context, p authz.Principal, runID uuid.UUID, cancel context.CancelFunc)
ObserveRun makes cancellations and credential revocations visible on every replica. Database failures stop execution rather than letting an unvalidated turn continue.
func (*Service) PersistSuspension ¶
func (*Service) RecordSystemRunUsage ¶
func (s *Service) RecordSystemRunUsage(runID, userID uuid.UUID, providerCatalogID, providerSlug, model string, usage stream.Usage, errored bool)
recordSystemRunUsage writes this turn's accumulated model spend to the shared llm_usage ledger and refreshes the system run's cost aggregate.
The sysagent runs the model loop in-process, so there is one accumulated stream.Usage per turn (not one per round-trip like the runtime proxy) — recorded as a single ledger row attributed to the operator (UserID) and this system run (SystemRunID), call_kind "system". agent_id is left null: the system agent has no agent row. Cost is computed from the same sol/provider catalog every other ledger writer uses.
Best-effort: accounting must never break a turn that already ran. Uses a fresh bounded ctx so a cancelled turn still records the tokens it burned.
func (*Service) ResumePrincipal ¶
func (*Service) RunContext ¶
func (s *Service) RunContext(ctx context.Context, p authz.Principal, runID uuid.UUID) (context.Context, error)
RunContext binds downstream build/bot admission to this verified system run. Those services persist OriginRunID alongside their asynchronous work record.
func (*Service) RunPrincipal ¶
RunPrincipal restores the exact original admission, including for follow-ups.