Files
archie/internal/gateway/workflow_tools.go
T
sam c5158edb6c feat(gateway): chat reads workflows and validates drafts
workflow_list, workflow_get and workflow_step_types read the org's
definitions and step catalog; workflow_validate runs the editor's save
check on a proposed definition without saving it.
2026-10-16 03:46:27 +11:00

197 lines
6.6 KiB
Go

package gateway
import (
"context"
"encoding/json"
"fmt"
"strings"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/tools"
)
// WorkflowSource is the control-plane surface the workflow tools use, acting
// in the caller's org. Validate returns the reason a collection is refused,
// or "" when it would be accepted; err is reserved for an unavailable store.
type WorkflowSource interface {
Workflows(ctx context.Context) (task.WorkflowDefinitionCollection, error)
StepTypes(ctx context.Context) (json.RawMessage, error)
Validate(ctx context.Context, collection task.WorkflowDefinitionCollection) (problem string, err error)
}
// WorkflowSummary is one workflow as workflow_list shows it.
type WorkflowSummary struct {
ID string `json:"id"`
Steps []string `json:"steps"`
}
// WorkflowValidation is what workflow_validate returns.
type WorkflowValidation struct {
ID string `json:"id,omitempty"`
Valid bool `json:"valid"`
Replace bool `json:"replaces_existing,omitempty"`
Problem string `json:"problem,omitempty"`
}
// WorkflowTools returns the read and validate tools over source. Saving is
// left to the operator in the workflow editor. Nil source registers none.
func WorkflowTools(source WorkflowSource) []tools.ToolEntry {
if source == nil {
return nil
}
return []tools.ToolEntry{
workflowListTool(source),
workflowGetTool(source),
workflowStepTypesTool(source),
workflowValidateTool(source),
}
}
func workflowListTool(source WorkflowSource) tools.ToolEntry {
return tools.ToolEntry{
Name: "workflow_list",
Toolset: "workflows",
Description: "List the workflows defined in this org with the step types each runs, in order.",
Classification: tools.ClassIdempotent,
Schema: tools.JSONSchema{"type": "object", "properties": map[string]any{}},
Handler: func(ctx context.Context, _ map[string]any) (any, error) {
collection, err := source.Workflows(ctx)
if err != nil {
return nil, fmt.Errorf("workflow_list: %w", err)
}
out := make([]WorkflowSummary, 0, len(collection.Definitions))
for _, entry := range collection.Definitions {
out = append(out, WorkflowSummary{ID: entry.ID, Steps: stepTypesOf(entry.YAML)})
}
return out, nil
},
}
}
func workflowGetTool(source WorkflowSource) tools.ToolEntry {
return tools.ToolEntry{
Name: "workflow_get",
Toolset: "workflows",
Description: "Return one workflow's YAML definition. Read a similar workflow before writing a new one.",
Classification: tools.ClassIdempotent,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{"id": map[string]any{"type": "string", "description": "The workflow id from workflow_list."}},
"required": []any{"id"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
id := strings.TrimSpace(asString(input["id"]))
collection, err := source.Workflows(ctx)
if err != nil {
return nil, fmt.Errorf("workflow_get: %w", err)
}
entry, ok := collection.DefinitionByID(id)
if !ok {
return nil, fmt.Errorf("workflow_get: no workflow %q", id)
}
return map[string]string{"id": entry.ID, "yaml": entry.YAML}, nil
},
}
}
func workflowStepTypesTool(source WorkflowSource) tools.ToolEntry {
return tools.ToolEntry{
Name: "workflow_step_types",
Toolset: "workflows",
Description: "Return the step types a workflow may use, with each type's settings schema.",
Classification: tools.ClassIdempotent,
Schema: tools.JSONSchema{"type": "object", "properties": map[string]any{}},
Handler: func(ctx context.Context, _ map[string]any) (any, error) {
types, err := source.StepTypes(ctx)
if err != nil {
return nil, fmt.Errorf("workflow_step_types: %w", err)
}
return types, nil
},
}
}
func workflowValidateTool(source WorkflowSource) tools.ToolEntry {
return tools.ToolEntry{
Name: "workflow_validate",
Toolset: "workflows",
Description: "Check a workflow YAML definition exactly as saving it would, without saving. " +
"Fix every problem it reports and validate again before giving the operator the YAML, " +
"who saves it from the workflow editor.",
Classification: tools.ClassIdempotent,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{"yaml": map[string]any{"type": "string", "description": "The complete workflow definition."}},
"required": []any{"yaml"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
src := asString(input["yaml"])
id, problem := definitionID(src)
if problem != "" {
return WorkflowValidation{Problem: problem}, nil
}
collection, err := source.Workflows(ctx)
if err != nil {
return nil, fmt.Errorf("workflow_validate: %w", err)
}
proposed, replaced := withDefinition(collection, id, src)
problem, err = source.Validate(ctx, proposed)
if err != nil {
return nil, fmt.Errorf("workflow_validate: %w", err)
}
return WorkflowValidation{ID: id, Valid: problem == "", Replace: replaced, Problem: problem}, nil
},
}
}
// withDefinition returns collection with src as workflow id, replacing an
// existing definition of that id or appending a new one.
func withDefinition(collection task.WorkflowDefinitionCollection, id, src string) (task.WorkflowDefinitionCollection, bool) {
out := task.WorkflowDefinitionCollection{Definitions: make([]task.WorkflowDefinitionEntry, 0, len(collection.Definitions)+1)}
replaced := false
for _, entry := range collection.Definitions {
if entry.ID == id {
entry.YAML, replaced = src, true
}
out.Definitions = append(out.Definitions, entry)
}
if !replaced {
out.Definitions = append(out.Definitions, task.WorkflowDefinitionEntry{ID: id, YAML: src})
}
return out, replaced
}
// definitionID returns the id src declares, or why it declares none.
func definitionID(src string) (id, problem string) {
var declared struct {
ID string `yaml:"id"`
}
if err := yaml.Unmarshal([]byte(src), &declared); err != nil {
return "", "the YAML does not parse: " + err.Error()
}
if strings.TrimSpace(declared.ID) == "" {
return "", "the definition needs an id"
}
return declared.ID, ""
}
// stepTypesOf lists a definition's top-level step types; a definition that
// does not parse lists none.
func stepTypesOf(src string) []string {
var def struct {
Steps []struct {
Type string `yaml:"type"`
} `yaml:"steps"`
}
_ = yaml.Unmarshal([]byte(src), &def)
out := make([]string, 0, len(def.Steps))
for _, step := range def.Steps {
if step.Type != "" {
out = append(out, step.Type)
}
}
return out
}