toolsrv

package
v0.6.1009 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 51 Imported by: 0

Documentation

Overview

Package toolsrv implements the Agentry companion tools server: one MCP stdio server whose tool surface is constructed from the manifest's capability contract. An undeclared capability means the tool is ABSENT from tools/list, not present-but-refusing: the model never sees a tool it was not granted.

This package is part of the embedded runner-image build context and therefore MUST remain stdlib-only; a unit test in the parent package enforces that.

Index

Constants

View Source
const (
	ToolBackgroundOutput = "background_output"
	ToolStopBackground   = "stop_background"
)

The tools that read and end a background program, granted with Exec.Any.

View Source
const (
	ToolCalendarFeeds    = "calendar_feeds"
	ToolCalendarEvents   = "calendar_events"
	ToolCalendarFreeTime = "calendar_free_time"
)

The calendar tools.

View Source
const (
	// MaxCalendarFeedBytes is the largest feed read.
	MaxCalendarFeedBytes = 10 << 20
	// CalendarFetchTimeout bounds one feed's fetch.
	CalendarFetchTimeout = 30 * time.Second
	// CalendarCacheFor is how long a fetched feed is answered from before
	// it is fetched again.
	CalendarCacheFor = 5 * time.Minute

	// MaxCalendarFeeds is the most feeds a spec may name.
	MaxCalendarFeeds = 20
)

Bounds on the calendar tools.

View Source
const (
	InputsIndexFile   = "inputs.json"
	InputsIndexSchema = "inputs/v1"
	InputsTextSubdir  = "text"
	// InputsConvertedSubdir holds the Markdown view of a file read as
	// text: HTML converted by pandoc.
	InputsConvertedSubdir = "converted"
)

The decoded-inputs layout the engine writes and this server reads.

View Source
const (
	ViewText     = "text"
	ViewOriginal = "original"
)

The two views of an input.

View Source
const (
	FormReport = "report"
	FormLetter = "letter"
	FormMemo   = "memo"
)

The forms of a PDF: the document's shape, which the agent chooses per export.

View Source
const (
	DefaultMaxResultBytes = 48 << 10
	DefaultMaxResultLines = 1900
)

The default budget, docker-agent's (the default harness): its hook's 50 KiB and 2,000 lines, less a margin for the notice a page ends with and for what the harness adds around the text.

View Source
const (
	MaxPDFSourceBytes = 1 << 20
	MaxPDFImages      = 20
	MaxPDFImageBytes  = 10 << 20
	// MaxPDFBytes caps the PDF itself.
	MaxPDFBytes      = 64 << 20
	PDFRenderTimeout = 60 * time.Second
	PDFRenderMemory  = 1 << 30
)

The limits of one export.

View Source
const (
	RenderRequestExt = ".json"
	RenderPageExt    = ".page"
	RenderFailExt    = ".fail"
)

The hand-off's file names, by request id.

View Source
const (
	// ReviewFileBytes is the most of one file a scan or the rubric reads:
	// stage S1's text cap, past which the registry reports the file as not
	// fully scanned.
	ReviewFileBytes = 1 << 20
	// ReviewTotalBytes is the most text one ai_review call sends.
	ReviewTotalBytes = 4 << 20
	// ReviewMaxFiles is the most files one ai_review call reads.
	ReviewMaxFiles = 500
	// DefaultMaxReviewCalls bounds ai_review calls a run.
	DefaultMaxReviewCalls = 3
)

The review's bounds.

View Source
const (
	ToolGrep = "grep"
	ToolGlob = "glob"
)

The search tools, granted with Search.

View Source
const (
	// SearchMemory is ripgrep's address space.
	SearchMemory = 512 << 20
	// SearchTimeout is how long one search may run.
	SearchTimeout = 30 * time.Second
)

The bounds of one search.

View Source
const (
	// ShareClean: ClamAV checked the bytes and found nothing.
	ShareClean = "clean"
	// ShareFound: ClamAV found Signature in the bytes.
	ShareFound = "found"
	// ShareUnchecked: the runner did not check the bytes with ClamAV
	// (Reason says why: the malware check is off on this computer, no
	// signatures on it, a file larger than the check takes). Read as it
	// is, as a run's inputs are then.
	ShareUnchecked = "unchecked"
)

The verdicts a checked file can have.

View Source
const (
	DefaultMaxReadBytes       = 256 << 10
	DefaultMaxWriteBytes      = 1 << 20
	DefaultMaxFetchBytes      = 512 << 10
	DefaultMaxExecOutputBytes = 256 << 10
	DefaultExecTimeoutSeconds = 120
)

Defaults for Limits zero values.

View Source
const (
	ToolFSRead     = "fs_read"
	ToolFSList     = "fs_list"
	ToolFSWrite    = "fs_write"
	ToolFetch      = "fetch"
	ToolRunCommand = "run_command"
	ToolListInputs = "list_inputs"
	ToolReadInput  = "read_input"
	// ToolSearchInputs searches the inputs' text, granted with
	// InputsTextDir.
	ToolSearchInputs = "search_inputs"
	ToolWriteReport  = "write_report"
	// The scratch folder's tools, granted with ScratchDir.
	ToolScratchList   = "scratch_list"
	ToolScratchRead   = "scratch_read"
	ToolScratchWrite  = "scratch_write"
	ToolScratchSearch = "scratch_search"
	// The knowledge tools, granted only while a
	// pack is attached.
	ToolKnowledgeList   = "knowledge_list"
	ToolKnowledgeSearch = "knowledge_search"
	ToolKnowledgeRead   = "knowledge_read"
	// The Writing Voice's one tool, granted
	// only while a voice is attached.
	ToolVoiceRead = "voice_read"
	// The web tools, the built-in Drafter's
	// alone: web_search only when the run has a search to use.
	ToolWebSearch      = "web_search"
	ToolWebRead        = "web_read"
	ToolRegistrySearch = "registry_search"
	// The review grant's tool: a built-in granted review alone.
	ToolAIReview = "ai_review"
)

Tool names, the closed surface of the server. The compiler writes these into the plan's tool-grant list and the gateway tools.yaml allowlist; the server registers exactly the granted subset.

View Source
const (
	WebScanRegistry = "registry"
	WebScanJev      = "jev"
)

Where a scan or a search goes.

