persistent

package
v0.7.4 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 66 Imported by: 0

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

View Source
const (
	MaxNameBytes        = 64
	MaxPersonalityBytes = 32 << 10
)

The bounds of what a person writes for the agent.

View Source
const (
	EntryCommands = "commands"
	EntryEgress   = "egress"
	EntryBrowser  = "browser"
	EntryDevHost  = "devhost"
	// EntryDependencyScan is dependency_scan, OSV-Scanner offline.
	EntryDependencyScan = "dependency-scan"
)

The Coding agent's entries.

View Source
const (
	ClientCLI     = "cli"
	ClientDesktop = "desktop"
)

The clients that own a running agent.

View Source
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.

View Source
const (
	SourceRegistry = "registry"
	SourceLocal    = installed.SourceLocal
)

Where a published agent's release came from.

View Source
const (
	EntryWeb    = "web"
	EntryReview = "review"
)

The web tools' and the review grant's roster ids, for an agent that declares them.

View Source
const (
	GrantedByBuiltin = "built-in"
	GrantedByRelease = "release"
	GrantedByYou     = "you"
)

Who granted an entry: the agent's built-in, its release's publisher (a published agent's), or the person.

View Source
const (
	EntryShare = "share"
	EntryData  = "data"
)

The ids of the folder entries.

View Source
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.

View Source
const (
	SkillCheckedClamAV = "clamav"
	SkillUnchecked     = "unchecked"
)

How an added skill was checked when it was added.

View Source
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"
	RefusedAnswer                     = protocol.RefusedAnswer
)

The refusal classes the owner socket adds to the session protocol's.

View Source
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.

View Source
const (
	TaskOn     = "on"
	TaskPaused = "paused"
)

Task states.

View Source
const (
	TaskOpPause  = "pause"
	TaskOpResume = "resume"
	TaskOpRemove = "remove"
)

The person's task operations.

View Source
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.

View Source
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.

View Source
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.

View Source
const CalendarSignInTimeout = 10 * time.Minute

CalendarSignInTimeout bounds a browser sign-in.

View Source
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.

View Source
const DocsBase = "https://docs.secureagentry.net"

DocsBase is the documentation site docs_read reads from, and nothing else.

View Source
const EntryHeartbeat = "heartbeat"

EntryHeartbeat is the roster's switch for an agent's heartbeat.

View Source
const EntryMeetings = "meetings"

EntryMeetings is the roster's switch for an agent's meeting tools.

View Source
const EntryMemory = "memory"

EntryMemory is the memory's roster entry: fixed on, for an agent that keeps one.

View Source
const EntryVoice = "voice"

EntryVoice is the Writing Voice's roster id.

View Source
const (

	// GoogleSignInTimeout is how long the sign-in waits for the browser.
	GoogleSignInTimeout = 10 * time.Minute
)

The bounds of a Google sign-in.

View Source
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.

View Source
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.

View Source
const MaxAddedSkills = 50

MaxAddedSkills is how many skills the person may add to an agent.

View Source
const MaxPorts = 8

MaxPorts bounds the Coding agent's published ports.

View Source
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.

View Source
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.

View Source
const StateRunning = "running"

StateRunning is a running agent's state.

View Source
const TaskMadeByAgent = "agent"

TaskMadeByAgent says the agent registered the task.

Variables

View Source
var (
	// ErrNotAgreed: the person said no.
	ErrNotAgreed = errors.New("not done: the person said no")
	// ErrNobodyToAsk: no client is attached to ask the person.
	ErrNobodyToAsk = errors.New("not done: the person could not be asked, because no Agentry window or terminal is attached to this agent; ask them to open it in Agentry Desktop, or to attach to it with agentry agent chat, and try again")
	// ErrNotAnswered: the person did not answer in time.
	ErrNotAnswered = errors.New("not done: the person did not answer")
)

The ways a question is not a yes.

View Source
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.

View Source
var ErrBusy = session.ErrBusy

ErrBusy refuses a turn sent while another is in flight.

View Source
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.

View Source
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.

View Source
var ErrDesktopOnly = errors.New("runs only in Agentry Desktop")

ErrDesktopOnly refuses an agent that runs only in Agentry Desktop.

View Source
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.

View Source
var ErrNoTask = errors.New("no such task")

ErrNoTask refuses a change to a task the agent does not have.

View Source
var ErrNotRunning = errors.New("not running")

ErrNotRunning says no supervisor answers on the agent's socket.

View Source
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.

View Source
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

func AccountEntryID(host string) string

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

func AccountKeychainAccount(host, user string) string

AccountKeychainAccount is the keychain account a git host account's token is kept under.

func AddedSkillsPath

func AddedSkillsPath(home, name string) string

AddedSkillsPath is where the agent's added skills are kept, one folder each.

func AgreeToRoster

func AgreeToRoster(home string, a Agent, client string) error

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

