1package tools
2
3import (
4 "context"
5 "encoding/json"
6 "fmt"
7 "strings"
8
9 "github.com/bnema/zut/packages/agent/subagents"
10 "github.com/bnema/zut/packages/core"
11 "github.com/bnema/zut/packages/provider"
12)
13
14// SubagentStopTool lets the manager request termination of a stuck background
15// sub-agent through the resident manager's cancellation lifecycle.
16type SubagentStopTool struct {
17 ResidentManager *subagents.ResidentManager
18 Enabled func() bool
19}
20
21type subagentStopArgs struct {
22 AgentID string `json:"agent_id"`
23}
24
25// subagentWaitOutcome reports the result of an explicit bounded wait on one
26// resident turn. An expired wait leaves the child active. Undelivered lists
27// steered follow-ups the child never read before that turn ended.
28type subagentWaitOutcome struct {
29 Seconds int `json:"seconds"`
30 TimedOut bool `json:"timed_out,omitempty"`
31 Status string `json:"status,omitempty"`
32 Error string `json:"error,omitempty"`
33 Summary string `json:"summary,omitempty"`
34 Undelivered []string `json:"undelivered,omitempty"`
35}
36
37type subagentActionResponse struct {
38 Action string `json:"action"`
39 Agent subagentStatusEntry `json:"agent"`
40}
41
42// Name returns the shared facade name: this type is an internal
43// implementation and is never registered on its own.
44func (t *SubagentStopTool) Name() string { return SubagentToolName }
45
46func (t *SubagentStopTool) Execute(ctx context.Context, raw json.RawMessage, _ func(string)) (core.ToolResult, error) {
47 if ctx != nil {
48 select {
49 case <-ctx.Done():
50 return core.ToolResult{}, ctx.Err()
51 default:
52 }
53 }
54 prefix := t.Name()
55 if t.ResidentManager == nil {
56 return protocolToolError(prefix + ": subagent runtime not available in this mode")
57 }
58 if t.Enabled == nil || !t.Enabled() {
59 return protocolToolError(prefix + ": subagent management is unavailable in this mode")
60 }
61
62 var args subagentStopArgs
63 if err := decodeSubagentArgs(raw, &args); err != nil {
64 return core.ToolResult{}, err
65 }
66 id := strings.TrimSpace(args.AgentID)
67 if id == "" {
68 return protocolToolError(prefix + ": agent_id is required")
69 }
70 snapshot, ok := findResidentStatusSnapshot(t.ResidentManager.Snapshot(), id)
71 if !ok {
72 return protocolToolError(fmt.Sprintf("%s: no such agent %q", prefix, id))
73 }
74 if err := t.ResidentManager.Stop(ctx, snapshot.ID); err != nil {
75 return core.ToolResult{}, fmt.Errorf("%s: %w", prefix, err)
76 }
77 if updated, ok := t.ResidentManager.SnapshotFor(snapshot.ID); ok {
78 snapshot = updated
79 }
80 return renderResidentAction("stop_requested", publicResidentStatus(snapshot))
81}
82
83func renderResidentAction(action string, entry subagentStatusEntry) (core.ToolResult, error) {
84 return renderSubagentResponse(subagentActionResponse{Action: action, Agent: entry})
85}
86
87func renderSubagentResponse(response any) (core.ToolResult, error) {
88 data, err := json.Marshal(response)
89 if err != nil {
90 return core.ToolResult{}, fmt.Errorf("subagent action: encode response: %w", err)
91 }
92 return core.ToolResult{Content: []provider.Content{provider.TextBlock{Text: string(data)}}, Details: response}, nil
93}