View Source
const (
	EnvWebJobToken  = "AGENTRY_WEB_JOB_TOKEN"
	EnvWebJevKey    = "AGENTRY_WEB_JEV_KEY"
	EnvWebSearchKey = "AGENTRY_WEB_SEARCH_KEY"
)

The environment variables the gateway injects into this container alone, from the run's secrets file. None of them reaches the agent container.

View Source
const (
	// PageTextBytes is the most text a page gives the model: four of the
	// judge's 8 KiB chunks.
	PageTextBytes = 32 << 10
	// DefaultMaxPages, DefaultMaxSearches and DefaultMaxRegistryCalls are
	// a run's calls (60 pages, 30 searches to start with).
	DefaultMaxPages         = 60
	DefaultMaxSearches      = 30
	DefaultMaxRegistryCalls = 60
)

The web tools' bounds.

View Source
const DecodedFetchFactor = 64

DecodedFetchFactor is how many times the reply cap a body may decode to. A compressor does well on text (ten to twenty times) and far better on a body built to be small encoded, so the limit sits well above real pages and far below what a few hundred encoded bytes can expand to.

View Source
const DefaultTheme = reportdesign.DefaultID

DefaultTheme is the built-in theme a run gets when nothing chooses another: Plain.

View Source
const EnvReviewJevKey = "AGENTRY_REVIEW_JEV_KEY"

EnvReviewJevKey carries the person's own TypeSafe key into this container alone, from the run's secrets file. It never reaches the agent container.

View Source
const FetchTimeout = 60 * time.Second

FetchTimeout is how long fetch waits for one request, redirects included, before it gives up. The Drafter's guide states it (its runtime facts are generated from it).

View Source
const InputResourceURI = "agentry://inputs"

InputResourceURI names the embedded resource an input tool's answer travels in. The answer itself says which file and page it is.

View Source
const MaxBlockedReason = 500

MaxBlockedReason bounds the sentence end_blocked keeps, in bytes.

View Source
const MaxDeliverableTitleRunes = 120

MaxDeliverableTitleRunes is the longest title a deliverable takes.

View Source
const MaxVoiceBytes = 32 << 10

MaxVoiceBytes bounds what voice_read returns: the format's cap, restated because this package imports nothing outside the standard library (pkg/runner/engine's TestTheToolsServerHoldsTheVoiceCap pins the two equal).

View Source
const (
	NotReadOverBudget = "past what one review sends (4 MiB, 500 files)"
)

The reasons a file is left out, as ai_review says them.

View Source
const RenderTextMin = 1024

RenderTextMin is the text a fetched HTML page must hold, trimmed, for web_read to take it without rendering it.

View Source
const RenderTimeout = 120 * time.Second

RenderTimeout bounds one render, the browser's start included: on a busy machine, under the run's CPU and memory bounds, Chromium alone can take most of a minute to start.

View Source
const RereadStub = "unchanged since your earlier call in this turn; call again with fresh: true for the text"

RereadStub is a re-read's answer.

View Source
const ReviewHost = "api.typesafe.ai"

ReviewHost is the one host a review's tools container reaches: TypeSafe's API, judge.DefaultBaseURL's host (a test holds the two equal).

View Source
const RipgrepDir = "/opt/agentry/ripgrep"

RipgrepDir is where the runner image holds ripgrep and its licences, copied by digest from agentry-ripgrep. It is outside every bin directory, so an exec image's minimize keeps it and no declared command finds it on a PATH.

View Source
const RipgrepVersion = "15.2.0"

RipgrepVersion is the ripgrep release in the pinned image, for the plan's enforcement text and the tools' errors.

View Source
const ShareFormats = "" /* 226-byte string literal not displayed */

ShareFormats names the documents whose text the share's check reads out for fs_read: the decode step's readers.

View Source
const ShareTextDir = "text"

ShareTextDir is the folder beside the verdicts file that holds the text the decode step read out of each checked document, one file a digest: <SHA-256>.txt.

View Source
const ShareVerdictsVersion = 2

ShareVerdictsVersion is the verdicts file's version.

View Source
const SpecVersion = "17"

SpecVersion is the current tool-server spec schema version. "2" added the run-inputs channel; "3" the knowledge packs a run may search; "4" the built-in Drafter's web tools; "5" the review grant; "6" the decoded inputs and search_inputs; "7" the calls ledger and end_blocked; "8" the scratch folder; "9" export_pdf; "10" the report design, theme document version 2, and export_pdf's form; "11" the result budget (Limits.MaxResultBytes and MaxResultLines); "12" grep and glob (Search); "13" the deliverables ledger and write_report's and export_pdf's deliverable and title; "14" the rendered web_read (Web.Render); "15" the given-only web_read (Web.GivenOnly and Web.Given); "16" a persistent agent's folders (WorkspaceName) and the share's checks (ShareChecks); "17" the calendar feeds (Calendar). The server refuses other versions, so a stale runner image meets a newer compiler loudly — and the image tag derives from the CLI version, so rebuilds happen on their own at upgrade time.

View Source
const ToolDependencyScan = "dependency_scan"

ToolDependencyScan is the tool's name.

View Source
const ToolEndBlocked = "end_blocked"

ToolEndBlocked ends a one-shot run as blocked; granted only with the calls ledger.

View Source
const ToolExportPDF = "export_pdf"

ToolExportPDF renders a Markdown file to a PDF in reports/.

View Source
const TypstDir = "/opt/agentry/typst"

TypstDir is where the runner image holds the renderer (copied by digest from agentry-typst): the binary, the fonts and the vendored packages. It is outside every bin directory, so an exec image's minimize keeps it, and no declared command finds it on a PATH.

View Source
const TypstVersion = "0.15.1"

TypstVersion is the Typst release in the pinned image, for the plan's enforcement text and the tool's errors.

Variables

View Source
var ConfineRole = confine.Role

ConfineRole is the argument that makes this process's own binary the confine trampoline: the runner image's `confine`. The CLI's hidden runner-tools sets its own command's name.

Forms are export_pdf's forms, the default first.

Functions

func BudgetWords

func BudgetWords(bytes int64, lines int) string

BudgetWords says a result budget as the System Prompt and the notices say it: "48 KiB and 1,900 lines".

func BuiltinTheme

func BuiltinTheme(name string) ([]byte, error)

BuiltinTheme is a built-in theme's document as the core ships it, its canonical form.