func AppSocketPath(home, name string) string

AppSocketPath is the socket an agent's supervisor answers its app link on, beside its owner socket.

func ApplyChange

func ApplyChange(home string, a Agent, c *Config, ch Change) (restart bool, err error)

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

func CalendarEntryID(name string) string

CalendarEntryID is a calendar feed's roster id.

func CalendarFeedReadableWith added in v0.6.999

func CalendarFeedReadableWith(ctx context.Context, address, session string) (string, int, error)

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

func CalendarKeychainAccount(agent, name string) string

CalendarKeychainAccount is the keychain account a calendar feed's address is kept under.

func CalendarService added in v0.6.999

func CalendarService(host string) string

CalendarService names the service a feed's host belongs to, or "".

func CalendarSession added in v0.6.999

func CalendarSession(keys Secrets, agent, name string) (string, error)

CalendarSession reads a feed's browser sign-in back from the keychain.

func CalendarSessionAccount added in v0.6.999

func CalendarSessionAccount(agent, name string, n int) string

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

func CheckGoogleClient(b []byte) error

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

func CheckMicrosoftClient(id string) error

CheckMicrosoftClient refuses an Entra application id that is not one, or that is Softeria's own.

func CheckSecretName

func CheckSecretName(name string) error

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

func CheckSecretValue(v string) error

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

func CheckShareFolder(home, dir string) error

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

func DataVolume(name string) string

DataVolume is the agent's data volume under the earlier name.

func DataVolumeIn

func DataVolumeIn(home, name string) string

DataVolumeIn is the agent's volume for its own files in the runner home home.

func Dir

func Dir(home, name string) string

Dir is the agent's state folder under the runner home.

func DiscardSkill

func DiscardSkill(home string, a Agent, name string) error

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 DocsText added in v0.7.1

func DocsText(body []byte, page string) string

DocsText is a docs page's text: its article (or its main, or its body), with the links within the docs written as their paths, so a next docs_read can follow them.

func ForgetCalendarFeed added in v0.6.999

func ForgetCalendarFeed(keys Secrets, agent, name string) error

ForgetCalendarFeed removes a feed's address and its browser sign-in from the keychain.

func ForgetCalendarSession added in v0.6.999

func ForgetCalendarSession(keys Secrets, agent, name string) error

ForgetCalendarSession removes a feed's browser sign-in from the keychain.

func HistoryEvents

func HistoryEvents(entries []Entry) []session.Event

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

func HomeID(home string) string

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

func HomeMalwareCheck(home string) bool

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

func ImageKeyringAccount(agent, key string) string

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

func ImageServerEntryID(key string) string

ImageServerEntryID is an image server's roster id.

func ImageSwitchEntryID added in v0.6.999

func ImageSwitchEntryID(key, sw string) string

ImageSwitchEntryID is the roster id of an image server's switch.

func ImageVolumeIn added in v0.6.999

func ImageVolumeIn(home, name, key string) string

ImageVolumeIn is the volume of the agent's image server key in the runner home home.

func IsBuiltinRef added in v0.6.1015

func IsBuiltinRef(ref string) bool

IsBuiltinRef says ref (ns/name) is a persistent built-in's, which is never installed as a published agent.

func KeepCalendarSession added in v0.6.999

func KeepCalendarSession(keys Secrets, agent, name, session string) error

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 Key added in v0.6.1015

func Key(namespace, name string) string

Key is a published agent's key: its state folder's, its volumes' and its socket's name.

func KnowledgeEntryID

func KnowledgeEntryID(pack string) string

KnowledgeEntryID is a pack's roster id.

func LogPath

func LogPath(home, name string) string

LogPath is where a detached supervisor writes what it prints.

func MemoryVolumeIn

func MemoryVolumeIn(home, name string) string

MemoryVolumeIn is the agent's memory volume in the runner home home.

func PortEntryID

func PortEntryID(name string) string

PortEntryID is the roster id of a published port.

func ReadSecrets

func ReadSecrets(keys Secrets, agent string, names []string) (map[string]string, error)

ReadSecrets reads the values of the named secrets of the agent from keys: every one must be there.

func RecordConsent

func RecordConsent(r Roster, c *Config)

RecordConsent records the person's agreement to every entry that is on.

func RequestInterrupt added in v0.6.1004

func RequestInterrupt(ctx context.Context, home, name string) (stopped bool, err error)

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

func Reset(ctx context.Context, home, name string, d dockerx.Client) error

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

func ResetAgent(ctx context.Context, home, name string, d dockerx.Client) error

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

func ResetHistory(ctx context.Context, home, name string, d dockerx.Client) error

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

func SaveConfig(home, name string, c Config) error

SaveConfig writes the agent's config.yaml (0600), replacing it whole.

func SecretAccount

func SecretAccount(agent, name string) string

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

func SecretEntryID(name string) string

