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 // ReportDelivery identifies the full report's host channel when the wait
36 // returns status only. Without a host, Summary and Undelivered stay inline.
37 ReportDelivery string `json:"report_delivery,omitempty"`
38}
39
40const subagentReportHostUpdate = "host_update"
41
42type subagentActionResponse struct {
43 Action string `json:"action"`
44 Agent subagentStatusEntry `json:"agent"`
45}
46
47// Name returns the shared facade name: this type is an internal
48// implementation and is never registered on its own.
49func (t *SubagentStopTool) Name() string { return SubagentToolName }
50
51func (t *SubagentStopTool) Execute(ctx context.Context, raw json.RawMessage, _ func(string)) (core.ToolResult, error) {
52 if ctx != nil {
53 select {
54 case <-ctx.Done():
55 return core.ToolResult{}, ctx.Err()
56 default:
57 }
58 }
59 prefix := t.Name()
60 if t.ResidentManager == nil {
61 return protocolToolError(prefix + ": subagent runtime not available in this mode")
62 }
63 if t.Enabled == nil || !t.Enabled() {
64 return protocolToolError(prefix + ": subagent management is unavailable in this mode")
65 }
66
67 var args subagentStopArgs
68 if err := decodeSubagentArgs(raw, &args); err != nil {
69 return core.ToolResult{}, err
70 }
71 id := strings.TrimSpace(args.AgentID)
72 if id == "" {
73 return protocolToolError(prefix + ": agent_id is required")
74 }
75 snapshot, ok := findResidentStatusSnapshot(t.ResidentManager.Snapshot(), id)
76 if !ok {
77 return protocolToolError(fmt.Sprintf("%s: no such agent %q", prefix, id))
78 }
79 if err := t.ResidentManager.Stop(ctx, snapshot.ID); err != nil {
80 return core.ToolResult{}, fmt.Errorf("%s: %w", prefix, err)
81 }
82 if updated, ok := t.ResidentManager.SnapshotFor(snapshot.ID); ok {
83 snapshot = updated
84 }
85 return renderResidentAction("stop_requested", publicResidentStatus(snapshot))
86}
87
88func renderResidentAction(action string, entry subagentStatusEntry) (core.ToolResult, error) {
89 return renderSubagentResponse(subagentActionResponse{Action: action, Agent: entry})
90}
91
92func renderSubagentResponse(response any) (core.ToolResult, error) {
93 data, err := json.Marshal(response)
94 if err != nil {
95 return core.ToolResult{}, fmt.Errorf("subagent action: encode response: %w", err)
96 }
97 return core.ToolResult{Content: []provider.Content{provider.TextBlock{Text: string(data)}}, Details: response}, nil
98}