Files
sam 846626fabf feat(gateway): read instructions and access policies from the workflow tools
settings_get now reads three more kinds:
- soul, the instruction text layered into a workflow run;
- task-policy, the diff cap and alert delivery settings;
- org-model-policy, which models an org may use.

None of them holds a secret value: task-policy's notify_secret and the
secrets elsewhere in the readable kinds are SecretRef references (engine and
key), never the resolved value.

access_policies_list is new: the caller org's Cedar policies (id, level,
scope, text), and the instance policies when the caller owns the instance,
which is what the dashboard lists for the same read. It is guarded as
access.ActionRead on access.KindPolicy, the check the dashboard makes.
IntegrationSource gained Policies, implemented over the State Store's
ListPolicies.

workflow_get now says how its instructions field layers: after the
instance's and the organisation's, before the repository's.
2026-10-18 02:39:25 +11:00

242 lines
8.9 KiB
Go

package gateway
import (
"context"
"encoding/json"
"fmt"
"strings"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/internal/domain/access"
"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)
Draft(ctx context.Context, id string) (yaml string, ok bool, err error)
PutDraft(ctx context.Context, id, yaml string) 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 workflow tools over source. The model writes only
// drafts; publishing is left to the operator in the workflow editor. Nil
// source registers none.
// Reads are checked as reading the workflow-definitions settings and a
// draft as writing workflow-drafts, the checks the workflow editor gets.
func WorkflowTools(source WorkflowSource, authz access.Authorizer) []tools.ToolEntry {
if source == nil || authz == nil {
return nil
}
read := func(entry tools.ToolEntry) tools.ToolEntry {
return guarded(authz, access.ActionRead, access.KindPolicy, fixedID("workflow-definitions"), entry)
}
return []tools.ToolEntry{
read(workflowListTool(source)),
read(workflowGetTool(source)),
read(workflowStepTypesTool(source)),
read(workflowValidateTool(source)),
guarded(authz, access.ActionManageIdentities, access.KindPolicy, fixedID("workflow-drafts"), workflowDraftTool(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: its draft when the operator has one open, else the published definition. Read a similar workflow before writing a new one. Its instructions field is one layer of the agent's brief, given after the instance's and the organisation's and before the repository's; a narrower layer refines the one above it.",
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"]))
draft, ok, err := source.Draft(ctx, id)
if err != nil {
return nil, fmt.Errorf("workflow_get: %w", err)
}
if ok {
return map[string]any{"id": id, "yaml": draft, "draft": true}, nil
}
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]any{"id": entry.ID, "yaml": entry.YAML, "draft": false}, 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 writing the draft.",
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
},
}
}
func workflowDraftTool(source WorkflowSource) tools.ToolEntry {
return tools.ToolEntry{
Name: "workflow_draft",
Toolset: "workflows",
Description: "Write the complete YAML as a workflow's draft. The operator sees it in the workflow editor, " +
"keeps or reverts each change, and publishes it; nothing runs from a draft. " +
"Validate first. id is the workflow being edited, even when the YAML renames it.",
Classification: tools.ClassMutating,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"id": map[string]any{"type": "string", "description": "The workflow being edited."},
"yaml": map[string]any{"type": "string", "description": "The complete workflow definition."},
},
"required": []any{"id", "yaml"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
id := strings.TrimSpace(asString(input["id"]))
if id == "" {
return nil, fmt.Errorf("workflow_draft: id is required")
}
if err := source.PutDraft(ctx, id, asString(input["yaml"])); err != nil {
return nil, fmt.Errorf("workflow_draft: %w", err)
}
return map[string]any{"id": id, "saved": true}, 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
}