SecretEntryID is a stored secret's roster id.

func ServerEntryID

func ServerEntryID(srv manifest.MCPServer) string

ServerEntryID is a server's roster id: its store id, which names its package or its address.

func ServerMaySeeShare

func ServerMaySeeShare(srv manifest.MCPServer) error

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

func ServerShareID(srv manifest.MCPServer) string

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

func ServerWritesID(srv manifest.MCPServer) string

ServerWritesID is the roster id of an offered server's writes entry.

func SessionVolume

func SessionVolume(name string) string

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

func SessionVolumeIn(home, name string) string

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

func SetMailProvider(home string, a Agent, client, key string, on bool) error

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

func ShareFolder(a Agent, c Config) (string, error)

ShareFolder is the agent's share folder: config.yaml's, else its default under ~/agentry.

func SharedVolumes

func SharedVolumes(ctx context.Context, d dockerx.Client, name string) []string

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 SkillEntryID

func SkillEntryID(name string) string

SkillEntryID is a skill's roster id.

func SocketPath

func SocketPath(home, name string) string

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 SubagentAskID added in v0.7.1

func SubagentAskID(ref string) string

SubagentAskID is the id of a subagent's switch that asks before each run.

func SubagentEntryID added in v0.7.1

func SubagentEntryID(ref string) string

SubagentEntryID is a subagent's entry id: "subagent:<ns>/<name>".

func Suggested added in v0.6.999

func Suggested(a Agent, key string) (manifest.MCPServer, error)

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.

func Uninstall added in v0.6.1015

func Uninstall(ctx context.Context, home, name string, d dockerx.Client, removeData bool) error

Uninstall removes a published agent's install record, so it is no longer one of the agents, and keeps its state folder and volumes, which a later install of the same reference takes up again, unless removeData: then it is first reset as Reset does, its volumes and what it keeps in the keychain removed, and its state folder goes too, the files in its share folder, which are the person's, staying. It refuses a built-in and a running agent, and holds the agent's lock while it works. The release folder is the caller's to remove, with its consent record.

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 AddedSubagent added in v0.7.1

type AddedSubagent struct {
	Ref     string `yaml:"ref" json:"ref"`
	Version string `yaml:"version" json:"version"`
	Reach   string `yaml:"reach,omitempty" json:"reach,omitempty"`
}

AddedSubagent is a subagent the person added: an autonomous QuickAgent installed on this computer, at the version it was installed at when it was added, with what its contract reaches in a line.

type Agent

type Agent struct {
	// Name is the agent's key: what the commands, the state folder, the
	// volumes and the socket are keyed by. A built-in's is its short name,
	// a published agent's its reference with a dot (Key).
	Name string
	// Ref is the agent's ns/name.
	Ref string
	// Title is how the agent is named to a person until they or its persona
	// name it (DisplayName): a built-in's own, a published agent's release
	// name.
	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 built-in it runs; the zero value for a published
	// agent, which has none of a built-in's grants.
	Builtin localrun.Builtin
	// ShareName is the default share folder's name, under ~/agentry.
	ShareName string

	// A published agent's, empty for a built-in: the version it runs and
	// where it came from (SourceRegistry or SourceLocal), its release
	// folder, what its release declares under capabilities.persistent
	// (Declared), the persona and the knowledge packs its release ships,
	// and the subagents it declares as they were pinned at its install.
	Version   string
	Source    string
	Release   *localrun.Installed
	Caps      *manifest.Persistent
	Persona   *Persona
	Packs     []string
	Subagents []SubagentPin
	// Registry is the registry a registry release came from, which its
	// subagents run from; empty is this computer's default.
	Registry string
}

Agent is one persistent agent: a built-in, or a published agent installed in the runner home (published.go).

func Agents

func Agents() []Agent

Agents are the persistent agents built into this build, in the order they are listed; AgentsIn adds the ones installed in a runner home.

func AgentsIn added in v0.6.1015

func AgentsIn(home string) []Agent

AgentsIn are the persistent agents of the runner home home: the built-ins, then the published agents installed there, by reference.

func Lookup

func Lookup(name string) (Agent, error)

Lookup is the built-in agent named name; LookupIn finds the published agents of a runner home too.

func LookupIn added in v0.6.1015

func LookupIn(home, name string) (Agent, error)

LookupIn is the agent of the runner home home that name names: a built-in by its short name, a published agent by its reference (ns/name) or its key, or by its name alone when no other agent has it. A built-in's short name is always the built-in. A name two published agents share is refused, naming both.

func SaveRelease added in v0.6.1015

func SaveRelease(home string, r Release) (Agent, error)

SaveRelease records a published agent's install in its state folder and enables it: what `agentry agent install` writes once its release is laid down and the person agreed to it. Its configuration, conversation and volumes, kept from an earlier install of the same reference, are its again; an agent the person disabled stays disabled when only its version moves.

