Files
pipelines/internal/stage/tools.go
T
alan f57457aec9 Make agent-stage retries safe and retain timeout failure evidence
Fix four stage failure-handling and observability defects (A2, A3, A6, A9).

- A2: add safeToReplay(def) as the single definition of retryable post-admission
  work - only an explicit tools block that selects neither edit nor shell. The
  agent/pi WorkStarted guards now break only when the stage is not safe to
  replay, so read-only stages genuinely retry a post-admission timeout while
  mutating and legacy-bundle stages still never replay admitted work.
- A6: re-emit a malformed final result on an explicit read-only stage up to the
  retry budget, preserving format_repairs evidence; mutating stages keep the
  immediate return and their session.
- A3: timed-out stages retain usable evidence. waitForSessionIdle records one
  bounded sanitized OperationEvidence on deadline; the agent deferred cleanup
  does a bounded best-effort latest-assistant readback and settles knowable V2
  usage; RetainSession adds a retained_session pointer to failed step
  transcripts so the session is visible beneath the BoundTranscript threshold.
- A9: a stage outcome routed to #failure now yields a non-empty run diagnostic
  ("stage <name> returned outcome <outcome>") while preferring an existing step
  diagnostic.

Adds focused stage and server tests for retry safety, malformed-result
re-emission, timeout evidence retention and run-level diagnostics; updates the
packaged skill references and docs/cli.md, docs/model-results.md.
2026-10-15 18:27:22 +01:00

126 lines
3.9 KiB
Go

package stage
import (
"fmt"
"path/filepath"
"regexp"
"strings"
)
// ToolNames validates model-stage permissions, not general graph semantics.
// A present empty block explicitly denies all tools.
func ToolNames(def Definition) ([]string, bool, error) {
text, present := def.Blocks["tools"]
if !present {
return nil, false, nil
}
tools := []string{}
seen := map[string]bool{}
for _, line := range strings.Split(text, "\n") {
name := strings.TrimSpace(line)
if name == "" {
continue
}
switch name {
case "websearch", "webfetch", "read", "glob", "grep", "edit", "shell":
default:
return nil, true, fmt.Errorf("unsupported tool %q", name)
}
if seen[name] {
return nil, true, fmt.Errorf("duplicate tool %s", name)
}
seen[name] = true
tools = append(tools, name)
}
return tools, true, nil
}
// safeToReplay is the single definition of which post-admission work may be
// automatically retried. Only an explicit tools block that selects neither
// "edit" nor "shell" is side-effect free. An absent block is the legacy
// read/glob/grep/edit/shell bundle and is treated as mutating, matching the
// runner's useAgent/permissionRules semantics.
func safeToReplay(def Definition) bool {
tools, explicit, err := ToolNames(def)
if err != nil || !explicit {
return false
}
for _, tool := range tools {
if tool == "edit" || tool == "shell" {
return false
}
}
return true
}
func (c *AgentClient) permissionRules() []map[string]string {
rules := []map[string]string{{"action": "*", "resource": "*", "effect": "deny"}}
tools := c.Tools
// A missing block gets normal local agent tools. Explicit stage blocks still
// select which tools are available, including an empty block for text-only work.
if tools == nil {
tools = []string{"read", "glob", "grep", "edit", "shell"}
}
allow := func(action, resource string) {
rules = append(rules, map[string]string{"action": action, "resource": resource, "effect": "allow"})
}
for _, tool := range tools {
switch tool {
case "websearch", "webfetch", "read", "glob", "grep":
allow(tool, "*")
case "edit":
if len(c.WritePaths) == 0 && c.Policy.Edit == nil {
allow("edit", "*")
rules = append(rules, map[string]string{"action": "edit", "resource": "/*", "effect": "deny"})
if c.Directory != "" {
allow("edit", filepath.ToSlash(filepath.Join(c.Directory, "*")))
}
} else {
paths := c.WritePaths
if len(paths) == 0 {
paths = c.Policy.Edit
}
// Relative patterns may also match absolute paths. Deny those first,
// then grant only absolute equivalents inside the run directory.
for _, path := range paths {
if c.Policy.Edit == nil || matchesEditPolicy(c.Policy.Edit, path) {
allow("edit", filepath.ToSlash(path))
}
}
rules = append(rules, map[string]string{"action": "edit", "resource": "/*", "effect": "deny"})
for _, path := range paths {
if c.Directory != "" && (c.Policy.Edit == nil || matchesEditPolicy(c.Policy.Edit, path)) {
allow("edit", filepath.ToSlash(filepath.Join(c.Directory, path)))
}
}
}
for _, pattern := range []string{"../*", "*/../*"} {
rules = append(rules, map[string]string{"action": "edit", "resource": pattern, "effect": "deny"})
}
case "shell":
if c.Policy.Shell == nil {
allow("shell", "*")
} else {
for _, command := range c.Policy.Shell {
allow("shell", command)
}
}
}
}
for _, pattern := range []string{"*.env", "*.env.*", "pipelines.db*"} {
rules = append(rules, map[string]string{"action": "read", "resource": pattern, "effect": "deny"})
}
return rules
}
func matchesEditPolicy(patterns []string, path string) bool {
for _, pattern := range patterns {
// OpenCode resource wildcards match across directory separators.
re := strings.ReplaceAll(strings.ReplaceAll(regexp.QuoteMeta(pattern), `\*`, ".*"), `\?`, ".")
if ok, _ := regexp.MatchString("^"+re+"$", filepath.ToSlash(path)); ok {
return true
}
}
return false
}