Documentation
¶
Overview ¶
Package agent is Ask Ether: a bounded tool-calling loop over the shared tool catalogue, streaming the AI SDK UI message stream, with durable transcripts, approvals, secret requests and a tool-call audit.
Index ¶
- Constants
- Variables
- func OwnerPrincipal() tools.Principal
- func ValidateToolInput(schema json.RawMessage, input any) error
- type Approval
- type Chunk
- type Message
- type Model
- type Options
- type SecretReq
- type Service
- func (s *Service) CancelTurn(turnID string) bool
- func (s *Service) ContinueAfterApproval(ctx context.Context, p tools.Principal, appr Approval, tc TurnContext) (bool, error)
- func (s *Service) DecideApproval(ctx context.Context, p tools.Principal, id, decision, note string) (Approval, error)
- func (s *Service) Handler() http.Handler
- func (s *Service) RunTurn(ctx context.Context, p tools.Principal, threadID, prompt string, ...) (string, string, error)
- func (s *Service) Running(threadID string) bool
- func (s *Service) Status() Status
- func (s *Service) SubmitSecret(ctx context.Context, id, value string) error
- type Status
- type Store
- func (s *Store) AllMessages(ctx context.Context, threadID string) ([]Message, error)
- func (s *Store) AppendMessage(ctx context.Context, threadID, role string, parts json.RawMessage) (Message, error)
- func (s *Store) Audit(ctx context.Context, threadID, tool, principal, status, mappedErr string, ...) error
- func (s *Store) ClaimApproval(ctx context.Context, id string) (bool, error)
- func (s *Store) CreateApproval(ctx context.Context, a Approval) (Approval, error)
- func (s *Store) CreateSecret(ctx context.Context, r SecretReq) (SecretReq, error)
- func (s *Store) CreateThread(ctx context.Context, title string) (Thread, error)
- func (s *Store) DeleteThread(ctx context.Context, id string) error
- func (s *Store) GetApproval(ctx context.Context, id string) (Approval, bool, error)
- func (s *Store) GetSecret(ctx context.Context, id string) (SecretReq, bool, error)
- func (s *Store) ListThreads(ctx context.Context, limit int) ([]Thread, error)
- func (s *Store) Messages(ctx context.Context, threadID, before string, limit int) ([]Message, bool, error)
- func (s *Store) Thread(ctx context.Context, id string) (Thread, bool, error)
- func (s *Store) UpdateApproval(ctx context.Context, a Approval) error
- func (s *Store) UpdateParts(ctx context.Context, messageID string, parts json.RawMessage) error
- func (s *Store) UpdateSecretStatus(ctx context.Context, id, status string) error
- type Thread
- type TurnContext
Constants ¶
const DescribeCollectionRoute = "/collections/describe"
DescribeCollectionRoute is the console's "Describe a collection" drawer. Its turns build one smart collection with live drafts the owner watches.
Variables ¶
var ErrThreadBusy = errors.New("a turn is already running in this conversation")
ErrThreadBusy reports a second concurrent turn in one conversation.
Functions ¶
func OwnerPrincipal ¶
OwnerPrincipal is the console owner principal. The mount in internal/app/agent.go sits behind owner auth.
func ValidateToolInput ¶
func ValidateToolInput(schema json.RawMessage, input any) error
ValidateToolInput validates inputs for callers that invoke catalogue tools directly.
Types ¶
type Approval ¶
type Approval struct {
ID, ThreadID, MessageID, ToolName string
Input map[string]any
Category, Description string
Details json.RawMessage
Status, DecisionNote string
FailureReason string
}
Approval is one durable proposal awaiting (or past) a decision.
type Message ¶
type Message struct {
ID string `json:"id"`
Role string `json:"role"`
Parts json.RawMessage `json:"parts"`
CreatedAt string `json:"createdAt,omitempty"` // RFC3339, for AgentPanel
// contains filtered or unexported fields
}
Message is one stored UI message.
type Model ¶
type Model interface {
StreamTools(ctx context.Context, req llm.ToolRequest) (<-chan llm.Event, error)
Enabled() bool
ProviderID() string
ModelName() string
ToolsSupported() (bool, string)
}
Model is the streaming tool-calling model client (*llm.Client, or a fake).
type Options ¶
type Options struct {
Model Model
Catalogue *tools.Catalogue
Store *Store
Logger *slog.Logger
// MaxSteps is clamped to 2..32; default 12.
MaxSteps int
// TurnTimeout bounds one turn; default 5 minutes.
TurnTimeout time.Duration
// TokenBudget bounds summed provider tokens per turn; default 200k.
TokenBudget int
// Heartbeat is how often a quiet turn stream sends a keep-alive
// comment; default 15 seconds.
Heartbeat time.Duration
}
Options build a Service.
type SecretReq ¶
type SecretReq struct {
ID, ThreadID, MessageID string
ProviderLabel string
CredentialLabel string
Purpose, HelpURL string
Status string
}
SecretReq is one durable credential request (never the value).
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service runs Ask Ether turns.
func (*Service) CancelTurn ¶
CancelTurn cancels a running turn by its assistant message id (turn id).
func (*Service) ContinueAfterApproval ¶
func (s *Service) ContinueAfterApproval(ctx context.Context, p tools.Principal, appr Approval, tc TurnContext) (bool, error)
ContinueAfterApproval runs the follow-up turn the approval card promises: the agent picks up with the owner's decision. It is skipped when another turn is already running in the conversation.
func (*Service) DecideApproval ¶
func (s *Service) DecideApproval(ctx context.Context, p tools.Principal, id, decision, note string) (Approval, error)
DecideApproval approves or rejects a stored proposal. Approval re-runs the tool's Execute with the stored input to rebuild the proposal closure, then applies it. The stored part is patched to the final status.
func (*Service) RunTurn ¶
func (s *Service) RunTurn(ctx context.Context, p tools.Principal, threadID, prompt string, tc TurnContext, emit func(Chunk) error) (string, string, error)
RunTurn runs one turn, emitting stream chunks. It returns the thread id and the assistant message id (the turn id used for cancellation).
type Status ¶
type Status struct {
Enabled bool `json:"enabled"`
Provider string `json:"provider"`
Model string `json:"model"`
ToolsSupported bool `json:"toolsSupported"`
Reason string `json:"reason"`
}
Status reports whether Ask Ether can run.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists threads, messages, approvals, secret requests and audit.
func (*Store) AllMessages ¶
AllMessages returns every message of a thread (loop history; capped by caller).
func (*Store) AppendMessage ¶
func (s *Store) AppendMessage(ctx context.Context, threadID, role string, parts json.RawMessage) (Message, error)
AppendMessage appends a message and returns it with its sequence.
func (*Store) Audit ¶
func (s *Store) Audit(ctx context.Context, threadID, tool, principal, status, mappedErr string, dur time.Duration) error
Audit records one tool call. Inputs are never stored.
func (*Store) ClaimApproval ¶
ClaimApproval atomically prevents multiple decisions or applications, even when requests arrive at different cluster nodes.
func (*Store) CreateApproval ¶
func (*Store) CreateSecret ¶
func (*Store) CreateThread ¶
func (*Store) GetApproval ¶
func (*Store) ListThreads ¶
func (*Store) Messages ¶
func (s *Store) Messages(ctx context.Context, threadID, before string, limit int) ([]Message, bool, error)
Messages returns up to limit messages of a thread, oldest first. When before names a message id, only messages before it are considered (the latest page ending before that message).
func (*Store) UpdateApproval ¶
func (*Store) UpdateParts ¶
UpdateParts replaces a message's parts (streaming assistant message).
type Thread ¶
type Thread struct {
ID string `json:"id"`
Title string `json:"title"`
CreatedAt int64 `json:"createdAt"` // unix milliseconds
UpdatedAt int64 `json:"updatedAt"`
}
Thread is one conversation.
type TurnContext ¶
type TurnContext struct {
Route string `json:"route"`
// MediaType is the kind of titles the owner picked on pages that ask
// (movie, show or mixed); empty elsewhere.
MediaType string `json:"mediaType,omitempty"`
Record *struct {
Type string `json:"type"`
ID string `json:"id"`
} `json:"record,omitempty"`
}
TurnContext is where the owner is in the console.
Source Files
Directories