func (a Agent) AppLink() string

AppLink is the agent's app link tool set, composed from what it declares; empty for none.

func (Agent) AppLinkWith added in v0.7.1

func (a Agent) AppLinkWith(c Config) string

AppLinkWith is the agent's app link tool set: its declared parts, and the subagent tools when its roster names a subagent.

func (Agent) ArmsMeetings added in v0.6.1017

func (a Agent) ArmsMeetings() bool

ArmsMeetings says the agent's app link has the meeting tools, through which it arms Agentry Desktop to record a meeting, and its roster the switch that lets it (meetings).

func (Agent) Codes added in v0.6.1018

func (a Agent) Codes() bool

Codes says the agent declares the coding toolchain (coder): any program in the coder exec image, open egress, the public browser, a dev host, ports and git host accounts, each a switch of its roster.

func (Agent) ConfiguresItself added in v0.6.1017

func (a Agent) ConfiguresItself() bool

ConfiguresItself says the agent may save its own name and persona through self_configure (selfConfigure).

func (Agent) Declared added in v0.6.1017

func (a Agent) Declared() *manifest.Persistent

Declared is what the agent declares under capabilities.persistent: its release's block for a published agent, its own manifest's for a built-in. Each capability below is reached only by declaring it, whatever the agent's source; nil declares nothing.

func (Agent) DisplayName

func (a Agent) DisplayName(c Config) string

DisplayName is the name the agent goes by: the person's for it, else its persona's, else its title.

func (Agent) ImageServers added in v0.6.1018

func (a Agent) ImageServers(images policy.Images) []offer.ImageServer

ImageServers are the servers run from an image the CLI pins that the agent declares, at the policy's images.

func (Agent) KeepsMemory added in v0.6.1017

func (a Agent) KeepsMemory() bool

KeepsMemory says the agent has a memory volume of its own, with compaction, the daily consolidation and recall (memory).

func (Agent) KeepsSecrets added in v0.6.1017

func (a Agent) KeepsSecrets() bool

KeepsSecrets says the person may store secrets for the agent, each a roster entry (secrets).

func (Agent) KeepsTime added in v0.6.1017

func (a Agent) KeepsTime() bool

KeepsTime says the agent is told the time at each turn and keeps a heartbeat that fires the tasks it registers (clock).

func (Agent) MailProviders added in v0.6.1018

func (a Agent) MailProviders() []offer.MailProvider

MailProviders are the mail providers the agent declares.

func (Agent) MemorySeed added in v0.6.1017

func (a Agent) MemorySeed() (map[string][]byte, error)

MemorySeed is what the agent's memory volume starts with, for an agent that keeps a memory: a built-in's tree's memory/ folder; for a published agent, Agentry's memory seed (its schema, index and log) with the files of its release's memory/ laid over it, but for the schema, which stays Agentry's so the memory's skills can keep it.

func (Agent) OfferedServers added in v0.6.1018

func (a Agent) OfferedServers(hosts []offer.GitHost) []offer.Server

OfferedServers are the MCP servers the agent comes with, each an entry of its roster: a built-in's package's own (some drawn for its git host accounts, hosts); a published agent's, the servers of the mail providers its release declares that are reached through a server of their own.

func (Agent) PackageRef added in v0.6.1015

func (a Agent) PackageRef() string

PackageRef is the package the agent runs, as ns/name@version.

func (Agent) Published added in v0.6.1015

func (a Agent) Published() bool

Published says the agent is installed from a release, not built in.

func (Agent) ReadsCalendars added in v0.6.1018

func (a Agent) ReadsCalendars() bool

ReadsCalendars says the agent declares calendars: the person may give it calendar feeds.

func (Agent) Skills added in v0.6.1017

func (a Agent) Skills() []AgentSkill

Skills are the agent's own skills: for an agent that takes skills, its built-in's tree's or the ones its release ships under skills/; and for a published agent that keeps a memory, the memory's own skills (compile.MemorySkills), from Agentry's tree, which its compaction and consolidation follow; a release's skill of one of their names is left out. A release's are read from its folder, which a segment's start holds to its integrity record before anything it staged is mounted.

func (Agent) SuggestedServers added in v0.6.1018

func (a Agent) SuggestedServers() []offer.Suggestion

SuggestedServers are the MCP servers a built-in's package suggests; a published agent suggests none.

func (Agent) TakesSkills added in v0.6.1017

func (a Agent) TakesSkills() bool

TakesSkills says the agent follows skills: its package's own and the ones the person adds (skills).

type AgentSkill added in v0.6.1017

type AgentSkill struct {
	localrun.BuiltinSkill
	GrantedBy string
}

AgentSkill is one of an agent's own skills and who grants it: the application, for a built-in's and for the memory's own skills, or its release.

type AppLinkHandler

type AppLinkHandler func(ctx context.Context, req applink.Request) applink.Answer

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.

