Documentation
¶
Overview ¶
Package conclusion implements the delegated-task conclusion protocol: parsing the sentinel <pando:conclusion> block emitted by a subagent and enriching it with software-owned launch metadata.
The package intentionally depends only on the domain models (plus stdlib and a YAML parser) so it can be reused by the orchestrator and app wiring without creating import cycles with internal/config or internal/project. Config and project resolution are threaded in via plain function/struct values.
Index ¶
- func BriefInstruction() string
- func Enrich(task *models.Task, cfg DelegationOptions, resolver ProjectResolver) *models.Conclusion
- func FormatForParent(task *models.Task, res *ResolveOptions) string
- func Parse(raw string) (*models.Conclusion, bool)
- type ArtifactResolver
- type DelegationOptions
- type MemoryRefResolver
- type ProjectResolver
- type ResolveOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BriefInstruction ¶
func BriefInstruction() string
BriefInstruction returns the instruction appended to a delegated subagent's prompt when delegation is enabled. It tells the subagent to close its run with a single <pando:conclusion> sentinel block listing ONLY the model-known fields. The software fills in all launch metadata (task id, engine, model, project, parent session, timestamps) from the task record it owns, so the model must NOT restate those.
The text is centralized here so it is reusable and testable, and so the orchestrator can append it as the trailing instruction after persona is applied.
func Enrich ¶
func Enrich(task *models.Task, cfg DelegationOptions, resolver ProjectResolver) *models.Conclusion
Enrich builds the durable Conclusion for a terminal task. It parses the task's output for the sentinel block, synthesizes a fallback when configured, and always fills software-owned metadata (CapturedAt, project id/name). It returns nil when no conclusion can or should be captured.
The function is pure with respect to globals: everything it needs is passed in. It mutates task.ProjectID / task.ProjectName as a convenience for the caller (the resolved project is software-owned launch metadata) but never panics on nil inputs.
func FormatForParent ¶
func FormatForParent(task *models.Task, res *ResolveOptions) string
FormatForParent renders a compact, pointers-not-dumps message describing a delegated task's result, suitable for injection into the parent agent loop. The header line carries only software-owned launch metadata (task id, engine, project, status, confidence) — never values the model could have hallucinated. The body carries the model-provided summary plus optional follow-up, artifacts and memory refs (each omitted when empty) so the parent can lazily fetch detail.
res controls optional enrichment of artifact paths and memory refs. When res is nil (or the individual resolver is nil), the corresponding field is rendered as a plain comma-joined list — byte-for-byte identical to the pre-resolver output. When a resolver is provided, each entry is rendered on its own line under the field header, resolved via the supplied function.
It is nil-safe: a task without a Conclusion yields a minimal single line so the parent still learns the task finished.
func Parse ¶
func Parse(raw string) (*models.Conclusion, bool)
Parse scans raw for the sentinel block delimited by <pando:conclusion> ... </pando:conclusion>. When multiple blocks are present the LAST one is used (it is the final summary). The inner body is parsed as YAML; parsing is tolerant: missing fields default to their zero value, and an unparseable body with a present sentinel still returns a Conclusion whose Summary is the salvaged raw inner text.
Soft-schema validation accumulates human-readable warnings in Conclusion.Warnings describing what was malformed/missing/out-of-range. Data is never discarded due to warnings — the principle is warn, don't discard.
It returns (conclusion, true) when a block was found, (nil, false) otherwise.
Types ¶
type ArtifactResolver ¶ added in v0.603.0
ArtifactResolver enriches an artifact reference string for display. It receives the raw ref (a file path, URL, or any opaque token) and returns a richer display string. It must return the input unchanged when enrichment is not possible or the ref is unrecognized.
func NewFilesystemArtifactResolver ¶ added in v0.603.0
func NewFilesystemArtifactResolver(baseDir string) ArtifactResolver
NewFilesystemArtifactResolver returns an ArtifactResolver that stats each artifact path on the local filesystem and appends a human-readable size or "(missing)" suffix. If the ref is a relative path, it is resolved against baseDir. A blank baseDir or any stat error returns the bare ref unchanged.
type DelegationOptions ¶
type DelegationOptions struct {
// SynthesizeFallback enables deriving a conclusion from output/error when the
// subagent did not emit a sentinel block. When false, a missing block means no
// conclusion is captured.
SynthesizeFallback bool
}
DelegationOptions carries the conclusion-relevant knobs the enricher needs. It is defined here (rather than importing internal/config) so the conclusion package stays free of import cycles; the app/orchestrator translate config into this value.
type MemoryRefResolver ¶ added in v0.603.0
MemoryRefResolver enriches a memory-ref identifier for display. It receives the raw ref (a KB path, memory key, or any opaque token) and returns a richer display string. It must return the input unchanged when enrichment is not possible.
type ProjectResolver ¶
ProjectResolver maps a canonical project path to its registry id and display name. It returns empty strings when the path is not a registered project.
type ResolveOptions ¶ added in v0.603.0
type ResolveOptions struct {
// Artifacts, when non-nil, is called for each artifact entry. When nil,
// artifacts are rendered as a plain comma-joined list (legacy behavior).
Artifacts ArtifactResolver
// Memory, when non-nil, is called for each memory_ref entry. When nil,
// memory_refs are rendered as a plain comma-joined list (legacy behavior).
Memory MemoryRefResolver
}
ResolveOptions carries optional resolvers that FormatForParent uses to enrich artifact and memory-ref entries. A nil *ResolveOptions or a nil resolver field means no enrichment is applied for that category — the output is byte-for-byte identical to the pre-resolver behavior.
Source Files