Documentation
¶
Overview ¶
Package persistent runs a persistent agent: a built-in QuickAgent the runner keeps between the person's conversations. Each start-to-stop is a segment, an ordinary session of the engine with its own run id, receipts and envelope; what outlives a segment is the agent's state folder under the runner home and its two volumes, which carry no run label, so neither a segment's teardown nor the sweep of a dead run removes them.
One process owns a running agent, its supervisor: the desktop in-process, or the detached process `agentry agent start` launches. The supervisor holds the agent's owner lock and serves its owner socket, through which a chat in another process attaches, sends turns, reads the status and stops it. A second supervisor is refused, naming the holder.
Index ¶
- Constants
- Variables
- func AccountEntryID(host string) string
- func AccountGuidance(kind spec.GitHostKind, own bool) string
- func AccountKeychainAccount(host, user string) string
- func AddedSkillsPath(home, name string) string
- func AgreeToRoster(home string, a Agent, client string) error
- func AppSocketPath(home, name string) string
- func ApplyChange(home string, a Agent, c *Config, ch Change) (restart bool, err error)
- func Attach(ctx context.Context, home, name string, history []session.Event) (session.Session, error)
- func CalendarEntryID(name string) string
- func CalendarFeedReadableWith(ctx context.Context, address, session string) (string, int, error)
- func CalendarKeychainAccount(agent, name string) string
- func CalendarService(host string) string
- func CalendarSession(keys Secrets, agent, name string) (string, error)
- func CalendarSessionAccount(agent, name string, n int) string
- func CheckGoogleClient(b []byte) error
- func CheckMicrosoftClient(id string) error
- func CheckSecretName(name string) error
- func CheckSecretValue(v string) error
- func CheckShareFolder(home, dir string) error
- func DataVolume(name string) string
- func DataVolumeIn(home, name string) string
- func Dir(home, name string) string
- func DiscardSkill(home string, a Agent, name string) error
- func ForgetCalendarFeed(keys Secrets, agent, name string) error
- func ForgetCalendarSession(keys Secrets, agent, name string) error
- func HistoryEvents(entries []Entry) []session.Event
- func HomeID(home string) string
- func HomeMalwareCheck(home string) bool
- func ImageKeyringAccount(agent, key string) string
- func ImageServerEntryID(key string) string
- func ImageSwitchEntryID(key, sw string) string
- func ImageVolumeIn(home, name, key string) string
- func KeepCalendarSession(keys Secrets, agent, name, session string) error
- func KnowledgeEntryID(pack string) string
- func LogPath(home, name string) string
- func MemoryVolumeIn(home, name string) string
- func PortEntryID(name string) string
- func ReadSecrets(keys Secrets, agent string, names []string) (map[string]string, error)
- func RecordConsent(r Roster, c *Config)
- func RequestInterrupt(ctx context.Context, home, name string) (stopped bool, err error)
- func Reset(ctx context.Context, home, name string, d dockerx.Client) error
- func ResetAgent(ctx context.Context, home, name string, d dockerx.Client) error
- func ResetHistory(ctx context.Context, home, name string, d dockerx.Client) error
- func SaveConfig(home, name string, c Config) error
- func SecretAccount(agent, name string) string
- func SecretEntryID(name string) string
- func ServerEntryID(srv manifest.MCPServer) string
- func ServerMaySeeShare(srv manifest.MCPServer) error
- func ServerShareID(srv manifest.MCPServer) string
- func ServerWritesID(srv manifest.MCPServer) string
- func SessionVolume(name string) string
- func SessionVolumeIn(home, name string) string
- func SetMailProvider(home string, a Agent, client, key string, on bool) error
- func ShareFolder(a Agent, c Config) (string, error)
- func SharedVolumes(ctx context.Context, d dockerx.Client, name string) []string
- func SignInCalendarFeed(ctx context.Context, address string, progress func(string)) (session, calName string, events int, err error)
- func SkillEntryID(name string) string
- func SocketPath(home, name string) string
- func Suggested(a Agent, key string) (manifest.MCPServer, error)
- func Suggestions(a Agent, c Config) []offer.Suggestion
- type AddedSkill
- type Agent
- type AppLinkHandler
- type Applied
- type CalendarFeed
- type CalendarFeedState
- type Change
- type Command
- type Compacted
- type Config
- type ConsentError
- type Conversation
- type Cron
- type DevHost
- type Entry
- type EntryKind
- type EntryState
- type Exported
- type GitAccount
- type Google
- type HeldError
- type Holder
- type HostReady
- type ImageSignIn
- type InstallServer
- type Interrupted
- type KeychainSecrets
- type MailProviderState
- type Microsoft
- type Options
- type Owner
- type Packs
- type Port
- type Reply
- type Roster
- func BuildRoster(a Agent, c Config, applied *Applied) Roster
- func BuildRosterUnder(a Agent, c Config, applied *Applied, malwareCheck bool) Roster
- func Configure(ctx context.Context, home string, a Agent, client string, ch Change) (r Roster, running bool, err error)
- func QueryRoster(ctx context.Context, home, name string) (Roster, error)
- func RequestChange(ctx context.Context, home, name string, ch Change) (Roster, error)
- type RosterEntry
- type Secrets
- type ServerFailure
- type SkillCheck
- type Stage
- type Status
- type Stopped
- type StoredSecret
- type Supervisor
- func (s *Supervisor) Change(ch Change) (Roster, error)
- func (s *Supervisor) ChangeTask(op TaskOp) ([]Task, error)
- func (s *Supervisor) Compact(ctx context.Context) (Compacted, error)
- func (s *Supervisor) Done() <-chan struct{}
- func (s *Supervisor) Interrupt(ctx context.Context) error
- func (s *Supervisor) Roster() Roster
- func (s *Supervisor) Send(ctx context.Context, text string) error
- func (s *Supervisor) Status() Status
- func (s *Supervisor) Stop(ctx context.Context) (*receipt.Envelope, error)
- func (s *Supervisor) Subscribe() (<-chan session.Event, func())
- func (s *Supervisor) Tasks() ([]Task, error)
- type Switch
- type Task
- func ChangeTaskOf(ctx context.Context, home string, a Agent, client string, op TaskOp) ([]Task, bool, error)
- func RequestTaskChange(ctx context.Context, home, name string, op TaskOp) ([]Task, error)
- func RequestTasks(ctx context.Context, home, name string) ([]Task, error)
- func TaskList(home string, a Agent) ([]Task, error)
- func TasksOf(ctx context.Context, home string, a Agent) ([]Task, bool, error)
- type TaskOp
- type TaskSpec
- type Tasks
- func (ts *Tasks) AddTask(spec TaskSpec, now time.Time) (Task, error)
- func (ts *Tasks) ApplyOp(op TaskOp, now time.Time) error
- func (ts Tasks) Listed(now time.Time) []Task
- func (ts *Tasks) RemoveTask(id string) (Task, error)
- func (ts *Tasks) UpdateTask(id string, spec TaskSpec, now time.Time) (Task, error)
- type UpkeepRecord
- type Usage
Constants ¶
const ( MaxNameBytes = 64 MaxPersonalityBytes = 32 << 10 )
The bounds of what a person writes for the agent.
const ( EntryCommands = "commands" EntryEgress = "egress" EntryBrowser = "browser" EntryDevHost = "devhost" // EntryDependencyScan is dependency_scan, OSV-Scanner offline. EntryDependencyScan = "dependency-scan" )
The Coding agent's entries.
const ( ClientCLI = "cli" ClientDesktop = "desktop" )
The clients that own a running agent.
const ( TenantConsumers = "consumers" TenantOrganizations = "organizations" )
The tenants a sign-in is made on: personal Microsoft accounts (Outlook.com, Hotmail, Live) on consumers, work and school accounts on organizations; a tenant's own id names one organization.
const ( GrantedByBuiltin = "built-in" GrantedByYou = "you" )
Who granted an entry.
const ( EntryData = "data" )
The ids of the folder entries.
const ( MaxSecrets = 32 MinSecretBytes = 8 MaxSecretBytes = 16 << 10 )
The bounds of an agent's stored secrets. A value is at least MinSecretBytes so the engine's redactor, which leaves shorter values alone, masks it wherever it would appear.
const ( SkillCheckedClamAV = "clamav" SkillUnchecked = "unchecked" )
How an added skill was checked when it was added.
const ( RefusedBusy = protocol.RefusedBusy RefusedEnded protocol.Refusal = "ended" RefusedChange protocol.Refusal = "change" RefusedConsent protocol.Refusal = "consent" RefusedTask protocol.Refusal = "task" RefusedCompact protocol.Refusal = "compact" RefusedInterrupt protocol.Refusal = "interrupt" )
The refusal classes the owner socket adds to the session protocol's.
const ( MaxTasks = 25 MinTaskInterval = 15 * time.Minute MaxTaskFiresPerDay = 96 MaxTaskNameBytes = 80 MaxInstruction = 4096 )
The task limits: how many an agent keeps, how often one may fire, how many fires a day all of them may make, and the sizes of a name and an instruction.
const ( TaskOn = "on" TaskPaused = "paused" )
Task states.
const ( TaskOpPause = "pause" TaskOpResume = "resume" TaskOpRemove = "remove" )
The person's task operations.
const ( UpkeepIdle = "idle" UpkeepInUse = "in-use" UpkeepManual = "manual" // UpkeepCold compacts before a person's message that comes after the // harness's prompt cache has expired, when the history is re-sent // uncached anyway. UpkeepCold = "cold" // UpkeepConsolidate is the daily tidy of the memory, which swaps // nothing. UpkeepConsolidate = "consolidate" )
The triggers a compaction records, and a consolidation's.
const ( // HandoffKeyed: the answer held the handoff's key lines, and the // handoff is the text from the first of them on. HandoffKeyed = "keyed" // HandoffProse: the answer held none, and the handoff is the whole // answer. Some models write the handoff as a paragraph; it still says // what the conversation left open. HandoffProse = "prose" )
The forms of a handoff, as its record says them.
const ( // SwapInSegment: the running harness started the new conversation. SwapInSegment = "in-segment" // SwapSegment: the segment ended and the next started in a new // conversation. SwapSegment = "segment" // SwapInPlace: the running harness compacted the conversation in // place, which stays the same conversation (the record's Swapped is // false). SwapInPlace = "in-place" )
How a compaction swapped the conversation, as its record says it.
const CalendarSignInTimeout = 10 * time.Minute
CalendarSignInTimeout bounds a browser sign-in.
const ConfigVersion = 11
ConfigVersion is the version of config.yaml this build writes. Version 2 added the share folder, the person's servers and packs, the switches and the consents, version 3 the Coding agent's dev server, version 4 its published ports, version 5 the skills the person added, version 6 the secrets they stored, version 7 the Coding agent's git host accounts and version 8 the sign-ins of the servers it runs from images, version 9 the mail providers the person enabled, version 10 the Assistant's calendar feeds and version 11 their browser sign-ins; a build that reads an older version alone refuses a newer one rather than drop what it does not know on its next save.
const EntryHeartbeat = "heartbeat"
EntryHeartbeat is the roster's switch for an agent's heartbeat.
const EntryMeetings = "meetings"
EntryMeetings is the roster's switch for an agent's meeting tools.
const EntryMemory = "memory"
EntryMemory is the memory's roster entry: fixed on, for an agent that keeps one.
const ( // GoogleSignInTimeout is how long the sign-in waits for the browser. GoogleSignInTimeout = 10 * time.Minute )
The bounds of a Google sign-in.
const KindConversationStart session.Kind = "conversation_start"
KindConversationStart is the transcript's mark of a new conversation the running segment's harness started (a compaction's): Text says why.
const KindSegmentStart session.Kind = "segment_start"
KindSegmentStart is the transcript's mark of a segment's start: Text says whether the conversation continued and, when it did not, why.
const MaxAddedSkills = 50
MaxAddedSkills is how many skills the person may add to an agent.
const MaxPorts = 8
MaxPorts bounds the Coding agent's published ports.
const MicrosoftConnector = "microsoft-365"
MicrosoftConnector is the id of the connector catalogue's entry whose public client is Agentry's own Microsoft app, which the registry serves.
const ( // MicrosoftSignInTimeout is how long the sign-in waits for the person // to enter the code: a device code lasts fifteen minutes. MicrosoftSignInTimeout = 15 * time.Minute )
The bounds of a Microsoft sign-in.
const StateRunning = "running"
StateRunning is a running agent's state.
const TaskMadeByAgent = "agent"
TaskMadeByAgent says the agent registered the task.
Variables ¶
var CalendarFeedReadable = func(ctx context.Context, address string) (string, int, error) { return CalendarFeedReadableWith(ctx, address, "") }
CalendarFeedReadable fetches a calendar feed's address once, as the tools server would, and reads it: it is how an address is checked before it is kept. It returns the calendar's own name, when it gives one, and its events' count. No error repeats the address. A test replaces it.
var ErrBusy = session.ErrBusy
ErrBusy refuses a turn sent while another is in flight.
var ErrCalendarFeedSignIn = fmt.Errorf("%w: it asks for a sign-in", ErrCalendarFeedUnreadable)
ErrCalendarFeedSignIn says a calendar feed's address sent the fetch to a sign-in page: it answers a signed-in browser alone, and is read after a browser sign-in (SignInCalendarFeed). It wraps ErrCalendarFeedUnreadable.
var ErrCalendarFeedUnreadable = errors.New("the calendar feed could not be read")
ErrCalendarFeedUnreadable says a calendar feed's address answered with something that is not a calendar this build can read, or not at all.
var ErrDesktopOnly = errors.New("runs only in Agentry Desktop")
ErrDesktopOnly refuses an agent that runs only in Agentry Desktop.
var ErrFastmailRefused = errors.New("the token was refused by Fastmail: make an API token of the MCP type in Fastmail's settings (Settings → Privacy & Security → Connected apps & API tokens), Read only unless you want changes, and give it again")
ErrFastmailRefused is Fastmail refusing a token.
var ErrNoTask = errors.New("no such task")
ErrNoTask refuses a change to a task the agent does not have.
var ErrNotRunning = errors.New("not running")
ErrNotRunning says no supervisor answers on the agent's socket.
var FastmailTokenAccepted = func(ctx context.Context, token string) error { return fastmailTokenAccepted(ctx, http.DefaultClient, "https://"+assistant.FastmailHost+"/mcp", token) }
FastmailTokenAccepted asks Fastmail's MCP server whether it accepts token: ErrFastmailRefused when it answers that it does not, another error when it could not be asked or answered something else. A test replaces it.
var RealmTenant = func(ctx context.Context, email string) (string, error) { ctx, cancel := context.WithTimeout(ctx, 20*time.Second) defer cancel() req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://login.microsoftonline.com/common/userrealm/"+url.PathEscape(email)+"?api-version=2.1", nil) if err != nil { return "", err } resp, err := http.DefaultClient.Do(req) if err != nil { return "", fmt.Errorf("ask Microsoft which kind of account %s is: %w", email, err) } defer func() { _ = resp.Body.Close() }() if resp.StatusCode != http.StatusOK { return "", fmt.Errorf("ask Microsoft which kind of account %s is: %s", email, resp.Status) } var realm struct { NameSpaceType string `json:"NameSpaceType"` DomainName string `json:"DomainName"` } if err := json.NewDecoder(io.LimitReader(resp.Body, 64<<10)).Decode(&realm); err != nil { return "", fmt.Errorf("read Microsoft's answer for %s: %w", email, err) } return realmTenant(realm.NameSpaceType, realm.DomainName), nil }
RealmTenant is the tenant an address signs in on, from Microsoft's own home-realm answer for it: an address whose domain Microsoft federates to its consumer sign-in (live.com), or that no organization holds, is a personal account's; one an organization holds signs in on organizations. A test replaces it.
Functions ¶
func AccountEntryID ¶ added in v0.6.999
AccountEntryID is a git host account's roster id.
func AccountGuidance ¶ added in v0.6.999
func AccountGuidance(kind spec.GitHostKind, own bool) string
AccountGuidance is what the person is told before giving the agent an account: for one of its own, why and how to share repositories with it; for theirs, what the token lets it do and how to bound it.
func AccountKeychainAccount ¶ added in v0.6.999
AccountKeychainAccount is the keychain account a git host account's token is kept under.
func AddedSkillsPath ¶
AddedSkillsPath is where the agent's added skills are kept, one folder each.
func AgreeToRoster ¶
AgreeToRoster records the person's agreement to everything the agent's roster has on, as a start asks for it: under the owner lock, so a running agent is refused.
func AppSocketPath ¶
AppSocketPath is the socket an agent's supervisor answers its app link on, beside its owner socket.
func ApplyChange ¶
ApplyChange applies ch to c for the agent a, under the runner home home. It answers whether the change alters what a segment is given, so a running agent's next turn starts a new segment, and refuses with a ConsentError a change that turns on what the person has not agreed to, unless ch.Consent says they have. The sentences it asks with say the malware check is off, as BuildRoster's do.
func Attach ¶
func Attach(ctx context.Context, home, name string, history []session.Event) (session.Session, error)
Attach connects a chat to the running agent: a session.Session whose events are the segment's from now on, after history, and whose End leaves the agent running. A file is never added this way.
func CalendarEntryID ¶ added in v0.6.999
CalendarEntryID is a calendar feed's roster id.
func CalendarFeedReadableWith ¶ added in v0.6.999
CalendarFeedReadableWith is CalendarFeedReadable, sending a browser sign-in (SignInCalendarFeed's session, or empty for none) with the fetch. A redirect to a sign-in page is ErrCalendarFeedSignIn. No error repeats the address or the sign-in.
func CalendarKeychainAccount ¶ added in v0.6.999
CalendarKeychainAccount is the keychain account a calendar feed's address is kept under.
func CalendarService ¶ added in v0.6.999
CalendarService names the service a feed's host belongs to, or "".
func CalendarSession ¶ added in v0.6.999
CalendarSession reads a feed's browser sign-in back from the keychain.
func CalendarSessionAccount ¶ added in v0.6.999
CalendarSessionAccount is the keychain account of the n-th part (from 1) of a calendar feed's browser sign-in.
func CheckGoogleClient ¶ added in v0.6.999
CheckGoogleClient refuses a file that is not a Google Cloud OAuth client for a desktop app: a JSON object with an "installed" client naming its id and secret. A web application's client cannot sign in to a redirect on 127.0.0.1, and a service account is no client at all.
func CheckMicrosoftClient ¶ added in v0.6.999
CheckMicrosoftClient refuses an Entra application id that is not one, or that is Softeria's own.
func CheckSecretName ¶
CheckSecretName refuses a name that is not an environment variable's ([A-Z][A-Z0-9_]{0,63}), or one the runner and the programs it runs set themselves (spec.CheckStoredSecretName).
func CheckSecretValue ¶
CheckSecretValue refuses a value the segment cannot carry or mask: one shorter than MinSecretBytes or longer than MaxSecretBytes, one that is not UTF-8 text, and one holding a line break or another control character, which the gateway's secrets file cannot hold.
func CheckShareFolder ¶
CheckShareFolder refuses a share folder that would hand the agent more than the person meant: a path that is not absolute and clean, one reached through a link, a filesystem root, the home folder or a folder holding it, a hidden folder of the home folder (where keys and settings live) or one beneath it, the runner's own folders or the configuration's, a folder that holds any of them, and the system's folders. A path holding a colon beyond a drive's is refused too: the gateway's bind lists are joined with one. A folder that does not exist yet passes, beneath a parent that does.
func DataVolume ¶
DataVolume is the agent's data volume under the earlier name.
func DataVolumeIn ¶
DataVolumeIn is the agent's volume for its own files in the runner home home.
func DiscardSkill ¶
DiscardSkill removes an added skill's files once it is not on the agent's roster: after it is removed, or after the change that would have added it was refused.
func ForgetCalendarFeed ¶ added in v0.6.999
ForgetCalendarFeed removes a feed's address and its browser sign-in from the keychain.
func ForgetCalendarSession ¶ added in v0.6.999
ForgetCalendarSession removes a feed's browser sign-in from the keychain.
func HistoryEvents ¶
HistoryEvents is the transcript as session events a chat shows before the live ones: each turn, tool call and error, and a line where each segment began.
func HomeID ¶
HomeID identifies a runner home among the homes that use one container engine: a short hash of its absolute path, links followed. The volumes of the agent a home runs carry it in their names and a label, so two homes (two people on one computer, a scratch home beside the person's own) never share a conversation or a data volume. A home moved to another path is a different home to the engine: its agents start on volumes of their own.
func HomeMalwareCheck ¶
HomeMalwareCheck is the malware-check setting of the policy in the runner home home, for a roster built while the agent is not running; off when that policy is missing or unreadable, as a new one has it.
func ImageKeyringAccount ¶ added in v0.6.999
ImageKeyringAccount is the keychain account of an image server's own secret: its file keyring's password, made at its first sign-in.
func ImageServerEntryID ¶ added in v0.6.999
ImageServerEntryID is an image server's roster id.
func ImageSwitchEntryID ¶ added in v0.6.999
ImageSwitchEntryID is the roster id of an image server's switch.
func ImageVolumeIn ¶ added in v0.6.999
ImageVolumeIn is the volume of the agent's image server key in the runner home home.
func KeepCalendarSession ¶ added in v0.6.999
KeepCalendarSession keeps a feed's browser sign-in (SignInCalendarFeed's session, a list of cookies) in the keychain, in as many parts as it needs, and removes any part a longer one before it left.
func KnowledgeEntryID ¶
KnowledgeEntryID is a pack's roster id.
func MemoryVolumeIn ¶
MemoryVolumeIn is the agent's memory volume in the runner home home.
func PortEntryID ¶
PortEntryID is the roster id of a published port.
func ReadSecrets ¶
ReadSecrets reads the values of the named secrets of the agent from keys: every one must be there.
func RecordConsent ¶
RecordConsent records the person's agreement to every entry that is on.
func RequestInterrupt ¶ added in v0.6.1004
RequestInterrupt asks the running agent's supervisor to stop the turn in flight, and returns once it has ended: stopped is false when no turn was in flight.
func Reset ¶
Reset puts a stopped agent back to its defaults, as it was when first enabled: its volumes, its transcript, its lifetime usage, its share verdicts, its share mirror, its installed servers, its tasks, the skills the person added, the secrets they stored and the git host accounts they gave it, from the keychain too, are removed; its configuration keeps only whether it is enabled, so its built-in skills are on again and its next start is a first segment that asks its consents again. The segments' receipts and the files in its share folder, which are the person's, are kept; so is a dev server's sign-in in the keychain, where a schedule of the same host may read it. It refuses a running agent, and holds the agent's lock while it works so none starts meanwhile. The containers of a segment whose supervisor died still hold the session volume, so they are swept first.
func ResetAgent ¶ added in v0.6.999
ResetAgent puts a stopped agent's choices back to their defaults and removes its history, as Reset does, but keeps the credentials the person gave it: its stored secrets, its git host accounts and its image servers' sign-ins stay, with their keychain entries and volumes, switched off and not agreed to, so turning one on asks again and needs no new set-up. Its share folder's location and its usage stay too. Only an agent that resets in parts has it.
func ResetHistory ¶ added in v0.6.999
ResetHistory removes what a stopped agent did and keeps what the person chose: its conversation, files and memory volumes, its transcript, tasks, share verdicts, share text and share mirror go; its configuration, its consents, its installed servers and added skills, its secrets and sign-ins (their keychain entries and volumes) and its usage stay. Its next start is a new conversation that asks nothing again. Only an agent that resets in parts has it.
func SaveConfig ¶
SaveConfig writes the agent's config.yaml (0600), replacing it whole.
func SecretAccount ¶
SecretAccount is the keychain account a stored secret's value is kept under, apart from every other agent's and from the person's other keys.
func SecretEntryID ¶
SecretEntryID is a stored secret's roster id.
func ServerEntryID ¶
ServerEntryID is a server's roster id: its store id, which names its package or its address.
func ServerMaySeeShare ¶
ServerMaySeeShare refuses a server the share is never given to: a remote server, which is another party's; a package server that reaches a host, which could send the person's files there; and one that signs in by OAuth, which a persistent agent cannot be given.
func ServerShareID ¶
ServerShareID is the id of a server's switch that lets it see the agent's share folder: its roster id and ":share". It is a switch of the server's entry, not an entry of its own: it changes what the server's sentence says.
func ServerWritesID ¶ added in v0.6.999
ServerWritesID is the roster id of an offered server's writes entry.
func SessionVolume ¶
SessionVolume and DataVolume are the legacy names of the agent's two volumes, by the agent alone: every runner home on one engine could use the same two. A home that has run the agent keeps its conversation by copying them into its own volumes at its next start, and leaves them be.
func SessionVolumeIn ¶
SessionVolumeIn is the agent's volume for the harness's conversation store in the runner home home, and DataVolumeIn the agent's volume for its own files.
func SetMailProvider ¶ added in v0.6.999
SetMailProvider enables or disables one of a stopped agent's mail providers. Disabling keeps the provider's sign-in, its keychain entries and its volume, and its switches and agreements as they were; enabling it again puts its servers back on the roster as they were left. It is refused while the agent runs, whose segment holds the servers' volumes, and holds the agent's lock meanwhile so none starts.
func ShareFolder ¶
ShareFolder is the agent's share folder: config.yaml's, else its default under ~/agentry.
func SharedVolumes ¶
SharedVolumes are the volumes of the agent that exist under the legacy names (SessionVolume, DataVolume), which every runner home on the engine could use. A reset leaves them, as another home may still need them; nothing else removes them. A failed listing answers none.
func SignInCalendarFeed ¶ added in v0.6.999
func SignInCalendarFeed(ctx context.Context, address string, progress func(string)) (session, calName string, events int, err error)
SignInCalendarFeed opens a browser window at a calendar feed's address, where the person signs in to the account the calendar belongs to, and, once the window has closed, returns the browser's sign-in (the cookies it sends to the address, as KeepCalendarSession keeps them) if the address answers with a calendar, with that calendar's name and events' count. progress, when set, is told what it waits for. No error repeats the address or the sign-in.
func SocketPath ¶
SocketPath is the agent's owner socket. It lives beside the runs' sockets under the runner home rather than in the state folder, so its path stays short of the kernel's limit for a socket's name.
func Suggested ¶ added in v0.6.999
Suggested is the server the agent suggests under key, to add as the person's own.
func Suggestions ¶ added in v0.6.999
func Suggestions(a Agent, c Config) []offer.Suggestion
Suggestions are the servers the agent suggests that it does not have.
Types ¶
type AddedSkill ¶
type AddedSkill struct {
Name string `yaml:"name" json:"name"`
Description string `yaml:"description" json:"description"`
Digest string `yaml:"digest" json:"digest"`
Check string `yaml:"check" json:"check"`
Added time.Time `yaml:"added" json:"added"`
}
AddedSkill is a skill the person added: its name and description from its SKILL.md, the digest of its files as they were checked, how they were checked, and when.
func InstallSkill ¶
func InstallSkill(ctx context.Context, home string, a Agent, src string, check SkillCheck) (AddedSkill, error)
InstallSkill takes the skill at src, a folder or a .zip on this computer, holds it to the skill bounds, runs check over its files and keeps it among the agent's added skills, not yet on its roster: the change that adds it (Change.AddSkill) does that, and asks the person first. A skill of a name the agent has already is refused.
type Agent ¶
type Agent struct {
// Name is the agent's name, its built-in's name: what the commands and
// the state folder are keyed by.
Name string
// Title is how the agent is named to a person until they name it.
Title string
// DesktopOnly says the agent runs only in Agentry Desktop; the CLI
// lists it and refuses to start, chat with or configure it.
DesktopOnly bool
// Builtin is the package it runs.
Builtin localrun.Builtin
ShareName string
}
Agent is one persistent agent this build knows.
func Agents ¶
func Agents() []Agent
Agents are the persistent agents this build knows, in the order they are listed.
func (Agent) DisplayName ¶
DisplayName is the name the agent goes by: the person's for it, else its title.
type AppLinkHandler ¶
AppLinkHandler answers an app link's tool call other than self_configure.
type Applied ¶
type Applied struct {
On []string `json:"on"`
}
Applied is what a segment was given: the ids of the roster's entries that were on.
func Apply ¶
func Apply(ctx context.Context, home string, a Agent, c Config, r Roster, open Packs, ready HostReady, keys Secrets) (g localrun.Grants, applied Applied, done func(), err error)
Apply turns the roster into what a segment is given: the share folder when it is on, the packs that are on and the servers that are on and ready (a server the agent's store does not hold yet, one being installed and one whose install failed are left out: serverReady), and the Coding agent's grant, its dev server readied by ready, the stored secrets that are on, their values read from keys, and its git host accounts that are on, their tokens read from keys. It is the one place a switch takes effect, so the tools server's spec, the gateway's allowlist, catalogue and secrets file, the bind lists and the driver's permit set, all compiled and rendered from what it returns, agree. applied names what the segment is given. done closes the packs it opened.
type CalendarFeed ¶ added in v0.6.999
type CalendarFeed struct {
Name string `yaml:"name" json:"name"`
// Host is the host the address names, in lower case.
Host string `yaml:"host" json:"host"`
// Set is when the address was last set, so setting it again reaches the
// next turn.
Set time.Time `yaml:"set" json:"set"`
// SignedIn says a browser sign-in is kept for the feed in the keychain
// (CalendarSessionAccount).
SignedIn bool `yaml:"signedIn,omitempty" json:"signedIn,omitempty"`
}
CalendarFeed is one of the Assistant's calendar feeds, as config.yaml keeps it.
type CalendarFeedState ¶ added in v0.6.999
type CalendarFeedState struct {
Name string `json:"name"`
Host string `json:"host"`
// Service names the service the host belongs to, or is empty.
Service string `json:"service,omitempty"`
On bool `json:"on"`
Set time.Time `json:"set"`
// SignedIn says a browser sign-in is kept for the feed.
SignedIn bool `json:"signedIn,omitempty"`
// Entry is the feed's roster id.
Entry string `json:"entry"`
}
CalendarFeedState is one calendar feed as a client shows it: never its address.
func CalendarFeeds ¶ added in v0.6.999
func CalendarFeeds(a Agent, c Config) []CalendarFeedState
CalendarFeeds are the agent's calendar feeds as a client shows them.
type Change ¶
type Change struct {
// Name and Personality are the person's for the agent; "" clears one.
Name *string `json:"name,omitempty"`
Personality *string `json:"personality,omitempty"`
Share *string `json:"share,omitempty"`
// RunOnStart starts the agent when its client starts.
RunOnStart *bool `json:"runOnStart,omitempty"`
// AddServer adds an MCP server, on; RemoveServer removes one by its
// roster id or its store id.
AddServer *manifest.MCPServer `json:"addServer,omitempty"`
RemoveServer string `json:"removeServer,omitempty"`
// AddKnowledge adds a pack of the local store by name, on;
// RemoveKnowledge removes one.
AddKnowledge string `json:"addKnowledge,omitempty"`
RemoveKnowledge string `json:"removeKnowledge,omitempty"`
// Switch turns a roster entry on or off.
Switch *Switch `json:"switch,omitempty"`
// DevHost saves the Coding agent's dev server, on; ClearDevHost removes
// it. Its sign-in is saved in the keychain before, by the client that
// asked the person for it.
DevHost *DevHost `json:"devHost,omitempty"`
ClearDevHost bool `json:"clearDevHost,omitempty"`
// AddPort publishes one of the Coding agent's ports, on; RemovePort
// takes one away by its name.
AddPort *Port `json:"addPort,omitempty"`
RemovePort string `json:"removePort,omitempty"`
// AddSkill adds a skill InstallSkill kept, on; RemoveSkill takes away
// one the person added, by its name. A built-in skill is switched, not
// removed.
AddSkill *AddedSkill `json:"addSkill,omitempty"`
RemoveSkill string `json:"removeSkill,omitempty"`
// SetSecret records a secret the person stored, on, its value already
// kept in the keychain by the client that asked them for it, or one set
// again; RemoveSecret takes one away, by its name. Neither carries a
// value.
SetSecret *StoredSecret `json:"setSecret,omitempty"`
RemoveSecret string `json:"removeSecret,omitempty"`
// SetAccount records one of the Coding agent's git host accounts, on,
// its token already kept in the keychain by the client that asked for
// it, or one whose token was set again; RemoveAccount takes one away,
// by its host. Neither carries a token.
SetAccount *GitAccount `json:"setAccount,omitempty"`
RemoveAccount string `json:"removeAccount,omitempty"`
// SetCalendarFeed records one of the Assistant's calendar feeds, on,
// its address already kept in the keychain by the client that asked for
// it (CalendarKeychainAccount), or one whose address was set again;
// RemoveCalendarFeed takes one away, by its name. Neither carries an
// address.
SetCalendarFeed *CalendarFeed `json:"setCalendarFeed,omitempty"`
RemoveCalendarFeed string `json:"removeCalendarFeed,omitempty"`
// Consent says the person consented to what this change turns on, as
// the lines a ConsentError listed say it.
Consent bool `json:"consent,omitempty"`
}
Change is one change to an agent's configuration; a field left unset is left as it is.
type Command ¶
type Command struct {
Attach *struct{} `json:"attach,omitempty"`
Send *protocol.Send `json:"send,omitempty"`
Status *struct{} `json:"status,omitempty"`
Roster *struct{} `json:"roster,omitempty"`
Change *Change `json:"change,omitempty"`
Stop *struct{} `json:"stop,omitempty"`
Tasks *struct{} `json:"tasks,omitempty"`
// TaskChange is a person's change to one of the agent's tasks.
TaskChange *TaskOp `json:"task_change,omitempty"`
// Compact asks for an upkeep turn and a compaction now.
Compact *struct{} `json:"compact,omitempty"`
// Interrupt asks for the turn in flight to stop.
Interrupt *struct{} `json:"interrupt,omitempty"`
}
Command is one line a client sends.
type Compacted ¶ added in v0.6.999
type Compacted struct {
Trigger string `json:"trigger"`
// Swapped says a new conversation opened with the handoff.
Swapped bool `json:"swapped"`
// Reason is why nothing was swapped.
Reason string `json:"reason,omitempty"`
ContextTokens int64 `json:"contextTokens,omitempty"`
// Turn is the upkeep turn's number among the segment's user turns.
Turn int `json:"turn,omitempty"`
// FactsBefore and FactsAfter count the memory's fact lines around the
// upkeep turn: -1 when they were not counted, because the memory could
// not be read or the agent keeps none.
FactsBefore int `json:"factsBefore"`
FactsAfter int `json:"factsAfter"`
HandoffBytes int `json:"handoffBytes,omitempty"`
// HandoffCut says the handoff was longer than its bound and was cut.
HandoffCut bool `json:"handoffCut,omitempty"`
// HandoffForm is the handoff's form (HandoffKeyed, HandoffProse).
HandoffForm string `json:"handoffForm,omitempty"`
// Swap is how the new conversation started (SwapInSegment,
// SwapSegment), and SwapMillis how long that took.
Swap string `json:"swap,omitempty"`
SwapMillis int64 `json:"swapMillis,omitempty"`
}
Compacted is what a compaction did, as the owner socket answers it.
type Config ¶
type Config struct {
Version int `yaml:"version" json:"version"`
// Enabled says the agent exists for the person: it may be started, and
// a client lists it as theirs. Disabling it keeps its volumes.
Enabled bool `yaml:"enabled" json:"enabled"`
// RunOnStart starts the agent when its client starts.
RunOnStart bool `yaml:"runOnStart" json:"runOnStart"`
// DisplayName and Personality are the person's for the agent.
DisplayName string `yaml:"displayName,omitempty" json:"displayName,omitempty"`
Personality string `yaml:"personality,omitempty" json:"personality,omitempty"`
// Conversation is the harness's conversation the last segment was in.
Conversation *Conversation `yaml:"conversation,omitempty" json:"conversation,omitempty"`
// Segments counts the segments started.
Segments int `yaml:"segments" json:"segments"`
// ~/agentry/<ShareName>.
Share string `yaml:"share,omitempty" json:"share,omitempty"`
// Servers are the MCP servers the person added, in the manifest's own
// shape; each is a roster entry.
Servers []manifest.MCPServer `yaml:"servers,omitempty" json:"servers,omitempty"`
// Knowledge names the knowledge packs the person added, from the local
// store; each is a roster entry.
Knowledge []string `yaml:"knowledge,omitempty" json:"knowledge,omitempty"`
// Switches are the roster's switches the person set, by entry id; an
// entry with none takes its default.
Switches map[string]bool `yaml:"switches,omitempty" json:"switches,omitempty"`
// Consented records, by entry id, the line the person consented to
// when they turned the entry on: turning on an entry whose line differs
// from it, or that has none, asks again.
Consented map[string]string `yaml:"consented,omitempty" json:"consented,omitempty"`
// PersonaGiven is the digest of the name and personality the agent was
// last given, so a change reaches it at the next turn.
PersonaGiven string `yaml:"personaGiven,omitempty" json:"personaGiven,omitempty"`
// DevHost is the Coding agent's dev server, which the person saved; it
// is a roster entry.
DevHost *DevHost `yaml:"devHost,omitempty" json:"devHost,omitempty"`
// Ports are the Coding agent's published ports, which the person
// named; each is a roster entry.
Ports []Port `yaml:"ports,omitempty" json:"ports,omitempty"`
// ServerFailures are the servers the person added whose install failed,
// by roster id: each stays failed, left out of every segment, until the
// person switches it or removes it. A build that does not know the field
// drops it on its next save, and the server is installed again at the
// next start, so the field needs no version of its own.
ServerFailures map[string]ServerFailure `yaml:"serverFailures,omitempty" json:"serverFailures,omitempty"`
// Skills are the skills the person added, as they were checked; each is
// a roster entry, its files in the agent's skills-added folder.
Skills []AddedSkill `yaml:"skills,omitempty" json:"skills,omitempty"`
// Secrets are the secrets the person stored for the agent, by name;
// each is a roster entry, its value in the keychain (SecretAccount).
Secrets []StoredSecret `yaml:"secrets,omitempty" json:"secrets,omitempty"`
// Accounts are the Coding agent's git host accounts, by host; each is a
// roster entry, its token in the keychain (AccountKeychainAccount).
Accounts []GitAccount `yaml:"accounts,omitempty" json:"accounts,omitempty"`
// SignIns are the sign-ins of the agent's image servers, by the
// server's key: who the server answers as once its own sign-in
// finished, never a credential.
SignIns map[string]ImageSignIn `yaml:"signIns,omitempty" json:"signIns,omitempty"`
// MailProviders are the keys of the mail providers the person enabled
// (Builtin.MailProviders): a provider not listed has its servers off
// the roster and out of every segment, and keeps its sign-in.
MailProviders []string `yaml:"mailProviders,omitempty" json:"mailProviders,omitempty"`
// CalendarFeeds are the Assistant's calendar feeds, by name; each is a
// roster entry, its address in the keychain (CalendarKeychainAccount).
CalendarFeeds []CalendarFeed `yaml:"calendarFeeds,omitempty" json:"calendarFeeds,omitempty"`
}
Config is the agent's config.yaml: what the person chose for it, and the conversation its next segment continues.
func LoadConfig ¶
LoadConfig reads the agent's config.yaml; an agent never configured has the zero Config at this version.
type ConsentError ¶
type ConsentError struct {
Agent string
Entries []RosterEntry
}
ConsentError refuses a change, or a start, that turns on entries the person has not consented to on this machine: Entries are their lines.
func (*ConsentError) Error ¶
func (e *ConsentError) Error() string
type Conversation ¶
type Conversation struct {
Adapter string `yaml:"adapter" json:"adapter"`
ID string `yaml:"id" json:"id"`
}
Conversation names a harness's stored conversation: the adapter that stored it, since another harness cannot read it, and its id.
type Cron ¶
type Cron struct {
// contains filtered or unexported fields
}
Cron is a parsed five-field expression.
func (Cron) CloserThan ¶
CloserThan says two of the expression's times in loc, over the year after from, are less than d apart: it fires more often than every d.
func (Cron) Count ¶
Count is how many times the expression names in loc after from and up to to, counting at most limit+1.
type DevHost ¶
type DevHost struct {
// Host is user@host[:port].
Host string `yaml:"host" json:"host"`
// HostKey is the SHA256 fingerprint of the host key the person
// trusted: a segment that finds another refuses.
HostKey string `yaml:"hostKey" json:"hostKey"`
}
DevHost is the Coding agent's dev server, as config.yaml keeps it: where it is and as whom, and the host key the person trusted. Its sign-in is in the system keychain, saved when the person configured it, never here.
type Entry ¶
type Entry struct {
Segment int `json:"segment"`
Run string `json:"run"`
session.Event
// Resumed is set on a segment_start entry.
Resumed *bool `json:"resumed,omitempty"`
}
Entry is one line of the agent's transcript.ndjson: a session event of a segment, as the engine emitted it (redacted), without the harness's raw message.
type EntryKind ¶
type EntryKind string
EntryKind is what a roster entry grants.
The kinds of the Coding agent's entries.
const ( KindFiles EntryKind = "files" KindKnowledge EntryKind = "knowledge" KindServer EntryKind = "server" )
The kinds of entry.
const KindAccount EntryKind = "account"
KindAccount is a git host account's roster entry.
const KindCalendar EntryKind = "calendar"
KindCalendar is a calendar feed's roster entry.
const KindMeetings EntryKind = "meetings"
KindMeetings is the kind of the meetings entry.
const KindMemory EntryKind = "memory"
KindMemory is the memory's roster entry kind.
const KindSecret EntryKind = "secret"
KindSecret is a stored secret's roster entry.
const KindServerSwitch EntryKind = "server-switch"
KindServerSwitch is the kind of an image server's widening switch.
const KindServerWrites EntryKind = "server-writes"
KindServerWrites is the kind of an offered server's writes entry.
const KindSkill EntryKind = "skill"
KindSkill is a skill's roster entry.
const KindTasks EntryKind = "tasks"
KindTasks is the kind of the heartbeat's entry.
type EntryState ¶
type EntryState string
EntryState is a roster entry's state.
const ( StateOn EntryState = "on" StateOff EntryState = "off" // StatePending: switched since the running segment started; the next // turn starts the segment that applies it. StatePending EntryState = "pending" // StateNeedsSignIn: a server that signs in by OAuth, which an agent // cannot be given in this version. StateNeedsSignIn EntryState = "needs-sign-in" // StateInstalling: a server that is on and that the agent's store does // not hold yet. It is installed in the background while the agent runs // without it; once installed it is pending, and the next turn's segment // has it. StateInstalling EntryState = "installing" // StateFailed: a server whose install failed (Reason says why). The // agent runs without it until the person switches it off and on. StateFailed EntryState = "failed" )
The states.
const StateNeedsSetUp EntryState = "needs-set-up"
StateNeedsSetUp: an offered server that is on and waits for a stored secret or a git host account (Reason says which).
type Exported ¶
type Exported struct {
Files int `json:"files"`
Bytes int64 `json:"bytes"`
Skipped int `json:"skipped,omitempty"`
}
Exported is what an export wrote: the files, their bytes, and the entries of the volume it left out because they were neither a file nor a folder.
func ExportMemory ¶
func ExportMemory(ctx context.Context, d dockerx.Client, home string, a Agent, image, runtime string, lim policy.Limits, dir string) (Exported, error)
ExportMemory copies the agent's memory into dir, a new folder it makes beneath a folder that exists: its files and folders as the volume holds them at that moment, read by a one-shot of image (the runner image) under runtime and lim. A link or any other entry is left out, and nothing is written outside dir. A failed export removes dir.
type GitAccount ¶ added in v0.6.999
type GitAccount struct {
// Host is host[:port], in lower case.
Host string `yaml:"host" json:"host"`
Kind spec.GitHostKind `yaml:"kind" json:"kind"`
// Own says the account is the agent's own, rather than the person's.
Own bool `yaml:"own" json:"own"`
User string `yaml:"user" json:"user"`
// Name and Email are the commit identity in a repository on the host.
Name string `yaml:"name" json:"name"`
Email string `yaml:"email" json:"email"`
// Set is when the token was last set, so setting it again reaches the
// next turn.
Set time.Time `yaml:"set" json:"set"`
}
GitAccount is one of the Coding agent's git host accounts, as config.yaml keeps it.
type Google ¶ added in v0.6.999
type Google struct {
Docker dockerx.Client
Home string
Agent Agent
Policy *policy.Policy
RunnerImage string
Keys Secrets
// Client is who calls, ClientCLI or ClientDesktop (ClientCLI when
// unset): the agent's lock names it while the client or the sign-in
// holds the agent.
Client string
// Say is where the steps are narrated.
Say io.Writer
}
Google is what Google Workspace's sign-in needs: the engine, the runner home and the agent, the policy (the server's image, the runner image and the containers' limits), and the keychain.
func (Google) SetClient ¶ added in v0.6.999
SetClient hands the person's Google Cloud OAuth client to gog, which keeps its id on the server's volume and its secret in its encrypted keyring; the file is read here and sent on stdin, never mounted. It is refused while the agent runs, since its server holds the volume.
func (Google) SignIn ¶ added in v0.6.999
func (g Google) SignIn(ctx context.Context, email string, browse func(string) error) (string, error)
SignIn signs Google Workspace in to email with gog's two-step remote flow: the consent's address made with no network, opened in the browser by browse, the browser's redirect caught on 127.0.0.1, and the code exchanged reaching oauth2.googleapis.com alone. It asks for read-only scopes unless the agent has "allow changes" on. It returns the account gog names, and records it only then.
type HeldError ¶
type HeldError struct {
Agent string
Holder *Holder // nil when the holder's record could not be read
}
HeldError is the refusal of a second owner.
type Holder ¶
type Holder struct {
Client string `json:"client"`
PID int `json:"pid"`
Since time.Time `json:"since"`
}
Holder is who owns a running agent: written beside the lock once it is held, and read by a client that is refused it.
func ReadHolder ¶
ReadHolder is the record of the agent's current owner, nil when there is none. A record left by an owner that died is stale; Held says whether the lock is actually held.
type HostReady ¶
HostReady readies the Coding agent's dev server for a segment: its address, its host key held to the pinned one, its sign-in from the keychain. No one is asked anything: a supervisor has no terminal.
type ImageSignIn ¶ added in v0.6.999
type ImageSignIn struct {
Client time.Time `yaml:"client,omitempty" json:"client,omitzero"`
Account string `yaml:"account,omitempty" json:"account,omitempty"`
At time.Time `yaml:"at,omitempty" json:"at,omitzero"`
Granted []string `yaml:"granted,omitempty" json:"granted,omitempty"`
// ClientID and Tenant are a server's OAuth client and its sign-in's
// tenant, for a server told them (offer.ImageServer.ClientEnv and
// TenantEnv): an id, never a secret.
ClientID string `yaml:"clientID,omitempty" json:"clientID,omitempty"`
Tenant string `yaml:"tenant,omitempty" json:"tenant,omitempty"`
// SignedInWith is the client the sign-in was made with, which the
// server refreshes as: ClientID, or Agentry's own app where the
// person kept none. Empty, the server is given ClientID.
SignedInWith string `yaml:"signedInWith,omitempty" json:"signedInWith,omitempty"`
// AgentryApp says the server's volume has held a sign-in made with
// Agentry's own app. It is set before that sign-in starts and stays
// set while the volume does, whatever client signs in later, since
// the volume may still hold its tokens: the server is then given only
// at the build's own image.
AgentryApp bool `yaml:"agentryApp,omitempty" json:"agentryApp,omitempty"`
// Signoff is what the person asked mail the server sends or drafts to
// end with, for a server that takes one; empty for none.
Signoff string `yaml:"signoff,omitempty" json:"signoff,omitempty"`
}
ImageSignIn is an image server's sign-in: when its OAuth client was set, and once signed in the account it answers as, as the server itself named it, when, and the switches whose scopes the sign-in asked for (none for a read-only one). Never a credential.
type InstallServer ¶
type InstallServer func(ctx context.Context, srv manifest.MCPServer, storeDir string, logw io.Writer) error
InstallServer installs one package server into a persistent agent's store, storeDir, writing its progress to logw (localrun.InstallServer).
type Interrupted ¶ added in v0.6.1004
type Interrupted struct {
Stopped bool `json:"stopped"`
}
Interrupted is the answer to an interrupt: whether a turn was in flight to stop. A turn that would not stop is refused instead.
type KeychainSecrets ¶
type KeychainSecrets struct{}
KeychainSecrets is the system keychain under Agentry's service. A start with a sealed credential (a headless start a client prepared) reads from it alone, as the model key is read.
func (KeychainSecrets) Delete ¶
func (KeychainSecrets) Delete(account string) error
Delete implements Secrets. A missing entry is not an error.
func (KeychainSecrets) Get ¶
func (KeychainSecrets) Get(account string) (string, error)
Get implements Secrets.
func (KeychainSecrets) Set ¶
func (KeychainSecrets) Set(account, value string) error
Set implements Secrets.
type MailProviderState ¶ added in v0.6.999
type MailProviderState struct {
Key string `json:"key"`
Name string `json:"name"`
Enabled bool `json:"enabled"`
// Servers are its servers' roster ids (server:<key>), which are on the
// roster only while it is enabled.
Servers []string `json:"servers"`
// Accounts are the accounts its signed-in servers answer as.
Accounts []string `json:"accounts,omitempty"`
// SetUp is what each server not yet signed in needs, as its roster entry
// says it.
SetUp []string `json:"setUp,omitempty"`
}
MailProviderState is one of the agent's mail providers as a client shows it: whether it is enabled, the roster ids of its servers, the account each signed-in server answers as, and what to do to set up one that is not.
func MailProviders ¶ added in v0.6.999
func MailProviders(a Agent, c Config) []MailProviderState
MailProviders are the agent's mail providers, in its built-in's order; none for an agent that reaches no mail.
type Microsoft ¶ added in v0.6.999
type Microsoft struct {
Docker dockerx.Client
Home string
Agent Agent
Policy *policy.Policy
RunnerImage string
Keys Secrets
// Client is who calls, ClientCLI or ClientDesktop (ClientCLI when
// unset).
Client string
// Say is where the steps, the code among them, are told.
Say io.Writer
// AgentryClient is the client id of Agentry's own Microsoft app, as
// the registry serves it, or "" for none. A sign-in uses it where the
// person kept no Entra client of their own and the server is the
// build's own image of it.
AgentryClient func(ctx context.Context) string
}
Microsoft is what Microsoft 365's sign-in needs, as Google is Google Workspace's.
func (Microsoft) SetClient ¶ added in v0.6.999
SetClient records the person's own Entra client, and the tenant to sign in on when they name one ("" asks Microsoft at the sign-in). A sign-in made with another client is kept until the next one. It is refused while the agent runs.
func (Microsoft) SetSignoff ¶ added in v0.6.999
SetSignoff records what mail the server sends or drafts ends with ("" for nothing): one line of printable text, at most 200 bytes.
func (Microsoft) SignIn ¶ added in v0.6.999
func (m Microsoft) SignIn(ctx context.Context, email string, browse func(string) error) (string, error)
SignIn signs Microsoft 365 in to email by the server's device code: the one-shot reaches Microsoft's sign-in host alone, the code it prints is relayed through Say and its page opened by browse, and the sign-in asks only for what the switches on need. It returns the account the server lists, and records it only then.
type Options ¶
type Options struct {
Home string
Agent Agent
// Client is who supervises: ClientCLI or ClientDesktop.
Client string
Policy *policy.Policy
PolicySHA string
PolicyFile *policy.File
// Build is the client's build identity.
Build string
Docker dockerx.Client
// Stderr gets the segment's progress (image builds, sweeps).
Stderr io.Writer
// OnStage, when set, is called as each segment's start reaches each of
// its steps (Stage; Stage.Words is how a person is shown it): the
// agent's first segment, and each a roster change or a restart starts.
// A server installed in the background while the agent runs is
// reported too, as its install begins, on that install's goroutine. It
// is called on the reporting goroutine, so it returns quickly; nil does
// nothing.
OnStage func(Stage)
// Packs opens the knowledge packs the roster has on, for each segment;
// nil refuses a roster with one on.
Packs Packs
// DevHost readies the Coding agent's dev server for each segment; nil
// readies it under Home and Policy (ReadyDevHost).
DevHost HostReady
// Secrets is where the stored secrets' values are read for each
// segment; nil is the keychain (KeychainSecrets).
Secrets Secrets
// AppLink answers the agent's app link calls other than self_configure,
// which the supervisor answers itself: the desktop's. Nil answers them
// as Agentry Desktop's.
AppLink AppLinkHandler
// StartSegment starts a segment; nil starts it with localrun. Tests
// put a session of their own here.
StartSegment func(ctx context.Context, seg localrun.Segment) (engine.PersistentSession, error)
// InstallServer installs a server in the background; nil installs it
// with localrun under Docker and Policy. Tests put an install of their
// own here.
InstallServer InstallServer
// Now is the clock the heartbeat and the time frame read; nil is the
// computer's. Tick is how often the heartbeat looks; 0 is a minute.
// Tests set both.
Now func() time.Time
Tick time.Duration
// CountFacts counts the fact lines of the agent's memory for a
// compaction's record; nil reads the memory volume with a one-shot.
// Tests put a count of their own here.
CountFacts func(context.Context) int
// MemoryDigest, with CountFacts, is the digest of the agent's memory a
// consolidation tells a changed memory by.
MemoryDigest func(context.Context) string
}
Options start a supervisor.
type Owner ¶
type Owner struct {
// contains filtered or unexported fields
}
Owner is a held owner lock. The kernel releases it when the process ends however it ends, so an agent whose supervisor died can be started again.
type Packs ¶
type Packs func(ctx context.Context, names []string) (packs []engine.AttachedPack, done func(), err error)
Packs opens the knowledge packs a segment searches, by name; done closes what it opened once the segment ends.
type Port ¶
Port is one of the Coding agent's published ports, as config.yaml keeps it: a name the person gives it and the number its programs serve on, published on this computer at 127.0.0.1 and the same number.
type Reply ¶
type Reply struct {
Event *protocol.Event `json:"event,omitempty"`
Status *Status `json:"status,omitempty"`
Roster Roster `json:"roster,omitempty"`
Stopped *Stopped `json:"stopped,omitempty"`
Tasks *[]Task `json:"tasks,omitempty"`
// Compacted answers a compact: what the compaction did.
Compacted *Compacted `json:"compacted,omitempty"`
// Interrupted answers an interrupt.
Interrupted *Interrupted `json:"interrupted,omitempty"`
// Consent lists what a refused change would turn on, for the person to
// agree to before it is sent again with Consent set.
Consent []RosterEntry `json:"consent,omitempty"`
}
Reply is one line the supervisor sends.
type Roster ¶
type Roster []RosterEntry
Roster is an agent's entries, in a fixed order: its folders, its packs, its servers.
func BuildRoster ¶
BuildRoster is the agent's roster from its config, its share's sentence saying the malware check is off, as the default policy has it; a client that knows the policy the agent runs under builds it with BuildRosterUnder. applied, when set, is what the running segment was given (Applied): an entry whose switch differs from it is pending.
func BuildRosterUnder ¶
BuildRosterUnder is BuildRoster for an agent that runs under a policy whose malware check is malwareCheck: the share's sentence of an agent that checks its share says whether ClamAV checks its files. Changing the setting changes the sentence and asks nothing: an agreement to the share under either setting is an agreement to it under the other (Unconsented).
func Configure ¶
func Configure(ctx context.Context, home string, a Agent, client string, ch Change) (r Roster, running bool, err error)
Configure applies a change to an agent: through its supervisor when it runs, which then writes its config alone, and under its owner lock when it does not, so no start reads a config half changed. running says which.
func QueryRoster ¶
QueryRoster asks the running agent's supervisor for its roster.
func RequestChange ¶
RequestChange sends a change to the running agent's supervisor, which writes it, and answers the roster after it.
func (Roster) Entry ¶
func (r Roster) Entry(id string) (RosterEntry, bool)
RosterEntry is the roster's entry with id.
func (Roster) Receipt ¶
func (r Roster) Receipt() []receipt.RosterEntry
Receipt is the roster as a segment's envelope records it.
type RosterEntry ¶
type RosterEntry struct {
// ID is how a switch names the entry: "share", "data",
// "knowledge:<pack>", "server:<id>".
ID string `json:"id"`
Kind EntryKind `json:"kind"`
Name string `json:"name"`
GrantedBy string `json:"grantedBy"`
State EntryState `json:"state"`
// On is the entry's switch as config.yaml holds it; State says what a
// running segment has.
On bool `json:"on"`
// Line is the consent sentence for the entry.
Line string `json:"line"`
// Fixed is an entry no switch changes.
Fixed bool `json:"fixed,omitempty"`
// Reason is why a failed entry failed.
Reason string `json:"reason,omitempty"`
// ShareSwitch is, for a server that may see the agent's share folder
// (a package server with no network), the id of its switch for that:
// "server:<id>:share". Share says the switch is on: the server sees
// the share, read only, while the agent has its share on. ShareLine is
// the server's sentence with the switch on, the one turning it on asks
// the person to agree to.
// contains filtered or unexported fields
}
RosterEntry is one line of the roster.
func Unconsented ¶
func Unconsented(r Roster, c Config) []RosterEntry
Unconsented are the roster's entries that are on and whose consent sentence the person has not agreed to as it stands.
type Secrets ¶
type Secrets interface {
Get(account string) (string, error)
Set(account, value string) error
Delete(account string) error
}
Secrets is where stored secrets' values are kept.
type ServerFailure ¶
type ServerFailure struct {
// Reason is the install's error and the builder's last lines, cut.
Reason string `yaml:"reason" json:"reason"`
At time.Time `yaml:"at" json:"at"`
// Told says the agent was told, at a turn, that it does not have the
// server.
Told bool `yaml:"told,omitempty" json:"told,omitempty"`
}
ServerFailure is why a server the person added could not be installed.
type SkillCheck ¶
SkillCheck checks a staged skill's files as the share's are checked; it says whether ClamAV checked every file and found nothing, and refuses a finding with an error.
type Status ¶
type Status struct {
Agent string `json:"agent"`
State string `json:"state"`
Client string `json:"client"`
PID int `json:"pid"`
Since time.Time `json:"since"`
Segment int `json:"segment"`
Run string `json:"run"`
SegmentDir string `json:"segmentDir"`
Adapter string `json:"adapter"`
Model string `json:"model"`
Resumed bool `json:"resumed"`
ResumeReason string `json:"resumeReason,omitempty"`
Busy bool `json:"busy"`
Usage receipt.Usage `json:"usage"`
// Pending says a change waits for the next turn's segment.
Pending bool `json:"pending,omitempty"`
}
Status is a running agent's state, as `agentry agent show` prints it.
type Stopped ¶
type Stopped struct {
Status string `json:"status"`
ResultFile string `json:"resultFile,omitempty"`
Error string `json:"error,omitempty"`
}
Stopped is the answer to a stop: where the segment's envelope is and how it ended.
type StoredSecret ¶
type StoredSecret struct {
Name string `yaml:"name" json:"name"`
Set time.Time `yaml:"set" json:"set"`
}
StoredSecret is a secret the person stored for the agent: its name, and when its value was last set, so setting it again reaches the next turn.
type Supervisor ¶
type Supervisor struct {
// contains filtered or unexported fields
}
Supervisor owns one running agent: its lock, its segment, its socket.
func Start ¶
func Start(ctx context.Context, opts Options) (*Supervisor, error)
Start takes the agent's owner lock and starts a segment: the conversation the last segment was in is continued where the harness can, and otherwise the new conversation's first turn carries the last exchange of the transcript, which the envelope records. It refuses an agent whose roster turns on what the person has not agreed to on this computer (ConsentError). It serves the owner socket until Stop, or until the segment ends by itself.
func (*Supervisor) Change ¶
func (s *Supervisor) Change(ch Change) (Roster, error)
Change applies a change to the running agent's config, the supervisor alone writing it while it runs. A change to what the segment is given takes effect at the next turn, which starts the next segment; the roster answered shows it pending until then.
func (*Supervisor) ChangeTask ¶
func (s *Supervisor) ChangeTask(op TaskOp) ([]Task, error)
ChangeTask applies a person's pause, resume or remove to the running agent's task.
func (*Supervisor) Compact ¶ added in v0.6.999
func (s *Supervisor) Compact(ctx context.Context) (Compacted, error)
Compact compacts the conversation now, at the person's asking, whatever its size. It refuses while another turn is in flight.
func (*Supervisor) Done ¶
func (s *Supervisor) Done() <-chan struct{}
Done is closed once the supervisor has finished: the segment ended, its envelope written, the socket closed and the lock released.
func (*Supervisor) Interrupt ¶ added in v0.6.1004
func (s *Supervisor) Interrupt(ctx context.Context) error
Interrupt stops the turn in flight, the person's or one the runner sent (a task's, an upkeep's), and returns once it has ended; the agent goes on. With no turn in flight it is session.ErrNoTurn.
func (*Supervisor) Roster ¶
func (s *Supervisor) Roster() Roster
Roster is the running agent's roster: an entry switched since the segment started is pending.
func (*Supervisor) Send ¶
func (s *Supervisor) Send(ctx context.Context, text string) error
Send sends one turn and returns when the agent has answered it. When the roster changed since the segment started, the segment is ended and the next started first, so the turn reaches an agent given the change. The first turn of a conversation that did not continue starts with the last exchange; the first turn after a change says what it switched on and off since the agent was last told, since the conversation the agent continues was had with what it had before; and a turn after the person named the agent or changed its personality starts with them. An agent that keeps time is told the time at every turn, and, at its first turn after a start, the tasks that came due while it was stopped.
func (*Supervisor) Stop ¶
Stop ends the segment without a final result, writes its receipts and envelope, adds its usage to the agent's, and lets the agent go. The volumes stay. Safe to call more than once and after the segment ended by itself; every call returns the segment's envelope.
func (*Supervisor) Subscribe ¶
func (s *Supervisor) Subscribe() (<-chan session.Event, func())
Subscribe hands every event from now on to a channel, until cancel or the agent's end closes it.
func (*Supervisor) Tasks ¶
func (s *Supervisor) Tasks() ([]Task, error)
Tasks are the running agent's tasks, each with its next fire.
type Task ¶
type Task struct {
ID string `yaml:"id" json:"id"`
Name string `yaml:"name" json:"name"`
Cron string `yaml:"cron" json:"cron"`
Zone string `yaml:"zone" json:"zone"`
Instruction string `yaml:"instruction" json:"instruction"`
State string `yaml:"state" json:"state"`
MadeBy string `yaml:"madeBy" json:"madeBy"`
Created time.Time `yaml:"created" json:"created"`
// LastFire is when the task last fired, and LastResult the first line
// of that turn's answer, or why it did not answer.
LastFire time.Time `yaml:"lastFire,omitempty" json:"lastFire,omitzero"`
LastResult string `yaml:"lastResult,omitempty" json:"lastResult,omitempty"`
// Next is when it fires next; set when the task is listed, not kept.
Next time.Time `yaml:"-" json:"next,omitzero"`
}
Task is one registered task.
func ChangeTaskOf ¶
func ChangeTaskOf(ctx context.Context, home string, a Agent, client string, op TaskOp) ([]Task, bool, error)
ChangeTaskOf applies a person's pause, resume or remove to an agent's task: through its supervisor while it runs, under its owner lock while it does not.
func RequestTaskChange ¶
RequestTaskChange asks the running agent's supervisor to pause, resume or remove one of its tasks.
func RequestTasks ¶
RequestTasks asks the running agent's supervisor for its tasks.
type TaskSpec ¶
type TaskSpec struct {
Name *string `json:"name,omitempty"`
Cron *string `json:"cron,omitempty"`
Zone *string `json:"zone,omitempty"`
Instruction *string `json:"instruction,omitempty"`
Paused *bool `json:"paused,omitempty"`
}
TaskSpec is what the agent gives to add or update a task; an update sets only what it names.
type Tasks ¶
type Tasks struct {
Version int `yaml:"version"`
// Checked is the last time the heartbeat looked for tasks that came
// due: the next start names the ones that came due after it.
Checked time.Time `yaml:"checked,omitempty"`
// Fires are the times of the fires of the last day, for the day's cap.
Fires []time.Time `yaml:"fires,omitempty"`
NextID int `yaml:"nextId"`
Tasks []Task `yaml:"tasks"`
}
Tasks is an agent's tasks file.
func (*Tasks) RemoveTask ¶
RemoveTask removes the task id.
type UpkeepRecord ¶ added in v0.6.999
type UpkeepRecord struct {
Time time.Time `json:"time"`
Trigger string `json:"trigger"`
Swapped bool `json:"swapped"`
Reason string `json:"reason,omitempty"`
ContextTokens int64 `json:"contextTokens,omitempty"`
OldConversation string `json:"oldConversation,omitempty"`
NewConversation string `json:"newConversation,omitempty"`
Turn int `json:"turn,omitempty"`
FactsBefore int `json:"factsBefore"`
FactsAfter int `json:"factsAfter"`
HandoffBytes int `json:"handoffBytes,omitempty"`
HandoffCut bool `json:"handoffCut,omitempty"`
HandoffForm string `json:"handoffForm,omitempty"`
Swap string `json:"swap,omitempty"`
SwapMillis int64 `json:"swapMillis,omitempty"`
}
UpkeepRecord is one line of receipts/upkeep.ndjson: a compaction, or a consolidation (Trigger UpkeepConsolidate), whether it ran or why not.
func LastUpkeep ¶ added in v0.6.999
func LastUpkeep(home, name string) (compaction, consolidation *UpkeepRecord)
LastUpkeep is the agent's newest compaction record and its newest consolidation record, across its segments' receipts; nil where there is none. What cannot be read (a file, a line) is skipped: the records are a report, and a damaged one hides nothing else.
type Usage ¶
type Usage struct {
Segments int `json:"segments"`
InputTokens int64 `json:"inputTokens"`
OutputTokens int64 `json:"outputTokens"`
TotalTokens int64 `json:"totalTokens"`
UserTurns int `json:"userTurns"`
ToolCalls int `json:"toolCalls"`
Updated time.Time `json:"updated"`
}
Usage is the agent's lifetime usage, summed over its segments' envelopes (usage.json).