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.
27type subagentWaitOutcome struct {
28 Seconds int `json:"seconds"`
29 TimedOut bool `json:"timed_out,omitempty"`
30 Status string `json:"status,omitempty"`
31 Error string `json:"error,omitempty"`
32 Summary string `json:"summary,omitempty"`
33}
34
35type subagentActionResponse struct {
36 Action string `json:"action"`
37 Agent subagentStatusEntry `json:"agent"`
38 Wait *subagentWaitOutcome `json:"wait,omitempty"`
39}
40
41// Name returns the shared facade name: this type is an internal
42// implementation and is never registered on its own.
43func (t *SubagentStopTool) Name() string { return SubagentToolName }
44
45func (t *SubagentStopTool) Execute(ctx context.Context, raw json.RawMessage, _ func(string)) (core.ToolResult, error) {
46 if ctx != nil {
47 select {
48 case <-ctx.Done():
49 return core.ToolResult{}, ctx.Err()
50 default:
51 }
52 }
53 prefix := t.Name()
54 if t.ResidentManager == nil {
55 return protocolToolError(prefix + ": subagent runtime not available in this mode")
56 }
57 if t.Enabled == nil || !t.Enabled() {
58 return protocolToolError(prefix + ": subagent management is unavailable in this mode")
59 }
60
61 var args subagentStopArgs
62 if err := decodeSubagentArgs(raw, &args); err != nil {
63 return core.ToolResult{}, err
64 }
65 id := strings.TrimSpace(args.AgentID)
66 if id == "" {
67 return protocolToolError(prefix + ": agent_id is required")
68 }
69 snapshot, ok := findResidentStatusSnapshot(t.ResidentManager.Snapshot(), id)
70 if !ok {
71 return protocolToolError(fmt.Sprintf("%s: no such agent %q", prefix, id))
72 }
73 if err := t.ResidentManager.Stop(ctx, snapshot.ID); err != nil {
74 return core.ToolResult{}, fmt.Errorf("%s: %w", prefix, err)
75 }
76 if updated, ok := t.ResidentManager.SnapshotFor(snapshot.ID); ok {
77 snapshot = updated
78 }
79 return renderResidentAction("stop_requested", publicResidentStatus(snapshot))
80}
81
82func renderResidentAction(action string, entry subagentStatusEntry) (core.ToolResult, error) {
83 return renderResidentActionWait(action, entry, nil)
84}
85
86// renderResidentActionWait renders an action response plus the outcome of an
87// explicit bounded wait, if the caller requested one.
88func renderResidentActionWait(action string, entry subagentStatusEntry, wait *subagentWaitOutcome) (core.ToolResult, error) {
89 response := subagentActionResponse{Action: action, Agent: entry, Wait: wait}
90 data, err := json.Marshal(response)
91 if err != nil {
92 return core.ToolResult{}, fmt.Errorf("subagent action: encode response: %w", err)
93 }
94 return core.ToolResult{Content: []provider.Content{provider.TextBlock{Text: string(data)}}, Details: response}, nil
95}