Files
archie/internal/domain/workflow/outputs.go
T

226 lines
8.3 KiB
Go

package workflow
import (
"encoding/json"
"fmt"
"maps"
"slices"
"strings"
"github.com/samcharles93/archie-core/internal/domain/agentrun"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
)
// Declared workflow outputs are written through capture tools named after
// them; the engine validates, publishes and persists accepted values.
// workflowInterface is the declaration the run's compiled workflow carries
// (Workflow.Interface, set by Run); a stage body invoked outside Run falls
// back to the pinned definition's YAML, which the pin guarantees matches the
// compile the request came from.
func (tc *TaskContext) workflowInterface() task.WorkflowInterface {
if tc.runInterfaceSet {
return tc.runInterface
}
if tc.ifaceParsed == nil {
parsed, err := task.ParseWorkflowInterface(tc.Task.WorkflowDefinitionYAML)
if err != nil {
// The pinned YAML was validated when the definition was saved, so
// a parse failure here cannot be a definition the engine accepts;
// an empty interface keeps such a run output-less.
parsed = task.WorkflowInterface{}
tc.Log.Warn("pinned workflow definition does not parse for outputs; ignoring declared outputs", "err", err)
}
tc.ifaceParsed = &parsed
}
return *tc.ifaceParsed
}
// WriteOutput records one declared output's value for this attempt: the path
// a deterministic Go stage takes. An undeclared key, a mistyped value or a
// second write is refused, and the refusing error parks the run before its
// outcome transition.
func (tc *TaskContext) WriteOutput(name string, value any) error {
spec, ok := tc.workflowInterface().Outputs[name]
if !ok {
return fmt.Errorf("output %q is not declared by the workflow", name)
}
if _, written := tc.Task.Outputs[name]; written {
return fmt.Errorf("output %q has already been written; each output is written once per attempt", name)
}
if value != nil {
if got := task.ValueType(value); !task.TypeAccepts(spec.Type, got) {
return fmt.Errorf("output %q is %s, want %s", name, got, spec.Type)
}
}
if tc.Task.Outputs == nil {
tc.Task.Outputs = map[string]any{}
}
tc.Task.Outputs[name] = value
return nil
}
// outputCaptureTool builds the capture tool one declared output is offered
// as: named after the output, whose arguments are {"value": ...}, with the
// declared type as the value's schema. The schema guides the agent; the
// run-time re-check is what enforces.
func outputCaptureTool(name string, spec task.OutputSpec) agentrun.CaptureTool {
value := map[string]any{"description": fmt.Sprintf("The value of the %q output.", name)}
if typ := jsonSchemaType(spec.Type); typ != "" {
// Null is how the agent withdraws a value it cannot supply, and the
// run reads a null value as "not written" (decodeCapturedOutput), so
// the advertised schema has to permit it or the call would be
// rejected for the value the contract assigns a meaning to.
value["type"] = []string{typ, "null"}
}
params, err := json.Marshal(map[string]any{
"type": "object",
"properties": map[string]any{"value": value},
"required": []string{"value"},
})
if err != nil {
// A fixed-shape map cannot fail to marshal. Keep the call acceptable
// through RequiredFields alone if it ever did.
params = []byte(`{"type":"object"}`)
}
return agentrun.CaptureTool{
Name: name,
Description: fmt.Sprintf("Write the workflow output %q. Call exactly once, with the value as the value argument.", name),
Parameters: params,
// The value member is required, but a null value counts as not written
// (there is nothing to reject: the run simply does not write it).
RequiredFields: []string{"value"},
MaxCalls: 1,
}
}
// jsonSchemaType maps the workflow value vocabulary onto JSON Schema's type
// names. "any" has no constraint, so it yields no type at all -- an empty
// string, never a null that is not a valid JSON Schema type.
func jsonSchemaType(vocab string) string {
switch vocab {
case "string", "number", "object", "array":
return vocab
case "bool":
return "boolean"
default: // "any"
return ""
}
}
// appendOutputTools offers the declared outputs the run has not written yet
// to this stage as capture tools, refusing a stage capture tool that shares a
// declared output's name: the value would otherwise be ambiguous.
func (tc *TaskContext) appendOutputTools(tools []agentrun.CaptureTool) ([]agentrun.CaptureTool, error) {
iface := tc.workflowInterface()
for _, tool := range tools {
if _, clash := iface.Outputs[tool.Name]; clash {
return nil, fmt.Errorf("output %q is also a stage capture tool's name; a declared output is written through its own tool", tool.Name)
}
}
for _, name := range slices.Sorted(maps.Keys(iface.Outputs)) {
// A stage is not offered an output the run has written.
if _, already := tc.Task.Outputs[name]; already {
continue
}
tools = append(tools, outputCaptureTool(name, iface.Outputs[name]))
}
return tools, nil
}
// applyOutputCaptures applies the declared-output capture calls a passed
// agent result carries: the accepted call's value member is the output's
// value, re-validated against the declared type the way readCaptures
// re-checks every record, before it enters the run's set.
func (tc *TaskContext) applyOutputCaptures(res agentrun.Result) error {
iface := tc.workflowInterface()
for name, calls := range res.Captures {
spec, ok := iface.Outputs[name]
if !ok {
// Every other capture tool is the stage's own; its OnResult owns
// its records.
continue
}
for _, call := range calls {
value, written, err := decodeCapturedOutput(call)
if err != nil {
return fmt.Errorf("output %q: %w", name, err)
}
if !written {
continue
}
if got := task.ValueType(value); !task.TypeAccepts(spec.Type, got) {
return fmt.Errorf("output %q is %s, want %s", name, got, spec.Type)
}
if _, written := tc.Task.Outputs[name]; written {
return fmt.Errorf("output %q has already been written; each output is written once per attempt", name)
}
if tc.Task.Outputs == nil {
tc.Task.Outputs = map[string]any{}
}
tc.Task.Outputs[name] = value
}
}
return nil
}
// decodeCapturedOutput reads one accepted capture call's value member. A call
// with no value, or a null value, counts as not written, as CheckInputs
// treats a null input.
func decodeCapturedOutput(call json.RawMessage) (value any, written bool, err error) {
var args struct {
Value json.RawMessage `json:"value"`
}
if err := json.Unmarshal(call, &args); err != nil {
return nil, false, err
}
if len(args.Value) == 0 || string(args.Value) == "null" {
return nil, false, nil
}
decoder := json.NewDecoder(strings.NewReader(string(args.Value)))
decoder.UseNumber()
if err := decoder.Decode(&value); err != nil {
return nil, false, err
}
return value, true, nil
}
// validateFinishOutputs checks the attempt's written outputs before the
// outcome transition: required, undeclared and mistyped values park here, so
// no caller observes a terminal state that breaks the run's own promise.
func (tc *TaskContext) validateFinishOutputs() error {
return tc.workflowInterface().CheckOutputs(tc.Task.Outputs)
}
// publishCalleeOutputs copies a successful callee's assigned outputs into the
// caller's. An unwritten or null output stays absent; a type the caller's
// declaration cannot accept is refused.
func (tc *TaskContext) publishCalleeOutputs(assignments map[string]string, calleeOutputs map[string]any) error {
if len(assignments) == 0 {
return nil
}
iface := tc.workflowInterface()
for _, calleeName := range slices.Sorted(maps.Keys(assignments)) {
ref := assignments[calleeName]
callerName := strings.TrimPrefix(ref, outputReference)
spec, ok := iface.Outputs[callerName]
if !ok {
// The save check refuses an undeclared reference; this re-check
// keeps a swapped callee from publishing into nothing.
return fmt.Errorf("output %q references %q, which this workflow does not declare", calleeName, ref)
}
value, ok := calleeOutputs[calleeName]
if !ok || value == nil {
// Declared but never written: the caller's output stays absent.
continue
}
if got := task.ValueType(value); !task.TypeAccepts(spec.Type, got) {
return fmt.Errorf("callee output %q is %s, which this workflow's output %q (%s) cannot accept", calleeName, got, callerName, spec.Type)
}
if err := tc.WriteOutput(callerName, value); err != nil {
return err
}
}
return nil
}