func BuiltinThemes

func BuiltinThemes() []string

BuiltinThemes are the ids of the built-in themes, Plain first.

func CalendarService added in v0.6.999

func CalendarService(host string) string

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

func CalendarSessionHeader added in v0.6.999

func CalendarSessionHeader(session string) (string, error)

CalendarSessionHeader is the Cookie header a feed's browser sign-in sends: every cookie it holds, by name and value.

func CalendarSessionValues added in v0.6.999

func CalendarSessionValues(session string) []string

CalendarSessionValues are the cookie values of a feed's browser sign-in long enough to mask on their own, beside the sign-in whole; none for a sign-in that cannot be read.

func CalendarSignInHost added in v0.6.999

func CalendarSignInHost(host string) bool

CalendarSignInHost says host is a sign-in page a calendar's address sends a fetch to when it answers a signed-in browser alone.

func CheckDeliverableTitle

func CheckDeliverableTitle(title string) error

CheckDeliverableTitle holds a title to the rule the report design's free texts keep: one line of plain, printable text of at most MaxDeliverableTitleRunes characters, with no control, line-break or bidirectional formatting character that could make it read otherwise than it is written. The runner holds a ledger's titles to it again.

func HTMLText

func HTMLText(body []byte, base *url.URL) string

HTMLText is the text of an HTML page as web_read gives it: what a reader sees, with the markup stripped. Scripts, styles, templates, embedded documents and elements marked hidden (the hidden attribute, aria-hidden="true", an inline display:none or visibility:hidden) are left out; headings, list items, paragraphs and line breaks become lines; a link keeps its absolute http or https address after its text, so the Drafter can follow it. Entities are decoded.

It is a reader's view, not a parser's: malformed markup degrades to less text, never to markup. What is left is still read by AI Review before a model sees it; leaving hidden text out only means the model is not given what a person would not see either.

func IsBuiltinTheme

func IsBuiltinTheme(name string) bool

IsBuiltinTheme says whether name is a built-in theme's id.

func LooksText

func LooksText(head []byte) bool

LooksText is stage S1's text sniff (the core's pkg/archive LooksText, which this stdlib-only image cannot import; a test holds the two equal): no NUL byte, and under 5% control characters, over the first 512 bytes.

func ParseCalendarSession added in v0.6.999

func ParseCalendarSession(session string) ([]*http.Cookie, error)

ParseCalendarSession reads a feed's browser sign-in as the cookies to fetch it with, each with the domain and path it was set for, so the one a host renews replaces it. Secure is set on every one: the feed is fetched by https alone.

func PrepareMounts

func PrepareMounts(spec *Spec) error

PrepareMounts readies the tools container's /tmp and scratch folder before the tools role serves. Where the run's docker filter mounts them as size-capped tmpfs (spec.TmpfsBytes, on a Linux host), it refuses to serve unless both are tmpfs no larger than that cap: without them a declared command or scratch_write would write the host's disk without bound, so the tools server never answers, the gateway's health check fails, and the run stops (exit 13) rather than run unbounded. Under Docker Desktop, which runs no filter, it makes the scratch folder in the container's own layer instead, anyone may write it, and neither is bounded. The image's tools role calls it; `agentry runner-tools`, the debugging path that never runs a QuickAgent, does not.

func ReviewSecretEnv

func ReviewSecretEnv() []string

ReviewSecretEnv is every key the review grant may be given.

func Serve

func Serve(in io.Reader, out io.Writer, logw io.Writer, spec *Spec) error

Serve runs the MCP loop until in closes (the gateway closing stdin is the shutdown signal — no other lifecycle exists for a per-run server). Diagnostics go to logw (stderr in the container); out carries protocol lines only, because anything else on stdout corrupts the stream.

func ShareTextName

func ShareTextName(sum string) string

ShareTextName is the name, in ShareTextDir, of the text kept for the bytes whose SHA-256 is sum.

func ShippedFile

func ShippedFile(ships []string, rel string) bool

ShippedFile reports whether a package path is a shipped pack's text, a file under knowledge/<name>/wiki/ or knowledge/<name>/sources/, as the core's manifest.ShippedPackFile reads it (a test holds the two equal): the registry's stage for packs reads those, and its S5 every other file, a pack's other files included.

func ShippedPacks

func ShippedPacks(manifestJSON []byte) []string

ShippedPacks are the knowledge packs a manifest's canonical JSON ships, as the core's manifest.ShippedPacksOf reads them (a test holds the two equal).

func WebSecretEnv

func WebSecretEnv() []string

WebSecretEnv is every key the web tools may be given, sorted.

Types

type Access

type Access struct {
	// Enabled is false when the capability was not declared (mode none or
	// undeclared): the corresponding tools are not registered at all.
	Enabled bool `json:"enabled"`
	// Paths, when non-empty, restricts access to exactly these
	// workspace-relative paths (manifest filesystem {paths: [...]} mode).
	// An entry grants the file itself and, if it names a directory,
	// everything under it. Empty with Enabled=true means the whole
	// workspace (manifest "workspace" mode).
	Paths []string `json:"paths,omitempty"`
}

Access is one direction of filesystem access inside the workspace.

type Calendar added in v0.6.999

type Calendar struct {
	Feeds []CalendarFeed `json:"feeds,omitempty"`
	// TimeZone is the IANA name of the person's zone; empty is UTC.
	TimeZone string `json:"timeZone,omitempty"`
}

Calendar is the calendar feeds' grant: the feeds a persistent Assistant has on, and the person's time zone, in which times are answered.

type CalendarFeed added in v0.6.999

type CalendarFeed struct {
	Name       string `json:"name"`
	Host       string `json:"host"`
	URLEnv     string `json:"urlEnv"`
	SessionEnv string `json:"sessionEnv,omitempty"`
}

CalendarFeed is one feed: the name the person gave it, the host its address names, the variable of this server's environment that holds the address and, for a feed signed in through a browser, the one that holds the sign-in's cookies (ParseCalendarSession).

type CalendarSessionCookie added in v0.6.999

type CalendarSessionCookie struct {
	Name   string `json:"n"`
	Value  string `json:"v"`
	Domain string `json:"d,omitempty"`
	Path   string `json:"p,omitempty"`
}

CalendarSessionCookie is one cookie of a feed's browser sign-in, as it is kept: a JSON list of them is the sign-in (CalendarFeed.SessionEnv).