func ApplyWith added in v0.6.1017

func ApplyWith(ctx context.Context, home string, a Agent, c Config, r Roster, openers Openers, ready HostReady, keys Secrets) (g localrun.Grants, applied Applied, done func(), err error)

ApplyWith is Apply with each of the person's things it opens.

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 is the share folder, absolute; "" is the agent's default.
	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.
	// AddSubagent adds a subagent the client checked is installed on this
	// computer and runs autonomously, on; RemoveSubagent takes away one the
	// person added, by its reference.
	AddSubagent    *AddedSubagent `json:"addSubagent,omitempty"`
	RemoveSubagent string         `json:"removeSubagent,omitempty"`
	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"`
	// Answer answers a question the agent's runner put to the person
	// (ask.go), by its id.
	Answer *protocol.Answer `json:"answer,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.

func RequestCompact added in v0.6.999

func RequestCompact(ctx context.Context, home, name string) (Compacted, error)

RequestCompact asks the running agent's supervisor for an upkeep turn and a compaction now, and returns once it is done: an upkeep turn takes minutes, so ctx should allow for 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"`
	// Share is the share folder, absolute; empty is the agent's default,
	// ~/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"`
	// Subagents are the subagents the person added (subagents.go).
	Subagents []AddedSubagent `yaml:"subagents,omitempty" json:"subagents,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

func LoadConfig(home, name string) (Config, error)

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 ParseCron

func ParseCron(expr string) (Cron, error)

ParseCron reads a five-field expression.

func (Cron) CloserThan

func (c Cron) CloserThan(from time.Time, loc *time.Location, d time.Duration) (bool, error)

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

func (c Cron) Count(from, to time.Time, loc *time.Location, limit int) int

Count is how many times the expression names in loc after from and up to to, counting at most limit+1.

func (Cron) Next

func (c Cron) Next(after time.Time, loc *time.Location) (time.Time, error)

Next is the first time after after, to the minute, that the expression names in loc; errNoNext when none comes within cronHorizon. A wall-clock minute a change to summer time skips does not come; one a change back to winter time repeats comes once, the first time.

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.

func Transcript

func Transcript(home, name string, n int) ([]Entry, error)

Transcript is the last n lines of the agent's transcript (every line for n <= 0). A line that does not parse is skipped.

type EntryKind

type EntryKind string

EntryKind is what a roster entry grants.

const (
	KindTools EntryKind = "tools"
	KindHost  EntryKind = "host"
	KindPort  EntryKind = "port"
)

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 KindSubagent EntryKind = "subagent"

KindSubagent is the kind of a subagent's entries.

const KindTasks EntryKind = "tasks"

KindTasks is the kind of the heartbeat's entry.

const KindVoice EntryKind = "voice"

KindVoice is the person's Writing Voice, given to a published agent.

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

func (g Google) SetClient(ctx context.Context, client []byte) error

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.

func (*HeldError) Error

func (e *HeldError) Error() string

type HelperHit added in v0.7.1

type HelperHit struct {
	Ref, Summary string
	Modes        []string
	Installs30d  int
	Quarantined  bool
}

HelperHit is one registry match.

type HelperInstalled added in v0.7.1

type HelperInstalled struct {
	Ref, Version, Registry string
	// Local is an install from an author's folder, which only the person
	// runs.
	Local bool
}

HelperInstalled is one QuickAgent installed on this computer.

type HelperOps added in v0.7.1

type HelperOps interface {
	// Search searches the registry and answers it as it is shown, and its
	// matches.
	Search(ctx context.Context, query string) (registry string, hits []HelperHit, err error)
	// Show describes ref (ns/name) on the registry, as text the agent reads:
	// what it does and reaches, its versions, its security report and its
	// installed version here.
	Show(ctx context.Context, ref string) (string, error)
	// Installed are the QuickAgents installed on this computer.
	Installed(ctx context.Context) ([]HelperInstalled, error)
	// Install installs ref (ns/name or ns/name@version) for the agent who
	// names, the person having agreed, and says what it installed.
	Install(ctx context.Context, ref, who string) (string, error)
	// Schedules lists the schedules; AddSchedule makes one, the person
	// having agreed; PauseSchedule pauses or resumes one; RemoveSchedule
	// removes one, the person having agreed.
	Schedules(ctx context.Context) ([]HelperSchedule, error)
	AddSchedule(ctx context.Context, s HelperScheduleSpec, who string) (id string, err error)
	PauseSchedule(ctx context.Context, id string, paused bool) error
	RemoveSchedule(ctx context.Context, id, who string) error
	// Docs reads a page of the docs site: its body and status.
	Docs(ctx context.Context, page string) (body []byte, status int, err error)
}

HelperOps are the operations a client gives the supervisor to answer the helper tools with.

type HelperOpsAsk added in v0.7.2

type HelperOpsAsk interface {
	HelperOps
	AsksThePerson() bool
}

HelperOpsAsk is HelperOps that ask the person themselves before an install, a schedule and a schedule's removal, naming the agent who asks: a client whose own dialogs show what is installed or scheduled. The supervisor then asks nothing more for those three, and an ErrNotAgreed from them is the person's no.

type HelperSchedule added in v0.7.1

type HelperSchedule struct {
	ID, Name, Ref, When, Next string
	Paused, Ended             bool
}

HelperSchedule is one schedule.

type HelperScheduleSpec added in v0.7.1

type HelperScheduleSpec struct {
	Registry, Exact, Task string
	Answers               map[string]string
	When                  When
}

HelperScheduleSpec is a schedule a helper tool makes.

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 Held

func Held(home, name string) (bool, *Holder)

Held reports whether some process holds the agent's owner lock, and who.

func ReadHolder

func ReadHolder(home, name string) (*Holder, error)

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.

func (Holder) Where

func (h Holder) Where() string

Where names the holder's client to a person.

type HostReady

type HostReady func(ctx context.Context, d DevHost) (*targethost.Host, error)

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.

func ReadyDevHost

func ReadyDevHost(home string, pol *policy.Policy) HostReady

ReadyDevHost is the HostReady of a supervisor under the runner home home and the policy pol: the policy's host lists, the runner's and the person's known_hosts files, the sign-in the person saved.

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

func (m Microsoft) SetClient(clientID, tenant string) error

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

func (m Microsoft) SetSignoff(text string) error

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 Openers added in v0.6.1017

type Openers struct {
	Packs  Packs
	Voice  Voice
	Web    WebOpener
	Review ReviewOpener
}

Openers are what Apply opens for a segment beside the keychain: the person's knowledge packs and their Writing Voice. A nil opener refuses a roster with what it opens on.

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
	// Voice opens the person's Writing Voice for each segment of a
	// published agent that has it on; nil refuses a roster with it on.
	Voice Voice
	// Web and Review read the keys of the web tools and the review grant
	// for each segment of an agent that declares them and has them on;
	// nil reads them from Policy as work on this computer does
	// (LocalWebOpener, LocalReviewOpener).
	Web    WebOpener
	Review ReviewOpener
	// 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
	// Subagents runs the agent's subagents (subagentrun.go), and the runs
	// quickagent_run starts; nil refuses both.
	Subagents SubagentHost
	// Helper answers Agentry's helper tools (helper.go), before AppLink;
	// nil leaves them to AppLink, and with neither they are refused.
	Helper HelperOps
	// 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
	// Credits is the credits-session client of the registry this computer
	// is signed in to, for a policy that pays with Agentry credits (model
	// provider agentry): the agent opens one session with it for its whole
	// life. Nil refuses such an agent as signed out.
	Credits *inference.Client
	// 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.

func Acquire

func Acquire(home, name, client string) (*Owner, error)

Acquire takes the agent's owner lock for client, or refuses with a HeldError naming the holder.

func (*Owner) Release

func (o *Owner) Release()

Release lets the lock go and removes the holder's record.

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 Persona added in v0.6.1015

type Persona struct {
	Name string `json:"name"`
	Text string `json:"text"`
	// Editable says the person may replace the text; a locked persona
	// may still be renamed.
	Editable bool `json:"editable"`
}

Persona is the name and the text a published agent's release ships for it to take on.

type Port

type Port struct {
	Name string `yaml:"name" json:"name"`
	Port int    `yaml:"port" json:"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.

