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
- Variables
- func AgentryScanStandsIn(p *knowledge.Pack, raw json.RawMessage) (bool, string)
- func CheckKnowledgeSize(packs []*knowledge.Pack) error
- func CheckPackage(description, dir string) (draftcheck.Package, error)
- func CoreJev(key string) (webscan.Scanner, error)
- func Correct(raw json.RawMessage, ships ...string) (json.RawMessage, []string)
- func FS() fs.FS
- func FromReports(d *Draft, reportsDir string) error
- func JevKey(pol *policy.Policy) (string, error)
- func NotRunReason(class string) (string, bool)
- func PackSource(name, file string) string
- func Prescan(ctx context.Context, sc webscan.Scanner, task string) (webscan.Result, error)
- func PrescanRelease(ctx context.Context, sc webscan.Scanner, r *Revision) (requests int, err error)
- func Render(d *Draft, dir string) (*manifest.Manifest, error)
- func RepairAnnouncement(r RepairReport) string
- func RepairTask(d *Draft, r RepairReport) (string, error)
- func RevisionDescription(r *Revision) string
- func RevisionTask(r *Revision) (string, error)
- func Task(description string, hints []string) (string, error)
- func TaskWithKnowledge(description string, hints, packs []string) (string, error)
- func TaskWithShips(description string, hints, packs, shipped []string) (string, error)
- func VersionBoundReasons() []string
- type AIReview
- type Check
- type CheckDraft
- type CheckFinding
- type CheckRubric
- type Checker
- type DependencyEntry
- type Draft
- func Finish(env *receipt.Envelope, outDir string, desc webscan.Result, ref, build string) (*Draft, error)
- func FinishShipping(env *receipt.Envelope, outDir string, desc webscan.Result, ref, build string, ...) (*Draft, error)
- func Parse(result json.RawMessage) (*Draft, error)
- func Repaired(first *Draft, env *receipt.Envelope, outDir string, r RepairReport) (*Draft, error)
- func Unparsed(env *receipt.Envelope, outDir string, desc webscan.Result, ref, build string, ...) *Draft
- func (d *Draft) Corrections() []string
- func (d *Draft) IsRepaired() bool
- func (d *Draft) NoteNotRepaired(r RepairReport, why string)
- func (d *Draft) NoteSecondAnswerDropped(r RepairReport, dropped []string)
- func (d *Draft) NoteSecondAnswerRefused(r RepairReport)
- func (d *Draft) NoteWithheld()
- func (d *Draft) Passed() bool
- func (d *Draft) RecordCheck(c *Check, checks int, unanswered error)
- type GuideRead
- type KnowledgeIn
- type KnowledgeRead
- type Made
- type Match
- type PackRead
- type Pay
- type PostStep
- type RegistryChecker
- type RemoteEntry
- type RepairReport
- type RepairTurn
- type Revises
- type Revision
- type RuntimeEntry
- type SearchState
- func LocalWeb(pol *policy.Policy, registry string) (*engine.WebRun, SearchState, error)
- func LocalWebPaid(ctx context.Context, pol *policy.Policy, registry, purpose string, pay Pay) (*engine.WebRun, SearchState, error)
- func SearchAccess(pol *policy.Policy) (provider, key string, state SearchState, err error)
- func SearchKey(pol *policy.Policy) (string, SearchState, error)
- type ServerEntry
- type ServerList
- func (l *ServerList) ListedDependency(ecosystem string, deps []string) (DependencyEntry, bool)
- func (l *ServerList) NotRunHere(ecosystem, pkg, version string) (ServerEntry, bool)
- func (l *ServerList) RemoteServer(address string, auth manifest.MCPAuth) (RemoteEntry, bool)
- func (l *ServerList) RunsHereEntry(ecosystem, pkg, version string) (e ServerEntry, listed, seen bool)
- func (l *ServerList) SignIn(ecosystem, pkg, version string) (SignInEntry, bool)
- type ServerResolver
- type ShipIn
- type ShippedPack
- type SignInEntry
- type Source
- type WithheldFile
- type WithheldSource
Constants ¶
const ( CheckPass = "pass" CheckFlagged = "flagged" CheckNotScanned = "not_scanned" )
The check's verdicts, as the registry's route answers them.
const ( SeverityHigh = "high" SeverityMedium = "medium" SeverityLow = "low" )
The severities a finding can carry.
const ( Namespace = "agentry" Name = "drafter" Version = "1.22.0" )
The package's identity, as its manifest declares it.
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).
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.
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).
const ( RunsHere = "runs-here" DoesNotRunHere = "does-not-run-here" )
The two lists.
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.
const AllVersions = "all"
AllVersions is an entry's versions when it speaks for every version.
const CheckUnanswered = "unanswered"
CheckUnanswered is Word's for a check with no answer.
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).
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.
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.
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.
const MaxKnowledgePacks = 5
MaxKnowledgePacks is the most packs one draft takes: a hosted run's bound on attached packs.
const MaxRevisionTextBytes = 4000
MaxRevisionTextBytes bounds each of the person's two texts: the additional instructions and the problems with this draft.
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.
const RubricIDUndeclared = corejudge.RubricIDUndeclaredCapability
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.
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 ¶
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.
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.
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.
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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. An organization's managed settings may say otherwise (review.source): its own key, delivered to this computer, AI Review off, or paid with its credits, which is a *managed.PaidWithCredits (exit 11) for the caller to open an operation for, or to refuse with.
func NotRunReason ¶
NotRunReason is the clause the pages give a reason class, and whether the class is one of the closed set.
func PackSource ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) RecordCheck ¶
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 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 Pay ¶ added in v0.7.46
Pay opens an operation paid with an organization's credits on registry, for purpose (managed.PurposeSearch when only web search is paid that way). The caller ends it when the work is done.
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 ¶
func (r *RegistryChecker) Check(ctx context.Context, p draftcheck.Package) (*Check, error)
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 ¶
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 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 ¶
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.
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 ¶
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. Where an organization's credits pay for AI Review or web search, it refuses (LocalWebPaid with no Pay): work that can pay with them calls LocalWebPaid.
func LocalWebPaid ¶ added in v0.7.46
func LocalWebPaid(ctx context.Context, pol *policy.Policy, registry, purpose string, pay Pay) (*engine.WebRun, SearchState, error)
LocalWebPaid is LocalWeb for work that can pay with an organization's credits: where the managed settings say they pay for AI Review or web search, it opens an operation with pay, for purpose, and the run scans (and, for web search paid that way, searches) through the registry with the operation's token, as a hosted draft does with its job's. Pay keeps the operation for the caller to end. A nil pay refuses such work with the organization's sentence.
func SearchAccess ¶ added in v0.7.46
func SearchAccess(pol *policy.Policy) (provider, key string, state SearchState, err error)
SearchAccess is SearchKey with the provider the key is for: the policy's, or, when an organization's managed settings pay for web search with its own key (webSearch.source), the provider that key is for, read from the keychain entry it was delivered to. A lock to off refuses (exit 11); the organization's credits paying for it is a *managed.PaidWithCredits.
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 ¶
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 ¶
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 ¶
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.