type CallEntry

type CallEntry struct {
	Start   bool   `json:"start,omitempty"`
	Tool    string `json:"tool,omitempty"`
	OK      bool   `json:"ok,omitempty"`
	Fault   bool   `json:"fault,omitempty"`
	Blocked string `json:"blocked,omitempty"`
}

CallEntry is one line of the calls ledger. It names the tool and whether the call answered without an error, never its arguments: an input's name is the person's. Fault says a failed call failed on the run's own machinery (failed), which nothing the agent asks can bring about; only such a failure is the runner's evidence, so an agent cannot earn a refunded run by asking for a file that is not there. Blocked is the agent's own sentence from end_blocked.

type Calls

type Calls struct {
	// Ledger is the container path the ledger is appended to, under OutDir:
	// a start line when the server starts, then one line a tool call.
	Ledger string `json:"ledger,omitempty"`
}

Calls is the calls ledger's grant. The engine stamps Ledger into a release's one-shot run alone, never into the compiled plan (a session's plan is the same bytes), and end_blocked exists only then.

type DeliverableEntry

type DeliverableEntry struct {
	Path   string `json:"path"`
	Title  string `json:"title,omitempty"`
	Marked bool   `json:"marked"`
}

DeliverableEntry is one line of the deliverables ledger: a path under reports/ (as the output folder spells it, reports/…) the agent marked, with its title, or, with Marked false, a path it took the mark off again. The last line for a path wins.

type Deliverables

type Deliverables struct {
	// Ledger is the container path each mark is appended to, under OutDir.
	Ledger string `json:"ledger,omitempty"`
}

Deliverables is the deliverables ledger's grant. The engine stamps Ledger into the run's own copy of the spec, never into the compiled plan; a spec without one still serves both tools, which then cannot mark a file.

type DependencyScan added in v0.6.999

type DependencyScan struct {
	// DBDir is where OSV's databases are mounted: osv-scalibr/<ecosystem>/
	// all.zip beneath it.
	DBDir string `json:"dbDir"`
	// Ecosystems are the ecosystems the runner keeps a database of.
	Ecosystems []string `json:"ecosystems,omitempty"`
}

DependencyScan configures dependency_scan (under Exec.Any).

type Exec

type Exec struct {
	// Commands is the manifest exec allowlist; empty disables the tool.
	// Enforcement is argv[0] membership plus a shim PATH containing only
	// these commands.
	Commands []string `json:"commands,omitempty"`
	// ImagePath is Unsafe Mode's: a declared
	// command runs with the image's own PATH after the shim directory,
	// so a declared script finds its interpreter and the programs it
	// calls (Ghidra's analyzeHeadless is a `#!/usr/bin/env bash` script
	// that runs java). The argv[0] allowlist is unchanged: only a declared
	// command can be called. Off, the PATH is the shim directory alone.
	ImagePath bool `json:"imagePath,omitempty"`
	// Any is the Coding agent's run_command: any program the image holds,
	// named on its PATH or by a path, with no allowlist and no shims, run in
	// a folder beneath the workspace the call names, as Owner where the spec
	// names one, held by the same confinement as a declared command. Only a
	// tools server in the Coding agent's own exec image is given it.
	Any bool `json:"any,omitempty"`
	// Home is HOME under Any: a folder beneath the workspace, made when the
	// server starts, so a command's caches and settings last as long as the
	// workspace does.
	Home string `json:"home,omitempty"`
	// Ports under Any are the server's ports the person's computer
	// publishes, each at its 127.0.0.1 and the same number: run_command's
	// description names them, so the agent serves where the person looks.
	Ports []Port `json:"ports,omitempty"`
	// SecretEnv under Any names variables of this server's environment, the
	// person's stored secrets, that a program is given as they are. Each
	// whole value is masked wherever it appears in a result of this
	// server's tools, and a file a tool writes may not hold one.
	SecretEnv []string `json:"secretEnv,omitempty"`
	// Accounts under Any are the person's git host accounts: a program is
	// given each one's token as git's credential for that host alone and in
	// the variables its host's CLI reads, and the commit identity in a
	// repository whose remote is on that host. Each token's variable is
	// also in SecretEnv, so it is masked as a stored secret is.
	Accounts []GitAccount `json:"accounts,omitempty"`
	// DependencyScan under Any grants dependency_scan, over OSV's
	// databases mounted at its DBDir.
	DependencyScan *DependencyScan `json:"dependencyScan,omitempty"`
}

Exec configures run_command.

type Fetch

type Fetch struct {
	// Enabled is true only when the manifest declared an egress host list
	// (or the policy-gated wildcard).
	Enabled bool `json:"enabled"`
	// Hosts are the exact DNS names requests may target.
	Hosts []string `json:"hosts,omitempty"`
	// AllowAll is the policy-gated "*" egress; the receipt discloses it.
	AllowAll bool `json:"allowAll"`
	// SecretEnv lists the environment variable NAMES (manifest secrets:)
	// the fetch tool may inject as auth headers. The gateway injects the
	// values into this container only; the tool never returns them to the
	// model.
	SecretEnv []string `json:"secretEnv,omitempty"`
	// Ledger is the container path each body fetch saves in the scratch
	// folder is recorded in, one JSON line a file (SaveEntry), under OutDir:
	// a body saved because the agent asked (saveTo) or because it was larger
	// than one result. The engine stamps it into the run's own copy of this
	// file, never into the compiled plan, and the receipt counts it.
	Ledger string `json:"ledger,omitempty"`
}

Fetch configures the HTTP tool. The gateway enforces the same host list at the container level (allowHosts + --block-network); this server-side check is the belt to that braces, and the only place redirects are re-validated hop by hop.

type GitAccount added in v0.6.999

type GitAccount struct {
	// Host is host[:port], in lower case.
	Host string `json:"host"`
	// Kind is github, gitlab, gitea or git.
	Kind string `json:"kind"`
	// Own says it is the agent's own account rather than the person's.
	Own   bool   `json:"own,omitempty"`
	User  string `json:"user"`
	Name  string `json:"name"`
	Email string `json:"email"`
	// TokenEnv is the variable of this server's environment holding the
	// token.
	TokenEnv string `json:"tokenEnv"`
}

GitAccount is one of the Coding agent's git host accounts.

type InputEntry

type InputEntry struct {
	// Path is the input's slash path under InputsDir.
	Path string `json:"path"`
	// Type is the kind of file the decode step detected (pdf, document,
	// image, text, …).
	Type string `json:"type"`
	// Bytes is the size of the input as given.
	Bytes int64 `json:"bytes"`
	// Unread, when set, is why the input could not be read; empty means
	// it was read.
	Unread string `json:"unread,omitempty"`
	// Decoded says its text is at InputsTextSubdir/<Path>; a read input
	// that was not decoded is text, read as it is.
	Decoded   bool   `json:"decoded,omitempty"`
	DecodedBy string `json:"decodedBy,omitempty"`
	// TextBytes is the size of the text read_input serves for it.
	TextBytes int64 `json:"textBytes,omitempty"`
	// InArchive is the archive it was unpacked from: its Path is
	// <archive>/<member>, it is not under InputsDir, and its text, decoded or
	// read as it is, is at InputsTextSubdir/<Path>.
	InArchive string `json:"inArchive,omitempty"`
	// Unpacked says it is an archive whose members are entries of their
	// own; Partial, when set, is why only part of it was unpacked.
	Unpacked bool   `json:"unpacked,omitempty"`
	Partial  string `json:"partial,omitempty"`
	// MIME is the type the decode step detected it as, from its fixed
	// vocabulary's shape; a binary original's page names it.
	MIME string `json:"mime,omitempty"`
	// Converted says a file read as text also has a Markdown text view at
	// InputsConvertedSubdir/<Path>, written by ConvertedBy (pandoc, for
	// HTML), ConvertedBytes long.
	Converted      bool   `json:"converted,omitempty"`
	ConvertedBy    string `json:"convertedBy,omitempty"`
	ConvertedBytes int64  `json:"convertedBytes,omitempty"`
	// Original says an input that is Unread, since no decoder reads it,
	// can still be read as uploaded: a file as staged that no reader
	// took, never one ClamAV found, refused, or inside a .git folder.
	Original bool `json:"original,omitempty"`
	// contains filtered or unexported fields
}

InputEntry is one input. Its Type and outcome restate the decode report's own (runnerimage/decode) as plain strings: this package is stdlib-only and independent of its siblings, and the engine fills them only from the decode's fixed vocabulary.

func (InputEntry) Outcome

func (e InputEntry) Outcome() string

Outcome is the entry's outcome as list_inputs says it.

type InputsIndex

type InputsIndex struct {
	Schema string `json:"schema"`
	// DefaultView is the release's own default (its manifest's
	// inputs.view): ViewText or ViewOriginal, which each
	// input that has that view is read in when the model asks for none.
	// Empty keeps each input's own default.
	DefaultView string       `json:"defaultView,omitempty"`
	Files       []InputEntry `json:"files"`
}

InputsIndex is every input of the run and what the decode step made of it, in path order.

type KnowledgePack

type KnowledgePack struct {
	Name   string `json:"name"`
	Digest string `json:"digest"`
}

KnowledgePack is one pack mounted under KnowledgeDir/<Name>. The name is what the tools take as their pack argument; the digest is the one the receipt records, so the run's own tool spec names what was attached in the same terms as the receipt.

type LedgerEntry

type LedgerEntry struct {
	Tool   string         `json:"tool"`
	Source webscan.Source `json:"source,omitempty"`
	// URL is the page's final address, a search result's address (its
	// origin alone when it did not pass), or the registry request.
	URL string `json:"url,omitempty"`
	// Bytes is the length of the text scanned.
	Bytes int `json:"bytes,omitempty"`
	// Refused says why a call read nothing (an address, a budget, a type),
	// in the words the model was given; Detail is the error behind it,
	// bounded, for the person.
	Refused string `json:"refused,omitempty"`
	Detail  string `json:"detail,omitempty"`
	// Search marks a web search that answered, with Results results; each
	// result has a line of its own after it.
	Search  bool `json:"search,omitempty"`
	Results int  `json:"results,omitempty"`
	// Rendered marks a page read from what a headless browser drew; Render
	// says why one was asked for and not used.
	Rendered bool   `json:"rendered,omitempty"`
	Render   string `json:"render,omitempty"`
	webscan.Result
}

LedgerEntry is one line of the web ledger: one text a web tool read, or one call it refused before reading anything.

type Limits

type Limits struct {
	// MaxReadBytes caps fs_read (default DefaultMaxReadBytes).
	MaxReadBytes int64 `json:"maxReadBytes,omitempty"`
	// MaxWriteBytes caps fs_write and write_report content (default
	// DefaultMaxWriteBytes).
	MaxWriteBytes int64 `json:"maxWriteBytes,omitempty"`
	// MaxFetchBytes caps a fetch response body (default
	// DefaultMaxFetchBytes).
	MaxFetchBytes int64 `json:"maxFetchBytes,omitempty"`
	// MaxExecOutputBytes caps run_command combined output (default
	// DefaultMaxExecOutputBytes).
	MaxExecOutputBytes int64 `json:"maxExecOutputBytes,omitempty"`
	// ExecTimeoutSeconds caps one run_command invocation (default
	// DefaultExecTimeoutSeconds).
	ExecTimeoutSeconds int `json:"execTimeoutSeconds,omitempty"`
	// MaxResultBytes and MaxResultLines are the result budget: the most
	// one tool result may hold, so that the harness never cuts it (page.go).
	// The compiler stamps them
	// from the run's harness adapter, its measured limit less a margin
	// (adapter.ResultBudget); zero takes docker-agent's
	// (DefaultMaxResultBytes, DefaultMaxResultLines). The read tools page
	// within it, and the caps above still apply beneath it.
	MaxResultBytes int64 `json:"maxResultBytes,omitempty"`
	MaxResultLines int   `json:"maxResultLines,omitempty"`
}

Limits bounds tool I/O sizes and exec time.

func (Limits) FitResult

func (l Limits) FitResult(tool, text string) string

FitResult holds a result to the budget, as every result of this server is held (fitResult).

func (Limits) Head

func (l Limits) Head(data []byte) []byte

Head is the longest head of data a page may hold, the notice's room set aside: data itself when it fits, else cut after a line end or on a rune boundary, as a page is.

func (Limits) PageBase64

func (l Limits) PageBase64(data []byte, offset, limit int64, contFmt string) string

PageBase64 is one page of data from offset as base64, within the budget (and limit, when positive): a header naming the bytes the page holds, the encoded page, and the page notice when the data is not read whole.

func (Limits) PageText

func (l Limits) PageText(data []byte, offset, limit int64, contFmt string) (text string, ok bool)

PageText is one page of the text data from offset, within the budget l stamps (and within limit, when it is positive), followed, when data is not read whole, by the page notice saying where to continue (contFmt as pageNote takes it). ok is false when the page is not UTF-8, so the caller can offer the bytes as base64 instead.

func (Limits) Room

func (l Limits) Room() int64

Room is the bytes a page's text may take under the budget, the notice's room set aside.

type Owner

type Owner struct {
	UID int `json:"uid"`
	GID int `json:"gid"`
}

Owner is a POSIX uid/gid pair.

type PDF

type PDF struct {
	Enabled bool `json:"enabled"`
	// Theme is the run's report design;
	// without one, the built-in default, Plain.
	Theme *ThemeStamp `json:"theme,omitempty"`
	// Author names the QuickAgent that wrote the report,
	// namespace/name@version, for the PDF's metadata: never the
	// person.
	Author string `json:"author,omitempty"`
	// Ledger is the container path each exported PDF is recorded in,
	// under OutDir.
	Ledger string `json:"ledger,omitempty"`
}

PDF is export_pdf's grant. The compiler sets Enabled with the scratch folder, for every package but a built-in; the engine stamps the rest into the run's own copy of the spec, never the compiled plan.

type PDFEntry

type PDFEntry struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Pages  int    `json:"pages"`
	Bytes  int64  `json:"bytes"`
	// Form is the form the agent chose for it.
	Form string `json:"form,omitempty"`
	Logo bool `json:"logo,omitempty"`
}

PDFEntry is one line of the PDF ledger: a PDF export_pdf wrote. Path is relative to the output folder (reports/…).

type Port

type Port struct {
	Name string `json:"name"`
	Port int    `json:"port"`
}

Port is one published port.

type RenderRequest

type RenderRequest struct {
	URL string `json:"url"`
}

RenderRequest is a request's file.

type Review

type Review struct {
	Enabled bool `json:"enabled"`
	// Ledger is the container path the review ledger is appended to, one
	// JSON line a file scanned or a call answered.
	Ledger string `json:"ledger,omitempty"`
}

Review configures the review grant. Enabled is compiled (a built-in the CLI grants it to); Ledger is the run's, stamped by the engine.

type ReviewAnswer

type ReviewAnswer struct {
	Model      string `json:"model"`
	RubricHash string `json:"rubricHash"`
	// Axes are all six questions, in the rubric's order; Findings those of
	// them that scored 2 or more.
	Axes     []ReviewAxis    `json:"axes"`
	Findings []ReviewAxis    `json:"findings"`
	Files    []string        `json:"files"`
	NotRead  []ReviewNotRead `json:"notRead,omitempty"`
	// Requests and InputTokens are what the call cost the judge, for the
	// record; AI Review is 1 credit an operation.
	Requests    int   `json:"requests"`
	InputTokens int64 `json:"inputTokens"`
}

ReviewAnswer is ai_review's answer.

type ReviewAxis

type ReviewAxis struct {
	ID string `json:"id"`
	// Score is 0 to 3, as the registry scores it (judge.ScoreFromProbability).
	Score       int       `json:"score"`
	Probability float64   `json:"probability"`
	Samples     []float64 `json:"samples,omitempty"`
	// File is the package path of the chunk that drew the highest
	// probability ("agent.yaml" is the manifest).
	File string `json:"file,omitempty"`
}

ReviewAxis is one rubric question's answer over the package.

type ReviewEntry

type ReviewEntry struct {
	Tool string `json:"tool"`
	// Path is the input file, inputs-relative, and View the view of it
	// read_input was asked for, when one was.
	Path string `json:"path,omitempty"`
	View string `json:"view,omitempty"`
	// Manifest and Dir are what an ai_review call read, inputs-relative and
	// cleaned ("." is the inputs root).
	Manifest string `json:"manifest,omitempty"`
	Dir      string `json:"dir,omitempty"`
	Bytes    int    `json:"bytes,omitempty"`
	// Refused says why a call read nothing, in the words the model was
	// given.
	Refused string `json:"refused,omitempty"`
	// Files and NotRead are what an ai_review call sent and left out.
	Files   int `json:"files,omitempty"`
	NotRead int `json:"notRead,omitempty"`
	// RubricHash names what the rubric asked; Findings counts the questions
	// that scored 2 or more.
	RubricHash string `json:"rubricHash,omitempty"`
	Findings   int    `json:"findings,omitempty"`
	// Axes are an answered ai_review call's six scores, as the model was
	// given them: the record a host post-step reads the review from, so
	// that what it reports never rests on what the model says the tool
	// answered.
	Axes []ReviewAxis `json:"axes,omitempty"`
	webscan.Result
}

ReviewEntry is one line of the review ledger: a file read_input scanned or refused, or one ai_review call.

type ReviewNotRead

type ReviewNotRead struct {
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

ReviewNotRead is a file ai_review left out, and why.

func ReviewFiles

func ReviewFiles(root, manifestAbs string, ships []string) ([]judge.RubricFile, []ReviewNotRead, error)

ReviewFiles is every text file under root, as stage S5 reads a release: package paths relative to root, sorted, the manifest's own staged JSON left out, and a shipped pack's tree left to its own stage. What is left out is named. The Examiner's host pre-step asks it of the staged package too, to know whether one call sends all of it.

type SaveEntry

type SaveEntry struct {
	Path   string `json:"path"`
	Host   string `json:"host"`
	Bytes  int64  `json:"bytes"`
	SHA256 string `json:"sha256"`
	Asked  bool   `json:"asked,omitempty"`
}

SaveEntry is one line of the fetch ledger: a body fetch saved in the scratch folder. Path is relative to the folder and Host is the declared host the request was made to; Asked says the agent named the path (saveTo), where a body larger than one result is saved unasked.

type Search struct {
	Enabled bool `json:"enabled"`
}

Search is grep and glob's grant: Enabled by the compiler with the scratch folder, for every package but a built-in. The tools exist only when the run also has an area to search.

type ShareChecks

type ShareChecks struct {
	Folder string `json:"folder"`
	File   string `json:"file"`
}

ShareChecks is Spec.ShareChecks: the folder beneath WorkspaceDir whose files are checked, and the container path of the verdicts file.

type ShareVerdict

type ShareVerdict struct {
	SHA256    string `json:"sha256"`
	Size      int64  `json:"size"`
	MTimeNano int64  `json:"mtimeNano"`
	Verdict   string `json:"verdict"`
	Signature string `json:"signature,omitempty"`
	Reason    string `json:"reason,omitempty"`
	// Text says the runner kept the text the decode step read out of
	// these bytes, at ShareTextDir/ShareTextName(SHA256); Tool names the
	// reader that read it (pdftotext, pandoc, tesseract, agentry-runner,
	// tika).
	Text bool   `json:"text,omitempty"`
	Tool string `json:"tool,omitempty"`
	// Unread is why no reader could read text out of these bytes, in the
	// decode step's words; empty when one did, or when the file is text.
	Unread string `json:"unread,omitempty"`
}

ShareVerdict is one checked file's verdict, and the bytes it is for.

type ShareVerdicts

type ShareVerdicts struct {
	Version int `json:"version"`
	// Files are the share's checked files, by their slash path beneath the
	// share folder.
	Files map[string]ShareVerdict `json:"files"`
}

ShareVerdicts is the verdicts file the runner writes (ShareChecks.File).

type Spec

type Spec struct {
	// SpecVersion pins the schema ("1"); the server refuses others so a
	// stale image and a newer compiler fail loudly, not subtly.
	SpecVersion string `json:"specVersion"`
	// WorkspaceDir is the container path of the agent workspace mount
	// (conventionally /workspace). The mount's ro/rw flag is enforced by
	// the gateway's volume spec; the server additionally refuses writes
	// when FSWrite is disabled, so the two layers agree.
	WorkspaceDir string `json:"workspaceDir"`
	// WorkspaceName is how the tools' descriptions name WorkspaceDir when
	// it is not the workspace (a persistent agent's folders); empty is
	// "the workspace".
	WorkspaceName string `json:"workspaceName,omitempty"`
	// ShareChecks, when set, holds reads of the person's share folder to
	// ClamAV's verdicts (sharecheck.go): a file beneath Folder is read only
	// when its bytes have a verdict that is not a finding in File, which
	// the runner rewrites before each turn. Set for a persistent agent
	// whose share is checked; unset, the share is read as it is.
	ShareChecks *ShareChecks `json:"shareChecks,omitempty"`
	// TurnFile holds the run's turn count, which the runner rewrites at
	// each turn's start and each compaction; a change starts a new read log
	// (reread.go). Empty: the run is one turn.
	TurnFile string `json:"turnFile,omitempty"`
	// OutDir is the container path of the run's output folder mount
	// (conventionally /out). write_report is rooted at OutDir/reports.
	OutDir string `json:"outDir"`
	// InputsDir is the container path of the read-only run-inputs mount
	// (conventionally /inputs). Inputs are
	// operator-provided task material — a channel like stdin, not a
	// manifest capability — so list_inputs/read_input are granted
	// whenever the dir is configured, and the mount's :ro flag plus the
	// absence of any write tool keep the channel one-way. Empty means the
	// channel is not configured and its tools are absent.
	InputsDir string `json:"inputsDir,omitempty"`
	// InputsTextDir is the container path of the read-only decoded-inputs
	// mount (conventionally /inputs-text): the engine's decode step writes
	// the index of every input there and the text decoded from each
	// (inputs.go). search_inputs is granted with it beside the inputs
	// channel, except under the review grant, where every text reaches the
	// model only through read_input's scan.
	InputsTextDir string `json:"inputsTextDir,omitempty"`
	// KnowledgeDir is the container path of the read-only knowledge mount
	// (conventionally /knowledge), one directory
	// per attached pack. Knowledge names those packs. Like the inputs, a
	// pack the person attaches is task material and not a manifest
	// capability, so the compiled plan never carries either field: the
	// engine stamps both into the run's own copy of this file when packs
	// are attached, and the three knowledge tools exist only then.
	KnowledgeDir string          `json:"knowledgeDir,omitempty"`
	Knowledge    []KnowledgePack `json:"knowledge,omitempty"`
	// Voice is the person's Writing Voice when one is attached: its
	// VOICE.md's container path, under the knowledge mount, and its digest.
	// Like a pack it is chosen at run time and never in the compiled plan:
	// the engine stamps it into the run's own copy of this file, and
	// voice_read exists only then.
	Voice *VoiceFile `json:"voice,omitempty"`
	// ScratchDir is the container path of the run's scratch folder
	// (conventionally /scratch): an empty tmpfs the docker filter mounts,
	// private to the run and gone with the container. scratch_read,
	// scratch_list, scratch_write and scratch_search are granted whenever it
	// is set; the compiler sets it for every package but a built-in. It is a
	// grant of the runner, not a line of the contract, and never aliases the
	// workspace, which FSRead and FSWrite govern.
	ScratchDir string `json:"scratchDir,omitempty"`
	// TmpfsBytes, when set, is the size the run's docker filter caps the
	// tools container's /tmp and ScratchDir at, each a tmpfs (Linux; the
	// filter runs nowhere else). The engine stamps it into the run's own
	// copy of this file, never into the compiled plan, and the tools role
	// then refuses to serve unless both are tmpfs no larger than it
	// (PrepareMounts).
	TmpfsBytes int64 `json:"tmpfsBytes,omitempty"`
	// FSRead gates fs_read and fs_list.
	FSRead Access `json:"fsRead"`
	// FSWrite gates fs_write.
	FSWrite Access `json:"fsWrite"`
	// Fetch gates the fetch tool.
	Fetch Fetch `json:"fetch"`
	// Exec gates the run_command tool.
	Exec Exec `json:"exec"`
	// Web gates the built-in Drafter's web tools (web.go). The compiler
	// sets Enabled for the Drafter alone; the engine stamps the rest into
	// the run's own copy of this file.
	Web Web `json:"web,omitzero"`
	// Review gates the review grant (review.go): ai_review, and read_input
	// answering only what AI Review passed. The compiler sets Enabled for a
	// built-in granted it; the engine stamps the ledger.
	Review Review `json:"review,omitzero"`
	// Calls is the calls ledger (calls.go): stamped by the engine into a
	// release's one-shot run alone, with end_blocked granted beside it.
	Calls Calls `json:"calls,omitzero"`
	// PDF is export_pdf's grant (pdf.go): Enabled by the compiler with the
	// scratch folder, the report design, the author line and the ledger
	// stamped by the engine.
	PDF PDF `json:"pdf,omitzero"`
	// Search is grep and glob's grant (search.go): Enabled by the compiler
	// with the scratch folder; the tools exist only while the run has an
	// area to search.
	Search Search `json:"search,omitzero"`
	// Calendar grants a persistent Assistant's calendar feeds and their
	// tools (calendar.go): each feed's address is a variable of this
	// server's environment, masked in every result, and the gateway lets
	// the container reach the feeds' hosts alone.
	Calendar Calendar `json:"calendar,omitzero"`
	// Deliverables is the ledger write_report and export_pdf record the files
	// the agent marked in (deliverables.go): stamped by the engine.
	Deliverables Deliverables `json:"deliverables,omitzero"`
	// Limits bounds tool I/O; zero values take the package defaults.
	Limits Limits `json:"limits"`
	// Owner, when set, is the host user who ran the command: every file
	// and directory write_report and fs_write create is chowned to it.
	// The tools container runs as root (see runnerimage/Dockerfile) and
	// writes into bind mounts the host user owns, so without this the
	// reports come out root-owned and the user cannot delete their own
	// output folder. The engine stamps it into the
	// per-run copy of this file, never into the compiled plan; absent on
	// hosts without POSIX ids.
	Owner *Owner `json:"owner,omitempty"`
}

Spec is the compiled configuration the runner's capability compiler hands to the tools server (written to plan/gateway/toolspec.json, bind-mounted read-only into the tools container). It is the only channel by which the manifest's capability contract reaches the server, so the compiler and this package must agree on it exactly — both sides import this type.

All filesystem grants are expressed as paths RELATIVE to WorkspaceDir; the server never receives, and never honors, absolute host paths.

func (*Spec) GrantedTools

func (s *Spec) GrantedTools() []string

GrantedTools returns the tool names this spec exposes, in the fixed registration order. Both the compiler (tools.yaml, plan tool grants) and the server (tools/list) derive from this one function so they cannot disagree.

type ThemeStamp

type ThemeStamp struct {
	// Name is the design's own label (a built-in's name, or the person's).
	Name string `json:"name"`
	// BasedOn is the built-in theme it started from.
	BasedOn string `json:"basedOn"`
	// Version is the design's revision, as text.
	Version string `json:"version"`
	// SHA256 is the hex SHA-256 of Document's bytes, which are the design's
	// canonical form, so it is pkg/reportdesign's SHA256 of the design.
	SHA256 string `json:"sha256"`
	// Document is the design's canonical JSON text, kept as a string so
	// that re-encoding the spec cannot change its bytes, and so its hash.
	Document string `json:"document"`
}

ThemeStamp is the run's report design as the engine stamps it into the tools spec: the canonical document verbatim, and what the receipt names it by.

func StampTheme

func StampTheme(doc []byte) (*ThemeStamp, error)

StampTheme reads a design document, held to every rule of pkg/reportdesign, into the stamp the engine writes into the run's tools spec. The stamp carries the canonical document, whatever spacing the source had, so its hash is the design's identity everywhere (the core answers the same bytes).

func (st *ThemeStamp) HasLogo() bool

HasLogo says the stamped design carries the person's logo.

type VoiceFile

type VoiceFile struct {
	File   string `json:"file"`
	Digest string `json:"digest"`
}

VoiceFile is an attached Writing Voice: the file voice_read returns, and the digest the receipt records for it.

type Web

type Web struct {
	Enabled bool `json:"enabled"`
	// RegistrySearch is compiled too: registry_search, the Drafter's alone,
	// granted only when Enabled and with a Registry to
	// read.
	RegistrySearch bool `json:"registrySearch,omitempty"`
	// SearchedOnly is compiled: web_read opens only an address a web_search
	// of this run returned and AI Review passed (the Knowledge Creator's).
	// Its model reads documents no one scanned, so an
	// instruction hidden in one must not be able to send another's text out
	// in an address of its choosing; a search result's address is the
	// search provider's, never the model's.
	SearchedOnly bool `json:"searchedOnly,omitempty"`
	// GivenOnly is compiled: web_read opens only an address the person gave
	// the run (Given), and one a page given redirects to on its own site
	// (the Voice Writer's). As with SearchedOnly, the address a read opens
	// is never the model's own choosing.
	GivenOnly bool `json:"givenOnly,omitempty"`
	// Given is the run's: the addresses a GivenOnly run may read, stamped
	// by the engine from the person's own command.
	Given []string `json:"given,omitempty"`
	// Render is compiled: the folder, in this container, through which
	// web_read asks the engine to render a page in a headless browser when
	// its text is thin or the model asks (the Knowledge Creator's). Empty,
	// no page is rendered.
	Render string `json:"render,omitempty"`
	// MaxPages, MaxSearches and MaxRegistryCalls bound one run's calls;
	// zero takes the defaults.
	MaxPages         int `json:"maxPages,omitempty"`
	MaxSearches      int `json:"maxSearches,omitempty"`
	MaxRegistryCalls int `json:"maxRegistryCalls,omitempty"`
	// Scan is where texts are scanned: WebScanRegistry (the registry's
	// route, with the job's credential in EnvWebJobToken) or WebScanJev
	// (the person's own key in EnvWebJevKey). Anything else scans nothing,
	// so every result is withheld.
	Scan string `json:"scan,omitempty"`
	// Search is where web_search goes: WebScanRegistry, a provider name
	// the person holds a key for (EnvWebSearchKey), or empty, when
	// web_search is not granted.
	Search string `json:"search,omitempty"`
	// Registry is the registry's root, for registry_search and, hosted,
	// the scan and search routes.
	Registry string `json:"registry,omitempty"`
	// Ledger is the container path the web ledger is appended to, one JSON
	// line a result.
	Ledger string `json:"ledger,omitempty"`
}

Web configures the web tools. Enabled is compiled (the Drafter's grant); everything below it is the run's, stamped by the engine into the run's own copy of this file, since one plan serves a local and a hosted draft alike.

Jump to

Keyboard shortcuts

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