drafter

package
v0.7.11-dev.2 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT, MIT Imports: 42 Imported by: 0

README

The Drafter

The Drafter is the QuickAgent behind Describe it in the Agentry Builder. You describe a task in plain words, and it drafts a QuickAgent for that task: a manifest (agent.yaml), an instruction file (AGENT.md) and short notes on what it chose and why. It publishes nothing. You read the draft and decide whether to submit it, and a submission is scanned like any other release.

This is the package that runs

The Drafter is built into the Agentry CLI and the desktop app, and it runs from there: on your computer when you run agentry draft, and on an Agentry sandbox host when you use Describe it on the site or in Agentry. This release has the same bytes. The registry built its archive from the package the CLI carries, and the archive's digest is the one the CLI reports. Run agentry builtins to print it and compare it with the digest on this page.

Installing this release does not give you the Drafter. The application runs the Drafter as a built-in, with the tools listed below. If you install this release, it runs as an ordinary QuickAgent with only what its manifest declares.

What it is given beyond its manifest

The manifest declares no network, no files and no commands. When Agentry runs the Drafter, it grants three tools that no other QuickAgent can have:

  • registry_search: searches Agentry's published QuickAgents, reads one QuickAgent's manifest, reads the registry's vulnerability check of an exact MCP server version, and looks an MCP server up in the registry's MCP server list (/build/mcp-servers/lookup on the registry's origin).
  • web_search: searches the web. A draft has this tool only when a search provider is configured.
  • web_read: reads one public web page as text.

AI Review reads every search result, page and registry answer before the Drafter's model does. Anything it flags, or could not scan, is withheld from the model, and the draft's notes list what was withheld. AI Review also reads the description before the run starts and checks the finished draft.

When you give a draft your knowledge packs, it also has the three knowledge tools every run with a pack has (knowledge_list, knowledge_search, knowledge_read). It reads the packs before the web. Nothing of a pack reaches its model unscanned: a pack Agentry scanned is read as that scan left it, and any other pack is scanned by AI Review before the draft starts. What a scan flagged is withheld, and the notes name it.

A draft ships only the packs you chose to ship (agentry draft --ship). The task names them, so the Drafter writes instructions that consult each at /knowledge/<name>, and the draft's manifest lists exactly those packs: any other knowledge.ships entry is removed and the notes say so, and a chosen pack the Drafter left out is added. The package carries each shipped pack whole, under knowledge/<name>/, whatever AI Review withheld from the Drafter's copy. A shipped pack is part of the release, readable by everyone who can download it, and agentry publish asks you to confirm each one.

Like every run, a draft also has a scratch folder for its working notes, private to the run and deleted with it, and grep and glob to search that folder and the attached packs.

Its drafting guide

The Drafter ships a knowledge pack of its own, drafting-guide, under knowledge/drafting-guide/ in this release, declared in knowledge.ships. It covers how a QuickAgent run works and what a declared MCP server meets in the runner: a musl Node runtime and a glibc Python one (which falls back to the previous Python line for a server whose requires_python excludes the default's), no install scripts, no launch arguments, stdio only, none of the run's files, and only port 443 to its declared hosts. It also has a checklist for a server before it is pinned, and two lists of servers: Runs here, the servers a survey saw install, start and list their tools in the runner, and Does not run here, the ones it saw fail, each with the reason, the runtime and the date. The lists are one thing for the Drafter to look at, not a judgement of any server's safety or quality (knowledge/drafting-guide/sources/servers.yaml; the survey is scripts/mcp-server-survey in the CLI's repository).

Since 1.8.2 the guide also holds the reference the Drafter's instruction used to carry on every turn: every field of the manifest and the rules' bounds, the commands every run provides, the network and the fetch tool, the intake and the guide, run modes, a person's knowledge at run time, how to write a QuickAgent's instructions, and three worked drafts. AGENT.md keeps the role, the rules for deciding, the steps, each naming the pages it needs, and the shape of the answer. The checks after a draft hold every rule they check, whatever the Drafter read.

Since 1.8.3 the checks after a draft hold each MCP server pin to the two lists. A pin on Does not run here, or a server whose own direct dependencies (from the package metadata the check of its version already reads) include a package the list names, gets the one repair turn, like any rule the draft breaks. An npm install script is noted for you to check before a run, not refused. The notes say what admitted each server the draft keeps: its Runs here entry, or the Drafter's judgement with the guide for a server on neither list. The lists stay soft: nothing outside the Drafter reads them, and a server on neither list may be pinned. The check sends nothing new off your computer.

Since 1.9.0 the guide teaches how a QuickAgent takes its files: every input is read in its text or as uploaded, the runner unpacks archives, and the manifest's inputs block says what kinds of file to bring and which view to read first. A draft that takes files declares the block, writes guide.files to match, and declares no command to read its inputs. The checks after a draft correct the block's slips (a kind in the singular, any beside named kinds, the block under capabilities) and send any archive reader to the repair turn. A release that declares the block needs CLI v0.6.73 or later to run; an older CLI refuses its manifest.

Since 1.10.0 the Drafter marks each key a draft declares: optional (capabilities.optionalSecrets) when the QuickAgent still does its job without it, required when it cannot. Its instructions say what to do when an optional key was not given, and a secret question's required matches its key. The Builders on the site and in the desktop show the marking, and the author can change it. A release that marks a key optional needs CLI v0.6.66 or later to run; an older CLI refuses its manifest.

Since 1.11.0 the Drafter may declare a vendor's own remote MCP server by its address, and prefers one to a package for the same service. A remote server signs in by OAuth, by one key sent as a bearer token, or not at all, and an OAuth one asks whoever runs the QuickAgent to sign in at the vendor at the first run of each version. The draft's notes say so, and say whose OAuth client the vendor needs. A package server signs in only with a sign-in its guide lists as seen working, copied exactly: the checks after a draft send any other oauth block to the repair turn. The guide's servers/sign-ins.md lists the vendors' servers and the sign-ins. A release with a remote server needs CLI v0.6.69 or later to run, one signed in to by OAuth CLI v0.6.70, and a package's sign-in CLI v0.6.71; an older CLI refuses its manifest.

Since 1.12.0 the Drafter knows the tools every run has beyond its manifest: the scratch folder, and export_pdf, the only way a run makes a PDF. A QuickAgent whose result is a PDF writes it in Markdown with write_report and turns it into the PDF with export_pdf, laid out in the report theme the person chose. The checks after a draft send instructions that have the run write a PDF with write_report, or leave the person to print a page to PDF, to the repair turn. A release whose instructions call export_pdf needs CLI v0.6.82 or later to run. 1.12.1 teaches the two paths: write_report's path is inside reports/ (resume.md), and export_pdf's source names it from the output folder (reports/resume.md), so a draft no longer writes into reports/reports/.

Since 1.13.0 the Drafter knows input sources. It asks for a codebase with a repository intake question and for a file at a web address with a url question, which the runner fetches before the run, and never advises a .zip for a repository or declares egress or a key to clone one. It knows that a tool result comes a page at a time, that a large fetch body is saved in the scratch folder or kept whole with saveTo, and that scratch_read and scratch_search read it. A release that asks a repository question needs CLI v0.6.97 or later, a url question v0.6.98 or later, and v0.6.104 or later to run either hosted.

Since 1.14.0 the Drafter knows target hosts. For a task on a machine the person names (a server to set up, manage or diagnose) it asks for the machine with an intake question of type host and lists its id in capabilities.targetHosts; it declares no SSH client, no egress and no key for the machine, writes the instructions for the host tools and the shell, and says in the notes that such a QuickAgent runs only on the person's computer. The checks after a draft send an exec that names ssh, scp, sftp or rsync to the repair turn with a line that points to a target host. A release that declares a target host needs CLI v0.6.105 or later to run, v0.6.106 for the shell and v0.6.109 for a host on port 22; it does not run In Agentry.

Since 1.15.0 the Drafter knows the browser. For a task that tests a website the person names as a person sees it (pages, forms, links, a phone's width) it asks for the site with an intake question of type url and lists its id in capabilities.browser.sites, adds hosts only for what the site's pages load, keeps the site scope, and declares a key the browser types into a sign-in form in capabilities.secrets and capabilities.browser.secrets, never with scope: public. It writes the instructions for the browser tools, with screenshots saved by bare file names into reports/browser/, and brings no browser of its own: the checks after a draft send an exec that names a browser or a driver (Chromium, Chrome, Firefox, Playwright, Puppeteer, Selenium, a WebDriver), or an MCP server that is one, to the repair turn with a line that points to the browser line. Since 1.15.2 that includes a hosted browser service (Browserless, Browserbase, browser-use, Hyperbrowser, Steel), by its package or by its remote address. A release that declares a browser needs CLI v0.6.117 or later, or Agentry Desktop 0.6.111; In Agentry it runs since CLI v0.6.118 and opens public sites only. Since 1.15.5 it teaches the run's budget: 100 tool calls and 900 seconds on the person's computer (the CLI's default policy, raised from 60 in the same release) and In Agentry on Pro and above, 20 and 300 seconds on Standard, which the run is not told. A browser draft does each page's checks in one browser_evaluate, bounds every fetch in a page script, never makes the same call five times running, writes its report early and rewrites it after each step, and opens only the site. The checks after a draft send instructions that fetch in a page script with no timeout, or press a key five or more times running, to the repair turn.

Since 1.15.2 the Drafter prefers what needs no key and no account: the run's own tools, the browser the runner gives, fetch to an API that answers without a key, a server that needs none. It declares a server or an API that needs a key, an account or a paid plan only when nothing key-free does the task, and the notes then say why.

Since 1.15.4 the Drafter knows deliverables. A QuickAgent whose result is a file tells its run to mark that file with deliverable: true and a one-line title on the write_report (or export_pdf) call that writes it, and to leave notes and drafts unmarked, so the person finds the result among a run's files.

Since 1.19.0 the Drafter drafts persistent agents. When a description asks for an agent that stays running, remembers what the person tells it or works on a schedule for them, the draft lists persistent in modes and declares in capabilities.persistent only the keys its instructions rely on (memory for recall, clock for the task tools, and so on). A person who names the agent gets a persona, whose text is written to PERSONA.md and listed in publish.include. For a part of the task that a published QuickAgent already does, the Drafter searches the registry, reads the candidate's manifest and proposes it in dependencies.agents with a version constraint and a reason; the notes list every subagent so the person can remove one, and the registry resolves each when the version is published. The checks after a draft send instructions that call a tool of an undeclared key, or a subagent tool with no subagent, to the repair turn.

The runner attaches the guide to every run of the Drafter, through the same knowledge tools, the repair turn included. It is part of this release, so the registry scans it with the published release. It is not one of your packs and does not count against a draft's limit of packs, but a pack of yours with the same name is refused. An install of this release from the registry is an ordinary QuickAgent and carries the pack like any release that ships one.

What it returns

AGENT.md and notes.md, written with write_report (and PERSONA.md for a persistent agent with a persona), and a final answer in the shape output.schema.json describes: the manifest's fields, the published QuickAgents that already do the job, and the questions the draft leaves open. The application turns them into the draft you review.

Documentation

Overview

Package drafter is the Drafter: the QuickAgent package that turns a person's description into a draft for the Builder, embedded in the CLI beside the Knowledge Creator and run by the runner as the second built-in package. Its manifest declares no egress, no filesystem, no exec and no secret; its reach is the three web tools the runner grants to it alone (runnerimage/toolsrv/web.go), every result of which AI Review reads before its model does.

Around the run this package holds the task the Drafter is given, the description's scan before the run starts (Prescan), the person's own keys for a draft on this computer (LocalWeb), the draft it returns (Draft, draft.json's shape) with AI Review's record (Finish), and the package a draft renders into, which the CLI's post-step validates. The CLI's `agentry draft` and the desktop's Describe it both drive it.

Index

Constants

View Source
const (
	CheckPass       = "pass"
	CheckFlagged    = "flagged"
	CheckNotScanned = "not_scanned"
)

The check's verdicts, as the registry's route answers them.

View Source
const (
	SeverityHigh   = "high"
	SeverityMedium = "medium"
	SeverityLow    = "low"
)

The severities a finding can carry.

View Source
const (
	Namespace = "agentry"
	Name      = "drafter"
	Version   = "1.19.0"
)

The package's identity, as its manifest declares it.

View Source
const (
	MaxIntake        = 3
	MaxPrepare       = 5
	MaxOpenQuestions = 2
	MaxNoteBullets   = 5
)

The Drafter's own caps: tighter than the manifest's bounds, which stay as they are for a QuickAgent written by hand. AGENT.md states each by value (TestTheInstructionStatesItsBoundsByValue) and the fixtures' shape check holds a draft to them (CheckShape).

View Source
const (
	// ScannedInAgentry: the pack's scan in Agentry stood in.
	ScannedInAgentry = "agentry"
	// ScannedForDraft: AI Review scanned it before this draft started.
	ScannedForDraft = "draft"
)

The two ways a pack a draft reads was scanned, as draft.json records it.

View Source
const (
	RepairTimeoutSeconds = 300
	RepairMaxTurns       = 8
)

The repair turn's caps: at most eight tool calls and, for a draft with a timeout, five minutes. A draft without a timeout gives the repair turn none either. It also gets no more than the draft's remaining budgets (repairBudgets).

View Source
const (
	RunsHere       = "runs-here"
	DoesNotRunHere = "does-not-run-here"
)

The two lists.

View Source
const (
	ClientAgentry = "agentry"
	ClientOwn     = "own"
)

How a vendor's OAuth sign-in gets its client: Agentry registers itself (a client metadata document or dynamic registration), or the person brings their own OAuth client, entered once per vendor.

View Source
const AllVersions = "all"

AllVersions is an entry's versions when it speaks for every version.

View Source
const CheckUnanswered = "unanswered"

CheckUnanswered is Word's for a check with no answer.

View Source
const GuideName = "drafting-guide"

GuideName is the knowledge pack the Drafter ships in its own release, its drafting guide: how a run works, what a declared MCP server meets in the runner, and the guide to the rest of a draft. The runner gives it to every run of the package, the repair turn included (localrun's withShippedPacks), apart from the person's packs, so it counts against none of a draft's caps; a person's pack of this name is refused (CheckKnowledgeSize). Its manifest.json, index and runtime facts are generated (TestTheDraftingGuideIsCurrent).

View Source
const LocalTimeoutFloorSeconds = 1800

LocalTimeoutFloorSeconds is the least a draft made on this computer is given: 30 minutes, where the runner policy's run timeout defaults to 15. A policy that allows more keeps its own, and a timeout the person names for the draft wins either way (localrun.Builtin.LocalBudgets). It is a timeout alone: a draft on this computer has no token limit, and its tool-call cap is the policy's. A draft made in Agentry runs under the caps its job carries.

View Source
const MaxInstructionBytes = 32 << 10

MaxInstructionBytes is the most the instruction file the Drafter writes may hold: most QuickAgents run with no network, so a drafted instruction carries the domain knowledge the run cannot look up, 20–30 KB for a big task. It is held equal to the core's draft-check bound (judge.DraftMaxInstruction), so no instruction it returns is past what the check reads. The check also holds the description, the manifest and the instruction to 48 KiB together (judge.DraftMaxState) and reads a draft past that as not scanned, which the post-step records and never counts as a pass. A longer instruction goes to the repair turn to be shortened.

View Source
const MaxKnowledgeBytes = knowledge.MaxBytes

MaxKnowledgeBytes is the most a draft's packs may hold in all, whatever a pack kept on this computer may hold: Agentry's own cap on one pack.

View Source
const MaxKnowledgePacks = 5

MaxKnowledgePacks is the most packs one draft takes: a hosted run's bound on attached packs.

View Source
const MaxRevisionTextBytes = 4000

MaxRevisionTextBytes bounds each of the person's two texts: the additional instructions and the problems with this draft.

View Source
const ReviseInput = "revise"

ReviseInput is the folder name the release is staged under, in the draft's output folder and under the run's /inputs.

RubricIDUndeclared is the release rubric's C3: a capability the instructions use that the manifest does not declare. Like every rubric finding on a draft it is recorded and never sent to the repair turn (Repairable); its note asks the person to check the manifest.

View Source
const ServerListFile = manifest.KnowledgeDir + "/" + GuideName + "/" + knowledge.SourcesDir + "/servers.yaml"

ServerListFile is the drafting guide's two soft lists of declared MCP servers, Runs here and Does not run here, as one file in the pack's sources. The two pages that show them are rendered from it (TestTheDraftingGuideIsCurrent). A list is one thing for the Drafter to look at, never a gate in the registry or the runner, and no entry says a server is safe or good: each says what was observed, on which runtime, on which date.

Variables

View Source
var (
	ErrCheckDescriptionTooLong = fmt.Errorf("the description is longer than the check reads (%d bytes)", corejudge.DraftMaxDescription)
	ErrCheckPackage            = errors.New("the package is not a draft the check reads")
	ErrCheckTooLarge           = fmt.Errorf("the package is past the check's bounds (%d files, %d bytes of text)", draftcheck.MaxFiles, draftcheck.MaxBytes)
)

The check's refusals of a draft it will not ask about, before anything is sent, in the CLI's own words: none quotes a path or the core's error.

View Source
var ErrKnowledgeNameTaken = errors.New("the Drafter ships a knowledge pack of that name")

ErrKnowledgeNameTaken is a person's pack named as the pack the Drafter ships (GuideName): both would be mounted at the same place.

View Source
var ErrKnowledgeTooLarge = errors.New("a draft reads at most " + knowledge.FormatCap(MaxKnowledgeBytes) + " of knowledge in all")

ErrKnowledgeTooLarge is a draft's packs past MaxKnowledgeBytes, or more than MaxKnowledgePacks of them.

View Source
var ErrKnowledgeUnscanned = errors.New("the pack is not scanned, and AI Review must scan it before the Drafter reads it")

ErrKnowledgeUnscanned is a pack that must be scanned first with no scanner to scan it.

View Source
var ErrNoJevKey = errors.New("no TypeSafe Jev key of your own was found")

ErrNoJevKey is LocalWeb's answer when the person has no Jev key of their own: a draft on this computer does not run without AI Review reading everything first, and there it takes the person's key.

Functions

func AgentryScanStandsIn

func AgentryScanStandsIn(p *knowledge.Pack, raw json.RawMessage) (bool, string)

AgentryScanStandsIn says whether raw, a pack's scan record in Agentry, stands in for scanning the pack for a draft, and why not: it must be the core's report, every stage must have finished, AI Review must have read every chunk, and it must account for every file of the pack's tree. A client says so before anything is scanned; ReadyKnowledge asks the same.

func CheckKnowledgeSize

func CheckKnowledgeSize(packs []*knowledge.Pack) error

CheckKnowledgeSize holds a draft's packs to MaxKnowledgePacks and MaxKnowledgeBytes, counted by each pack's files and its manifest, and refuses one named as the pack the Drafter ships (GuideName), which is not one of the person's and counts against neither cap: what a client checks before it scans anything. The runner refuses the same name again when it mounts the packs.

func CheckPackage

func CheckPackage(description, dir string) (draftcheck.Package, error)

CheckPackage is the rendered package as the check reads it: the person's description, and exactly the text files publish.include takes from dir, the licence among them, as stage S5 will read them at publish.

func CoreJev

func CoreJev(key string) (webscan.Scanner, error)

CoreJev scans with the person's own Jev key through the core's own pkg/judge, the registry's client and question set. It is the description's scanner for a local draft; the tools server in the run asks the same questions through the image's byte-for-byte copy.

func Correct

func Correct(raw json.RawMessage, ships ...string) (json.RawMessage, []string)

Correct is the post-step's first step: the Drafter's mechanical slips corrected without the model, before the draft is checked. Each correction is a data edit of the manifest the draft already holds, never a value invented for it:

  • a value named twice where the rules take it once (a mode, a tag, an intake question's choice): the second dropped;
  • an optional part left empty, or holding a placeholder such as "None" or "n/a": removed;
  • a list past its bound (the tags, the intake questions, the guide's prepare items): cut to the bound;
  • a text past its bound (the summary, a guide part, a key's help, the interactive opening, the knowledge prompt): shortened at a word, ending with "…";
  • a knowledge block under capabilities: moved to the top level, where the manifest takes it; knowledge.ships: held to the packs the person chose to ship (the ships argument, none when it is empty): any other entry removed, a chosen pack the draft left out added, and publish.include given the pattern that puts the packs in the archive;
  • a persona whose file publish.include does not match: the file added to publish.include, since the persona's text ships beside the instruction.

The bounds are pkg/manifest's own. It returns what it corrected, one plain sentence each, which Finish names in the draft's notes; the rules then check the corrected manifest as they would any other. A manifest that is not a JSON object is left as it came, for the rules to refuse.

func FS

func FS() fs.FS

FS is the package's tree: agent.yaml, AGENT.md, output.schema.json, README.md and LICENSE at its root (a public release carries the last two, V7), and under knowledge/ the pack it ships (GuideName).

func FromReports

func FromReports(d *Draft, reportsDir string) error

FromReports fills the instructions, the notes and the persona's text from the reports the Drafter wrote: its last message carries the manifest and the lists, and each long text comes as a report of its own, which a model writes more reliably than one large JSON answer. A field the message carried is kept. A report that is not a regular file, or is over its bound, is not read, and the error says so. The persona is written by a persistent agent's draft alone, so its report is optional.

func JevKey

func JevKey(pol *policy.Policy) (string, error)

JevKey is the person's own TypeSafe key as work on this computer reads it: the variable the policy's judge block names, else, for a keyring source, the keychain entry provider:typesafe. "" is no key. A draft scans with it (LocalWeb), and the Examiner reviews with it.

func NotRunReason

func NotRunReason(class string) (string, bool)

NotRunReason is the clause the pages give a reason class, and whether the class is one of the closed set.

func PackSource

func PackSource(name, file string) string

PackSource is how a draft names a file of a pack it read, in its sources and its notes: pack:<name>/<path>, the path relative to the pack's wiki for a page, else to the pack.

func Prescan

func Prescan(ctx context.Context, sc webscan.Scanner, task string) (webscan.Result, error)

Prescan is the step before the Drafter starts: AI Review reads the task as a description, and one that is flagged, or cannot be scanned, refuses the draft (exit 11) before anything else happens.

func PrescanRelease

func PrescanRelease(ctx context.Context, sc webscan.Scanner, r *Revision) (requests int, err error)

PrescanRelease has AI Review read the release's staged files before the Drafter starts, as model input in the pack scan's chunks (the Drafter's model reads nothing AI Review has not). A revision is of the whole release, so a file it does not pass, or could not scan, stops the draft at stage description rather than being withheld.

func Render

func Render(d *Draft, dir string) (*manifest.Manifest, error)

Render writes the draft as a package into dir, which must not exist yet: agent.yaml, rendered from the manifest in the Drafter's own key order; the instruction file the manifest names (AGENT.md when it names none); and, as `agentry init` does, a README.md from the manifest's own summary and overview and a LICENSE placeholder naming its SPDX id, since public publication needs both (V7) and the person writes the real ones.

A persistent agent's persona text is written to the file its manifest's persona names (PERSONA.md when it names none), beside the instruction.

A manifest pkg/manifest cannot parse is still rendered, so the person fixes it in the package, and the parse error is returned with it. An instruction or persona path that is not one Markdown file name at the root is refused, and nothing is written: a draft is agent-written, and its paths are data.

func RepairAnnouncement

func RepairAnnouncement(r RepairReport) string

RepairAnnouncement is the line a client prints as the repair turn starts.

func RepairTask

func RepairTask(d *Draft, r RepairReport) (string, error)

RepairTask is the repair turn's task: the constant framing, the rules' own report on the draft, and the draft's manifest, instructions and, for a persistent agent that has one, persona text as the Drafter wrote them (after the post-step's corrections), or, for an answer the output schema refused, its last message as it wrote it. Nothing else goes in: not the description, not the notes, the sources, the matches or AI Review's record, and no text the Drafter read. The turn runs without the web tools, so the report is the only thing in it the model did not write itself, beside the drafting guide the Drafter ships, which the framing points it to for the page a fix needs.

A repair with a flag of AI Review's check is also given r.Task, the task the Drafter's first turn was given, which AI Review passed before that turn started: a draft flagged as not doing the task cannot be fixed without it. It is the one text in the turn the Drafter was given before, and nothing it read. What the check flagged is the CLI's own words around the question's id and score and the package's own paths.

func RevisionDescription

func RevisionDescription(r *Revision) string

RevisionDescription is what AI Review's check of the finished draft reads as the person's description for a revision: the release it revises, what it does, and the person's two texts.

func RevisionTask

func RevisionTask(r *Revision) (string, error)

RevisionTask is the Drafter's task for a revision. It names the release's files under /inputs and then gives the person's two texts, fenced and labelled in the third person, as the site's Describe again does (an imperative framing of the person's words is flagged as an injection). AI Review reads the whole of it before the Drafter starts (Prescan); the release's own files are not in it.

func Task

func Task(description string, hints []string) (string, error)

Task is the Drafter's task message: the person's description and hints, framed. It is exactly what the description's scan reads (Prescan) and what the model is given.

func TaskWithKnowledge

func TaskWithKnowledge(description string, hints, packs []string) (string, error)

TaskWithKnowledge is Task for a draft given the person's knowledge packs: the message also names the packs, so the Drafter reads them first. The packs themselves reach it only through its knowledge tools, after their scan (ReadyKnowledge).

func TaskWithShips

func TaskWithShips(description string, hints, packs, shipped []string) (string, error)

TaskWithShips is TaskWithKnowledge for a draft whose person chose to ship some of the packs with the QuickAgent: shipped names the ones that ship, each of which is also in packs. The message tells the Drafter that every run of the QuickAgent reads those at /knowledge/<name>, so it writes the instructions to use them, and that the person chose them, so it declares them in knowledge.ships.

func VersionBoundReasons

func VersionBoundReasons() []string

VersionBoundReasons are versionBound's classes, sorted.

Types

type AIReview

type AIReview struct {
	// Description is the verdict on the description and hints, read
	// before the Drafter started: always pass in a draft that exists.
	Description webscan.Verdict `json:"description"`
	receipt.Web
	// WithheldSources is every text AI Review kept from the model, with why.
	WithheldSources []WithheldSource `json:"withheldSources"`
	// Check is AI Review's check of the finished draft (the post-step's):
	// absent for a draft that could not be rendered.
	Check *Check `json:"check,omitempty"`
}

AIReview is the draft's record of AI Review: the description's verdict, the run's receipt counts (what the web tools read, scanned and withheld, and where it was scanned), and each text the model was not given.

type Check

type Check struct {
	Rubric *CheckRubric `json:"rubric,omitempty"`
	Draft  *CheckDraft  `json:"draft,omitempty"`
	// Model is the judge's pinned model.
	Model string `json:"model,omitempty"`
	// Requests and InputTokens are the judge's, over every check asked.
	Requests    int `json:"requests"`
	InputTokens int `json:"inputTokens"`
	// Checks is how many checks the post-step asked: one, or two when a
	// flag sent the draft to its repair turn and the second answer was
	// checked again.
	Checks     int    `json:"checks"`
	Unanswered string `json:"unanswered,omitempty"`
}

Check is draft.json's record of the check, under aiReview.check: the verdicts of the last check the post-step asked, and how many it asked. A check with no answer (not asked, refused, or not answered) says why in Unanswered, in the CLI's own words, and has no verdicts.

func (*Check) Repairable

func (c *Check) Repairable() []string

Repairable is what of a check the repair turn acts on, in the CLI's own words: the draft question's flag (off_task), and nothing else. The release rubric's findings on a draft are advisory: they are recorded and named in the notes, and S5 reads the submitted version again. Sending them to the repair turn taught the model to clear a security QuickAgent's flags by deleting the servers, hosts and background its task needs. Empty when there is nothing to repair.

func (*Check) Verdict

func (c *Check) Verdict() string

Verdict is the check's as one word: flagged if either half flagged, else not scanned if either was, else pass; "" for a check with no verdicts.

func (*Check) Word

func (c *Check) Word() string

Word is the check as one word, for the envelope and the terminal: its Verdict, CheckUnanswered for a check with no answer, "" for none.

type CheckDraft

type CheckDraft struct {
	Verdict     string         `json:"verdict"`
	Score       int            `json:"score"`
	Scores      map[string]int `json:"scores,omitempty"`
	Flagged     []string       `json:"flagged"`
	QuestionSet string         `json:"questionSet"`
	Failure     string         `json:"failure,omitempty"`
}

CheckDraft is the draft question set's half.

type CheckFinding

type CheckFinding struct {
	ID       string `json:"id"`
	Score    int    `json:"score"`
	Path     string `json:"path"`
	Severity string `json:"severity"`
}

CheckFinding is one rubric question at 2 or more, with the severity S5 would record for it at publish, as the core serves it: high sends the version to a person, medium (and low) is shown on the report of a version that publishes.

type CheckRubric

type CheckRubric struct {
	Verdict    string         `json:"verdict"`
	Scores     map[string]int `json:"scores,omitempty"`
	Findings   []CheckFinding `json:"findings"`
	RubricHash string         `json:"rubricHash"`
	Failure    string         `json:"failure,omitempty"`
}

CheckRubric is the release rubric's half: pass, flagged or not scanned, the six scores, and each question that scored 2 or more with the file whose chunk scored highest.

type Checker

type Checker interface {
	Check(ctx context.Context, p draftcheck.Package) (*Check, error)
}

A Checker asks the check of a finished draft. Its error means the check was not asked, and says why in the CLI's own words; a judge that could not answer a half is a verdict of not scanned on that half.

func CheckerFor

func CheckerFor(w *engine.WebRun) (Checker, error)

CheckerFor is the check of the finished draft for a run's web configuration: the registry's route with the job's credential for a hosted draft, the core's pkg/draftcheck with the person's own Jev key on this computer (inside the draft's one AI Review use).

func CoreCheck

func CoreCheck(key string) (Checker, error)

CoreCheck asks the check with the person's own Jev key through the core's own pkg/draftcheck, exactly as the registry asks it.

func LocalChecker

func LocalChecker(a corejudge.Asker) Checker

LocalChecker asks the check through a judge client of the caller's.

type DependencyEntry

type DependencyEntry struct {
	Ecosystem string    `yaml:"ecosystem"`
	Package   string    `yaml:"package"`
	Reason    string    `yaml:"reason"`
	Observed  string    `yaml:"observed"`
	Evidence  string    `yaml:"evidence"`
	Date      time.Time `yaml:"date"`
}

DependencyEntry is a package whose presence as a server's direct dependency means the server does not run here.

type Draft

type Draft struct {
	// Manifest is the v2 manifest as JSON, as the Drafter wrote it.
	Manifest json.RawMessage `json:"manifest"`
	// Instructions is the instruction file (AGENT.md).
	Instructions string `json:"instructions"`
	// Notes is Markdown for the person.
	Notes string `json:"notes"`
	// PersonaText is the persona's text (PERSONA.md) of a persistent agent
	// that has one: the file the manifest's persona names, which the package
	// carries beside the instruction. Empty for a draft with no persona.
	PersonaText   string   `json:"personaText,omitempty"`
	Matches       []Match  `json:"matches"`
	Sources       []Source `json:"sources"`
	OpenQuestions []string `json:"openQuestions"`

	// Drafter names what made the draft (the post-step's).
	Drafter *Made `json:"drafter,omitempty"`
	// AIReview is what AI Review read and withheld (the post-step's).
	AIReview *AIReview `json:"aiReview,omitempty"`
	// Knowledge is each of the person's knowledge packs the Drafter was
	// given, how it was scanned and what of it was withheld (the
	// post-step's).
	Knowledge []PackRead `json:"knowledge,omitempty"`
	// Ships is each pack the person chose to ship with the QuickAgent: the
	// draft's package carries it under knowledge/<name>/, and the
	// manifest ships exactly these (the post-step's). A client that
	// builds the package itself lays these packs from their stores.
	Ships []ShippedPack `json:"ships,omitempty"`
	// Revises is the release a revision was drafted from (the post-step's):
	// its ref and its archive's digest. Absent for a new
	// QuickAgent.
	Revises *Revises `json:"revises,omitempty"`
	// Validation is `agentry validate --json`'s report over the rendered
	// package (the post-step's): the manifest rules and the S1, S3 and S4
	// scanners. A draft that fails them is kept, with its problems, for the
	// person to fix.
	Validation json.RawMessage `json:"validation,omitempty"`
	// ManifestError says why the draft could not be checked: its manifest
	// does not parse (the package is rendered all the same, for the person
	// to fix), its instruction path or its reports were refused (nothing is
	// rendered), or validation could not run. Validation is then absent.
	ManifestError string `json:"manifestError,omitempty"`
	// Recovered says the post-step took a schema-valid terminal object
	// from a last message the runner refused for text before it.
	Recovered bool `json:"recovered,omitempty"`
	// contains filtered or unexported fields
}

Draft is draft.json: what the Drafter returned, known fields only, and what the post-step adds (Finish, and the CLI's validation of the rendered package). A client reads it as data: its values reach the Builder only as text in the fields the Builder already has.

func Finish

func Finish(env *receipt.Envelope, outDir string, desc webscan.Result, ref, build string) (*Draft, error)

Finish is the post-step's first half: the Drafter's answer in env as a draft, named by the Drafter's ref and the build that ran it (the model and the run id are the envelope's), its long texts from the reports under outDir, AI Review's record from the receipt and the run's ledger, its manifest's mechanical slips corrected (Correct), and the notes followed by what was corrected and a list of every text AI Review withheld (its address, tool and reason, never the text). A draft whose reports were refused, or that has no instructions, carries why in ManifestError; a caller renders and checks only a draft whose ManifestError is empty. An answer that is not a draft is exit 17.

func FinishShipping

func FinishShipping(env *receipt.Envelope, outDir string, desc webscan.Result, ref, build string, ships []string) (*Draft, error)

FinishShipping is Finish for a draft whose person chose to ship the packs named in ships: its manifest ships exactly those (Correct), and every repair of it does too.

func Parse

func Parse(result json.RawMessage) (*Draft, error)

Parse reads the Drafter's result, known fields only. The runner has held it to output.schema.json; this is the decode.

func Repaired

func Repaired(first *Draft, env *receipt.Envelope, outDir string, r RepairReport) (*Draft, error)

Repaired is the post-step over the repair turn's answer: the first draft with the manifest the second answer returned and, when the turn wrote one, its instruction file. Everything else is the first answer's (the matches, the sources, the open questions, the notes, AI Review's record and what made it), since the repair turn read nothing. Its manifest is corrected as the first's was, and its notes say it was repaired and what the rules said of the first answer. outDir is the repair run's own output folder. The caller checks the result as it checked the first, and keeps it whether or not it passes; an answer that is not a draft is exit 17, and the caller keeps the first draft.

func Unparsed

func Unparsed(env *receipt.Envelope, outDir string, desc webscan.Result, ref, build string, why error) *Draft

Unparsed is the draft of an answer the output schema refused (exit 17, why): the Drafter's last message was not one JSON object with a manifest. It has no manifest and says why in ManifestError, and it keeps what Finish would (its reports, AI Review's record, what made it) and the last message, bounded, for its repair turn (RepairTask), the one thing the turn is given back besides the error. It is never rendered or written as a draft unless that turn returns one.

func (*Draft) Corrections

func (d *Draft) Corrections() []string

Corrections is what the post-step corrected in the draft's manifest without the model (Correct), in the order it was done.

func (*Draft) IsRepaired

func (d *Draft) IsRepaired() bool

IsRepaired says the draft is the Drafter's second answer, after its repair turn (Repaired).

func (*Draft) NoteNotRepaired

func (d *Draft) NoteNotRepaired(r RepairReport, why string)

NoteNotRepaired says in the notes that the rules refused this draft and its repair turn returned no draft, with why in the CLI's own words.

func (*Draft) NoteSecondAnswerDropped

func (d *Draft) NoteSecondAnswerDropped(r RepairReport, dropped []string)

NoteSecondAnswerDropped says in the notes that the first answer is kept, because the second left out declared capabilities the report did not name (keepFirst), r being what sent the first to its repair turn. A repair does not clear a report by stripping what the task needs.

func (*Draft) NoteSecondAnswerRefused

func (d *Draft) NoteSecondAnswerRefused(r RepairReport)

NoteSecondAnswerRefused says in the notes that the first answer is kept, because the second broke a rule the first passed (keepFirst), r being what sent the first to its repair turn. A repair does not trade a draft the rules pass for one they refuse, nor one within the instruction cap for one past it.

func (*Draft) NoteWithheld

func (d *Draft) NoteWithheld()

NoteWithheld adds to the notes the texts AI Review kept from the model, with why (the notes list every withheld source), from the draft's AI Review record rather than from what the model chose to say.

func (*Draft) Passed

func (d *Draft) Passed() bool

Passed says the rules pass the draft's rendered package.

func (*Draft) RecordCheck

func (d *Draft) RecordCheck(c *Check, checks int, unanswered error)

RecordCheck writes the check into the draft's AI Review record, with how many checks were asked (c becomes the record's), and says in the notes what a person should know of it: nothing for a pass; for a flag, what it flagged and what it means at publish; for a half not scanned or a check not asked, that. The notes' words are the CLI's own.

type GuideRead

type GuideRead struct {
	Name   string `json:"name"`
	Digest string `json:"digest"`
	Pages  int    `json:"pages"`
	Bytes  int64  `json:"bytes"`
}

GuideRead is the record of the drafting guide a draft had: its name and the digest, pages and bytes its manifest.json gives.

type KnowledgeIn

type KnowledgeIn struct {
	Pack *knowledge.Pack
	// Agentry is the scan record of Agentry's copy of this pack's tree,
	// confirmed with the registry or laid down by a sandbox host from
	// Agentry's store; nil when there is none, and the pack is scanned
	// first.
	Agentry json.RawMessage
	// Unconfirmed is why a kept pack's record could not be confirmed, for
	// what the person is told; "" when there was nothing to confirm.
	Unconfirmed string
}

KnowledgeIn is one pack a draft is given.

type KnowledgeRead

type KnowledgeRead struct {
	Packs []engine.AttachedPack
	Read  []PackRead
}

KnowledgeRead is what a draft reads of the person's knowledge: the packs to attach to its run, cut of what was withheld, and the record of each.

func ReadyKnowledge

func ReadyKnowledge(ctx context.Context, in []KnowledgeIn, sc webscan.Scanner, scratch string, log io.Writer) (*KnowledgeRead, error)

ReadyKnowledge makes the packs a draft reads (see the top of this file): held to the size bounds, each one's withheld files decided by its scan in Agentry or by sc, and those files cut from a private copy under scratch, which the caller removes after the run. sc may be nil when every pack carries a record that stands in; a pack that needs scanning is then refused (ErrKnowledgeUnscanned, exit 11). log takes a line a person reads as each pack is scanned; nil discards them.

func (*KnowledgeRead) Names

func (k *KnowledgeRead) Names() []string

Names are the packs' names, in the order given.

type Made

type Made struct {
	Ref   string `json:"ref"`
	Build string `json:"build,omitempty"`
	Model string `json:"model,omitempty"`
	RunID string `json:"runId,omitempty"`
	// Guide is the pack the Drafter ships and every run of it read
	// (GuideName), recorded apart from the person's packs in Knowledge.
	// It is part of the Drafter's release, so it has no scan record of
	// its own.
	Guide *GuideRead `json:"guide,omitempty"`
}

Made names the Drafter run behind a draft.

type Match

type Match struct {
	Ref string `json:"ref"`
	Why string `json:"why"`
}

Match is a published QuickAgent that does the task, or most of it.

type PackRead

type PackRead struct {
	Name   string `json:"name"`
	Digest string `json:"digest"`
	Pages  int    `json:"pages"`
	Bytes  int64  `json:"bytes"`
	// Scan is how the pack was scanned: ScannedInAgentry or
	// ScannedForDraft.
	Scan string `json:"scan"`
	// Withheld is every file of the pack the Drafter was not given.
	Withheld []WithheldFile `json:"withheld"`
	// Requests counts AI Review's requests for a pack scanned for the
	// draft, for the record (never a price: one credit an operation).
	Requests int `json:"requests,omitempty"`
}

PackRead is draft.json's record of one pack the Drafter was given.

type PostStep

type PostStep struct {
	// OutDir is the first turn's output folder: the package is rendered in
	// OutDir/package and the repair turn writes OutDir/repair.
	OutDir string
	// Description is the person's description, which the check reads; Task
	// is the first turn's task, which a repair turn a check flag sent is
	// also given (AI Review passed it before that turn started).
	Description, Task string
	// Scan is AI Review's verdict on the description (Prescan).
	Scan webscan.Result
	// Ref and Build name the Drafter and the client that ran it.
	Ref, Build string
	// Budgets are the first turn's; the repair turn gets what it left.
	Budgets spec.Budgets
	// Checker asks AI Review's check of the finished draft (CheckerFor).
	// CheckerErr is why CheckerFor could make none; a nil Checker (an
	// untyped nil) is recorded as unanswered, never as a pass.
	Checker    Checker
	CheckerErr error
	// Repair runs the Drafter's one repair turn. It must run the Drafter
	// without its web tools and with no web configuration, so no key and
	// nothing to read: localrun.RepairRun builds that run.
	Repair func(context.Context, RepairTurn) (*receipt.Envelope, error)
	// Rules loads the S4 bundle the package is validated under; nil is the
	// bundle embedded in this binary (validate.Embedded).
	Rules validate.RulesLoader
	// Log takes the line announcing the repair turn; nil discards it.
	Log io.Writer
	// Knowledge is what the first turn was given of the person's
	// knowledge (ReadyKnowledge): recorded in the draft, each withheld
	// file named in its notes. Nil for a draft given none. The repair
	// turn is given none.
	Knowledge *KnowledgeRead
	// Ships are the packs the person chose to ship with the QuickAgent,
	// as the person's own, whole, unscanned for the draft: the draft's
	// manifest ships exactly these, the rendered package carries each
	// under knowledge/<name>/ (and so validate holds it to the rules a
	// registry applies), and the draft records them in Ships. They are
	// also among the packs the first turn reads (Knowledge). Nil for a
	// draft that ships none.
	Ships []ShipIn
	// Revision is the release a revision was drafted from and the person's
	// two texts: the draft records it in Revises and keeps its name, the
	// first answer and the repair turn's alike. Nil for a new QuickAgent.
	Revision *Revision
	// OnUsage is the live usage reporter the first turn had; the repair
	// turn's lines count on from the first turn's total, so a host's caps
	// see the draft whole. Nil reports none.
	OnUsage func(receipt.Usage)
	// Servers resolves a declared MCP server's pin for the rule on its
	// runtime (checkServers); nil resolves against Registries, the
	// registries the person's runs install from (the runner policy's
	// mcpRegistries), or the default npm and PyPI registries when none are
	// given.
	Servers    ServerResolver
	Registries policy.MCPRegistries
	// contains filtered or unexported fields
}

PostStep is the post-step over the Drafter's first answer, after Prescan and the first turn: the answer finished with AI Review's record and its mechanical slips corrected (Finish), rendered into OutDir/package and checked by `agentry validate`'s own code (pkg/validate), AI Review's check of the finished package, one repair turn for a draft the rules refuse or the check flagged as not doing the task, and the second answer checked again. `agentry draft` and the desktop's draft on this computer run it alike, so a draft's validation, its repair turn's input and its check are one implementation.

func (PostStep) Run

func (p PostStep) Run(ctx context.Context, env *receipt.Envelope, runErr error) (*Draft, *receipt.Envelope, error)

Run is the post-step over the first turn's envelope and error. An answer the output schema refused (exit 17) is first recovered when it ends in a schema-valid object; otherwise it is given the one repair turn with that error and its own last message; a draft it returns stands as the run's answer, and the envelope is made ok (its usage stays both turns'). Any other failed run, or a second answer that is still not a draft, comes back as runErr with its envelope and no draft. Otherwise the draft comes back finished, validated and checked, with the envelope of both turns; an error is an answer that was not a draft (Finish).

type RegistryChecker

type RegistryChecker struct {
	// Base is the registry's root URL; JobToken the job's credential.
	Base     string
	JobToken string
	// HTTP is the client; nil is one that never follows a redirect.
	HTTP *http.Client
}

RegistryChecker asks the registry's check with a hosted draft's job credential. It asks once and never again on a failure: the registry counts a check against the draft's cap of two as it admits it, before its checker answers, so a retry after a 503 would spend the check kept for after the repair turn.

func (*RegistryChecker) Check

type RemoteEntry

type RemoteEntry struct {
	Vendor string `yaml:"vendor"`
	URL    string `yaml:"url"`
	// Auth is the manifest's: oauth, secret or none.
	Auth manifest.MCPAuth `yaml:"auth"`
	// Scopes are what the vendor's metadata offers, for auth oauth.
	Scopes []string `yaml:"scopes,omitempty"`
	// Client is, for auth oauth, ClientAgentry (the vendor lets Agentry
	// register itself) or ClientOwn (the person brings their own client).
	Client     string    `yaml:"client,omitempty"`
	Seen       bool      `yaml:"seen"`
	Observed   string    `yaml:"observed"`
	Conditions []string  `yaml:"conditions,omitempty"`
	Evidence   string    `yaml:"evidence"`
	Date       time.Time `yaml:"date"`
}

RemoteEntry is one vendor's remote MCP server, as an address and a way of signing in. Seen says it answered a tool call through Agentry; otherwise the entry is what the vendor's own metadata said on its date, read anonymously.

type RepairReport

type RepairReport struct {
	Rules   []string
	Flagged []string
	Task    string
}

RepairReport is what sends a draft to its one repair turn: the rules' report on it, AI Review's check flagging it as not doing the task (Check.Repairable, off_task alone), or both. A draft has one repair turn whatever sent it. Task is the task the Drafter's first turn was given, which a turn with a flag is also given.

func (RepairReport) Empty

func (r RepairReport) Empty() bool

Empty says there is nothing to repair.

type RepairTurn

type RepairTurn struct {
	Task    string
	OutDir  string
	Budgets spec.Budgets
	RunID   string
	OnUsage func(receipt.Usage)
}

RepairTurn is what the post-step gives the repair turn's run: the task (RepairTask), the folder, the budgets the first turn left, a run id of its own, and its usage reporter.

type Revises

type Revises struct {
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
}

Revises is draft.json's record of the release a draft revises.

type Revision

type Revision struct {
	// Revises is the release's ns/name@version and the digest of its
	// archive, as the registry holds it (the archive read for a fetched
	// release, the same packing of a folder on this computer).
	Revises
	// Name is the manifest's name, which the revision keeps.
	Name string
	// Summary is the release's own one-line summary.
	Summary string
	// InstructionFile is the release's instruction file, by its path in
	// the package.
	InstructionFile string
	// PersonaFile is the release's persona file, by its path in the
	// package; empty for a release with no persona.
	PersonaFile string
	// Dir holds the release's agent.yaml, its instruction file and its
	// persona file, and nothing else: the folder staged under
	// /inputs/revise.
	Dir string
	// Additional and Problems are the person's two texts, the additional
	// instructions and the problems with this draft; at least one is
	// given.
	Additional, Problems string
}

Revision is a release given to the Drafter to revise, and the person's two texts.

func ReadRelease

func ReadRelease(src, dest, ref, digest string) (*Revision, error)

ReadRelease reads a release's package folder for a revision: its agent.yaml, which must parse and name the QuickAgent, the instruction file it names and, for a persistent agent, its persona's file. It copies them into dest (OutDir/revise), the only files the Drafter is given of the release. digest is the release's archive digest, which the caller computes; ref is checked against the manifest when given, and made from it when not.

func (*Revision) WithTexts

func (r *Revision) WithTexts(additional, problems string) error

WithTexts sets the person's two texts, holding each to its bound and requiring at least one.

type RuntimeEntry

type RuntimeEntry struct {
	Image    string    `yaml:"image"`
	User     string    `yaml:"user"`
	Home     string    `yaml:"home"`
	Observed string    `yaml:"observed"`
	Programs []string  `yaml:"programs"`
	Evidence string    `yaml:"evidence"`
	Date     time.Time `yaml:"date"`
}

RuntimeEntry is what a server meets inside one default runtime image: the user and HOME it starts as, and the programs the image has.

type SearchState

type SearchState string

SearchState says whether a local draft has web search, and why not.

const (
	// SearchOn: the policy names a provider and its key was found.
	SearchOn SearchState = "on"
	// SearchNoProvider: the policy's webSearch block names no provider.
	SearchNoProvider SearchState = "no-provider"
	// SearchNoKey: a provider is named, and no key for it was found.
	SearchNoKey SearchState = "no-key"
)

func LocalWeb

func LocalWeb(pol *policy.Policy, registry string) (*engine.WebRun, SearchState, error)

LocalWeb is a local draft's web configuration from the person's own keys: their Jev key, which every result is scanned with, and their search key when the policy names a provider and the key is found, with which of those it is. Without a Jev key it is ErrNoJevKey and nothing runs. The registry is the one registry_search reads. The Jev key in the answer is exactly the one the draft scans with, so a client that tests a key tests that one.

func SearchKey

func SearchKey(pol *policy.Policy) (string, SearchState, error)

SearchKey is the person's own search key as a local draft reads it, and whether search is on: the policy's provider, its key from the variable the policy names or the provider's own, else, for a keyring source, the keychain entry provider:<provider>. It needs no Jev key, so a client can test the search key alone, and it is the one LocalWeb searches with.

type ServerEntry

type ServerEntry struct {
	Ecosystem string `yaml:"ecosystem"`
	Package   string `yaml:"package"`
	// Versions is the versions the entry is about: the exact version that
	// was seen, or "all". It is never a range (LoadServerList). Which other
	// versions an exact entry speaks for is versionBound's rule.
	Versions string `yaml:"versions"`
	List     string `yaml:"list"`
	// Reason is a class of the closed set (NotRunReason), on Does not run here only.
	Reason string `yaml:"reason,omitempty"`
	// Runtime is the runtime it was seen on ("Node 24.21.0").
	Runtime string `yaml:"runtime"`
	// Observed is what was seen, in one or two plain sentences.
	Observed string `yaml:"observed"`
	// Tools are the tools it listed, on Runs here.
	Tools []string `yaml:"tools,omitempty"`
	// Conditions are what a QuickAgent must declare or know for it to
	// run: its keys, its egress hosts, an env switch.
	Conditions []string `yaml:"conditions,omitempty"`
	// Evidence is where it was seen.
	Evidence string    `yaml:"evidence"`
	Date     time.Time `yaml:"date"`
}

ServerEntry is one server on one list.

type ServerList

type ServerList struct {
	Servers      []ServerEntry     `yaml:"servers"`
	Dependencies []DependencyEntry `yaml:"dependencies"`
	Runtimes     []RuntimeEntry    `yaml:"runtimes"`
	// Remote are vendors' own remote MCP servers, by address and sign-in,
	// and SignIns the package servers' OAuth sign-ins seen working.
	// A draft may give a package an oauth block only by copying one listed
	// here.
	Remote  []RemoteEntry `yaml:"remote"`
	SignIns []SignInEntry `yaml:"signins"`
}

ServerList is ServerListFile decoded: the servers on the two lists, the dependencies that mean a server does not run here, and what was seen of the runtime images a server runs in.

func LoadServerList

func LoadServerList(fsys fs.FS) (*ServerList, error)

LoadServerList reads ServerListFile from fsys (FS(), or a laid-down tree) and holds every entry to the file's rules: a known ecosystem and list, a reason from the closed set exactly where one belongs, the observation, evidence and date every entry carries, and one entry per package and list.

func (*ServerList) ListedDependency

func (l *ServerList) ListedDependency(ecosystem string, deps []string) (DependencyEntry, bool)

ListedDependency is the first of deps, a server's direct dependencies in one ecosystem, that the dependencies section lists.

func (*ServerList) NotRunHere

func (l *ServerList) NotRunHere(ecosystem, pkg, version string) (ServerEntry, bool)

NotRunHere is the Does not run here entry that covers a pin: its package, in the ecosystem's own name rule, and a version the entry speaks for.

func (*ServerList) RemoteServer

func (l *ServerList) RemoteServer(address string, auth manifest.MCPAuth) (RemoteEntry, bool)

RemoteServer is the Remote entry for a remote server's address and auth, compared as written, with a trailing slash ignored.

func (*ServerList) RunsHereEntry

func (l *ServerList) RunsHereEntry(ecosystem, pkg, version string) (e ServerEntry, listed, seen bool)

RunsHereEntry is the Runs here entry of a package, if it is listed; seen says the entry speaks for this version (its own, or all).

func (*ServerList) SignIn

func (l *ServerList) SignIn(ecosystem, pkg, version string) (SignInEntry, bool)

SignIn is the listed sign-in for a package's version, if one is listed.

type ServerResolver

type ServerResolver func(context.Context, manifest.MCPServer) (mcpinstall.Resolved, error)

ServerResolver resolves one declared MCP server's pin to its registry metadata (mcpinstall.Resolved, whose DeclaredRuntime is the release's own engines.node or requires_python).

type ShipIn

type ShipIn struct {
	Pack   *knowledge.Pack
	Origin *ship.Origin
}

ShipIn is one pack the person chose to ship, and where it was laid down from, when it was laid down from a stored pack.

type ShippedPack

type ShippedPack struct {
	Name   string `json:"name"`
	Digest string `json:"digest"`
	Pages  int    `json:"pages"`
	// Bytes is the pack's tree, as a pack counts its size.
	Bytes  int64        `json:"bytes"`
	Origin *ship.Origin `json:"origin,omitempty"`
}

ShippedPack is draft.json's record of a pack the draft ships: the pack as the person chose it, and, when it was laid down from a stored pack, the origin the publish confirmation claims.

type SignInEntry

type SignInEntry struct {
	Ecosystem string `yaml:"ecosystem"`
	Package   string `yaml:"package"`
	// Versions is the exact version seen, or "all".
	Versions string `yaml:"versions"`
	// Egress are hosts the server's egress must name.
	Egress []string `yaml:"egress"`
	// Env are plain settings the server's env must carry, as given.
	Env   map[string]string `yaml:"env,omitempty"`
	OAuth manifest.MCPOAuth `yaml:"oauth"`
	// Client is ClientAgentry or ClientOwn, as on a RemoteEntry.
	Client   string    `yaml:"client"`
	Observed string    `yaml:"observed"`
	Evidence string    `yaml:"evidence"`
	Date     time.Time `yaml:"date"`
}

SignInEntry is a package server's OAuth sign-in seen working: the package and version, the hosts and plain settings the block needs beside it, and the block itself, which a draft copies exactly.

func (SignInEntry) Differs

func (si SignInEntry) Differs(srv manifest.MCPServer) string

Differs names, by field, how a declared server's sign-in departs from the listed one: its oauth block not copied exactly, a host the listed egress names and the server's lacks, a listed setting missing or changed. "" when it is the listed sign-in. Every word is the entry's or a field's name, never the draft's, so nothing the model wrote reaches the repair turn through it.

type Source

type Source struct {
	URL      string `json:"url"`
	Used     string `json:"used"`
	Withheld bool   `json:"withheld,omitempty"`
}

Source is one page or registry answer the Drafter used, or one AI Review withheld.

type WithheldFile

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

WithheldFile is one file of a pack the Drafter was not given.

type WithheldSource

type WithheldSource struct {
	Tool   string `json:"tool"`
	URL    string `json:"url"`
	Reason string `json:"reason"`
}

WithheldSource is one text the model was not given.

Jump to

Keyboard shortcuts

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