func (Port) Address

func (p Port) Address() string

Address is where the port is published on this computer.

type Question added in v0.7.1

type Question struct {
	ID, Title, Text string
}

Question is a question Ask puts to the person, as a client in this process is given it: its id, its title and its text.

type Release added in v0.6.1015

type Release struct {
	// Ref is the release's ns/name.
	Ref string `yaml:"ref" json:"ref"`
	// Version and Digest name the release folder the agent runs.
	Version string `yaml:"version" json:"version"`
	Digest  string `yaml:"digest" json:"digest"`
	// Source is SourceRegistry or SourceLocal.
	Source string `yaml:"source" json:"source"`
	// Registry is the registry a registry release was installed from, which
	// its subagents are run from; empty is this computer's default.
	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`
	// Folder is the author's folder a local agent was installed from, to
	// say where it came from; empty for a registry release.
	Folder string `yaml:"folder,omitempty" json:"folder,omitempty"`
	// Subagents are the subagents the release declares, each pinned to the
	// version its constraint resolved to when it was installed.
	Subagents   []SubagentPin `yaml:"subagents,omitempty" json:"subagents,omitempty"`
	InstalledAt time.Time     `yaml:"installedAt" json:"installedAt"`
}

Release is a published agent's install record: the release it runs and the subagents its release declares, as they were pinned at its install.

func LoadRelease added in v0.6.1015

func LoadRelease(home, key string) (Release, error)

LoadRelease reads the install record of the published agent keyed key; a key with none is not installed (fs.ErrNotExist).

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 ReviewOpener added in v0.6.1018

type ReviewOpener func(ctx context.Context) (*engine.ReviewRun, error)

WebOpener and ReviewOpener read the keys a segment's web tools and review grant run with.

func LocalReviewOpener added in v0.6.1018

func LocalReviewOpener(pol *policy.Policy) ReviewOpener

type Roster

type Roster []RosterEntry

Roster is an agent's entries, in a fixed order: its folders, its packs, its servers.

func BuildRoster

func BuildRoster(a Agent, c Config, applied *Applied) Roster

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

func BuildRosterUnder(a Agent, c Config, applied *Applied, malwareCheck bool) Roster

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

func QueryRoster(ctx context.Context, home, name string) (Roster, error)

QueryRoster asks the running agent's supervisor for its roster.

func RequestChange

func RequestChange(ctx context.Context, home, name string, ch Change) (Roster, error)

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.
	ShareSwitch string `json:"shareSwitch,omitempty"`
	Share       bool   `json:"share,omitempty"`
	ShareLine   string `json:"shareLine,omitempty"`
	// 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

type SkillCheck func(ctx context.Context, dir string) (clamav bool, err error)

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 Stage

type Stage = engine.Stage

Stage is a step a segment's start has reached (engine.Stage).

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.

func QueryStatus

func QueryStatus(ctx context.Context, home, name string) (Status, error)

QueryStatus asks the running agent's supervisor for its status.

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.

func RequestStop

func RequestStop(ctx context.Context, home, name string) (Stopped, error)

RequestStop asks the running agent's supervisor to stop it, and returns once the segment's envelope is written.

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 Subagent added in v0.7.1

type Subagent struct {
	Ref, Version, Why, Reach string
	// GrantedBy is GrantedByRelease for one the release pins, GrantedByYou
	// for one the person added.
	GrantedBy string
}

Subagent is one subagent of an agent as its roster names it.

func SubagentNamed added in v0.7.1

func SubagentNamed(a Agent, c Config, ref string) (Subagent, bool)

SubagentNamed is the agent's subagent ref, if it has one.

func Subagents added in v0.7.1

func Subagents(a Agent, c Config) []Subagent

Subagents are the agent's subagents: those its release pins to a version, then those the person added under a reference the release does not use. An agent from an author's folder has none.

func (Subagent) Exact added in v0.7.1

func (s Subagent) Exact() string

Exact is the subagent's ns/name@version.

type SubagentHost added in v0.7.1

type SubagentHost interface {
	// Check reads exact (ns/name@version) on registry ("" is this
	// computer's default): how to run it, or why it may not run now. An
	// error is said to the agent as it is.
	Check(ctx context.Context, registry, exact string) (SubagentUsage, error)
	// Run runs exact as an ordinary autonomous run on this computer, with
	// the task, the answers and the files (host paths) given, writing its
	// output folder at OutDir, and answers its envelope.
	Run(ctx context.Context, r SubagentRunSpec) (*receipt.Envelope, error)
}

SubagentHost is what a client gives the supervisor to run the agent's subagents: the CLI's runs each as a run of its own binary, the desktop's through its run service.

type SubagentPin added in v0.6.1015

type SubagentPin struct {
	// Ref is the subagent's ns/name, Constraint the release's semver
	// constraint for it and Why its reason, as the release declares them.
	Ref        string `yaml:"ref" json:"ref"`
	Constraint string `yaml:"constraint" json:"constraint"`
	Why        string `yaml:"why" json:"why"`
	// Version is the version the constraint resolved to at the install;
	// empty when it resolved to none, with Unresolved saying why.
	Version    string `yaml:"version,omitempty" json:"version,omitempty"`
	Unresolved string `yaml:"unresolved,omitempty" json:"unresolved,omitempty"`
	// Reach is what that version's contract reaches, in a line, as its
	// roster entry's sentence quotes it.
	Reach string `yaml:"reach,omitempty" json:"reach,omitempty"`
}

SubagentPin is one subagent a published agent's release declares, pinned at its install.

type SubagentQuestion added in v0.7.1

type SubagentQuestion struct {
	ID       string   `json:"id"`
	Type     string   `json:"type"`
	Required bool     `json:"required"`
	Prompt   string   `json:"prompt"`
	Choices  []string `json:"choices,omitempty"`
	Answer   string   `json:"answer,omitempty"`
}

SubagentQuestion is one of a subagent's questions and how to answer it.

type SubagentRunSpec added in v0.7.1

type SubagentRunSpec struct {
	Registry string
	Exact    string
	Task     string
	Answers  map[string]string
	Files    []string
	OutDir   string
}

SubagentRunSpec is one subagent run a SubagentHost starts.

type SubagentUsage added in v0.7.1

type SubagentUsage struct {
	Questions []SubagentQuestion `json:"questions,omitempty"`
}

SubagentUsage is how a subagent's version is run: its questions.

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) Answer added in v0.7.1

func (s *Supervisor) Answer(id string, yes bool) error

Answer takes the person's answer to the question id, as an answer over the owner socket is taken.

func (*Supervisor) Ask added in v0.7.1

func (s *Supervisor) Ask(ctx context.Context, title, text string) error

Ask puts title and text to the person through the attached clients and waits for the first answer: nil for a yes, ErrNotAgreed for a no, ErrNobodyToAsk when no client is attached to ask, ErrNotAnswered when no answer comes in time.

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) OnQuestion added in v0.7.1

func (s *Supervisor) OnQuestion(ask func(Question)) func()

OnQuestion sends the agent's questions to ask as well as to the clients attached to the owner socket: a client that supervises the agent in its own process (Agentry Desktop) draws them and answers with Answer. The func it answers stops that.

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

func (s *Supervisor) Status() Status

Status is the agent's state now.

func (*Supervisor) Stop

func (s *Supervisor) Stop(ctx context.Context) (*receipt.Envelope, error)

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 Switch

type Switch struct {
	ID string `json:"id"`
	On bool   `json:"on"`
}

Switch is a roster switch.

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

func RequestTaskChange(ctx context.Context, home, name string, op TaskOp) ([]Task, error)

RequestTaskChange asks the running agent's supervisor to pause, resume or remove one of its tasks.

func RequestTasks

func RequestTasks(ctx context.Context, home, name string) ([]Task, error)

RequestTasks asks the running agent's supervisor for its tasks.

func TaskList

func TaskList(home string, a Agent) ([]Task, error)

TaskList is the agent's tasks while it is not running, each with its next fire.

func TasksOf

func TasksOf(ctx context.Context, home string, a Agent) ([]Task, bool, error)

TasksOf are an agent's tasks: its supervisor's while it runs, its file's while it does not.

type TaskOp

type TaskOp struct {
	ID string `json:"id"`
	Op string `json:"op"`
}

TaskOp is a person's change to a task: pause, resume or remove.

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 LoadTasks

func LoadTasks(home, name string) (Tasks, error)

LoadTasks reads the agent's tasks; none when it has no file.

func (*Tasks) AddTask

func (ts *Tasks) AddTask(spec TaskSpec, now time.Time) (Task, error)

AddTask registers a task the agent made.

func (*Tasks) ApplyOp

func (ts *Tasks) ApplyOp(op TaskOp, now time.Time) error

ApplyOp applies a person's pause, resume or remove.

func (Tasks) Listed

func (ts Tasks) Listed(now time.Time) []Task

Listed are the tasks with each one's next fire set, from now.

func (*Tasks) RemoveTask

func (ts *Tasks) RemoveTask(id string) (Task, error)

RemoveTask removes the task id.

func (*Tasks) UpdateTask

func (ts *Tasks) UpdateTask(id string, spec TaskSpec, now time.Time) (Task, error)

UpdateTask changes the task id as spec says.

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

func LoadUsage

func LoadUsage(home, name string) (Usage, error)

LoadUsage reads usage.json; none is the zero Usage.

type Voice added in v0.6.1017

type Voice func(ctx context.Context) (*engine.AttachedVoice, error)

Voice opens the person's Writing Voice for a segment: the one they keep, as a run attaches it. It refuses when they keep none.

type WebOpener added in v0.6.1018

type WebOpener func(ctx context.Context) (*engine.WebRun, error)

WebOpener and ReviewOpener read the keys a segment's web tools and review grant run with.

func LocalWebOpener added in v0.6.1018

func LocalWebOpener(pol *policy.Policy) WebOpener

LocalWebOpener and LocalReviewOpener read the keys from the runner policy as work on this computer does: the person's TypeSafe key, and for the web tools the search provider's key when the policy names one.

type When added in v0.7.1

type When struct {
	// Kind is once, daily, weekdays, weekly or monthly.
	Kind string `json:"kind"`
	// Date is a once schedule's day (YYYY-MM-DD).
	Date string `json:"date,omitempty"`
	// Time is HH:MM, 24-hour.
	Time string `json:"time"`
	// Days are a weekly schedule's (mon … sun).
	Days     []string `json:"days,omitempty"`
	MonthDay int      `json:"monthDay,omitempty"`
}

When is when a schedule a helper tool makes runs.

func ParseWhen added in v0.7.1

func ParseWhen(s string, now time.Time) (When, error)

ParseWhen reads when a schedule runs, in the words whenForms lists.

func (When) Args added in v0.7.1

func (w When) Args() ([]string, error)

Args are the agentry schedule add flags that say w.

func (When) Describe added in v0.7.1

func (w When) Describe() string

Describe is when w runs, in a phrase.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL