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// SubagentStatusTool reports live state for background sub-agents without
15// waiting for a child to finish. An omitted agent_id lists resident children;
16// an agent_id queries one child.
17// The result deliberately contains metadata only: it does not expose
18// transcripts, result output, credentials, provider settings, or filesystem
19// paths.
20type SubagentStatusTool struct {
21 ResidentManager *subagents.ResidentManager
22 Enabled func() bool
23}
24
25type subagentStatusArgs struct {
26 AgentID string `json:"agent_id,omitempty"`
27}
28
29type subagentStatusResponse struct {
30 Agent *subagentStatusEntry `json:"agent,omitempty"`
31 Agents []subagentStatusEntry `json:"agents"`
32}
33
34type subagentStatusEntry struct {
35 ID string `json:"agent_id"`
36 State subagents.ResidentState `json:"state"`
37 Profile string `json:"profile,omitempty"`
38 Provider string `json:"provider"`
39 Model string `json:"model"`
40 Workspace subagents.WorkspaceMode `json:"workspace_mode,omitempty"`
41 Required bool `json:"required,omitempty"`
42 OwnedElsewhere bool `json:"owned_elsewhere,omitempty"`
43 Budget *subagents.BudgetSnapshot `json:"budget,omitempty"`
44 BudgetSource string `json:"budget_source,omitempty"`
45}
46
47const subagentStatusSchema = `{
48 "type": "object",
49 "properties": {
50 "agent_id": {
51 "type": "string",
52 "description": "Optional child id or unique id prefix. Omit it to list all resident sub-agents."
53 }
54 }
55}`
56
57func (t *SubagentStatusTool) Name() string { return SubagentStatusToolName }
58
59func (t *SubagentStatusTool) Description() string {
60 return "Query live status for one background sub-agent or list all visible workers without waiting for completion."
61}
62
63func (t *SubagentStatusTool) Schema() json.RawMessage {
64 return json.RawMessage(subagentStatusSchema)
65}
66
67func (t *SubagentStatusTool) Execute(ctx context.Context, raw json.RawMessage, _ func(string)) (core.ToolResult, error) {
68 if ctx != nil {
69 select {
70 case <-ctx.Done():
71 return core.ToolResult{}, ctx.Err()
72 default:
73 }
74 }
75 prefix := t.Name()
76 if t.ResidentManager == nil {
77 return protocolToolError(prefix + ": subagent runtime not available in this mode")
78 }
79 if t.Enabled == nil || !t.Enabled() {
80 return protocolToolError(prefix + ": subagent status is unavailable in this mode")
81 }
82
83 var args subagentStatusArgs
84 if err := decodeSubagentArgs(raw, &args); err != nil {
85 return core.ToolResult{}, err
86 }
87 snapshots := t.ResidentManager.Snapshot()
88 id := strings.TrimSpace(args.AgentID)
89 if id == "" {
90 entries := make([]subagentStatusEntry, 0, len(snapshots))
91 for _, snapshot := range snapshots {
92 entries = append(entries, publicResidentStatus(snapshot))
93 }
94 return renderSubagentStatus(subagentStatusResponse{Agents: entries})
95 }
96 snapshot, ok := findResidentStatusSnapshot(snapshots, id)
97 if !ok {
98 return protocolToolError(fmt.Sprintf("%s: no such agent %q", prefix, id))
99 }
100 entry := publicResidentStatus(snapshot)
101 return renderSubagentStatus(subagentStatusResponse{Agent: &entry})
102}
103
104func findResidentStatusSnapshot(snapshots []subagents.ResidentSnapshot, id string) (subagents.ResidentSnapshot, bool) {
105 for _, snapshot := range snapshots {
106 if snapshot.ID == id {
107 return snapshot, true
108 }
109 }
110 var match subagents.ResidentSnapshot
111 hits := 0
112 for _, snapshot := range snapshots {
113 if strings.HasPrefix(snapshot.ID, id) {
114 match = snapshot
115 hits++
116 }
117 }
118 return match, hits == 1
119}
120
121func publicResidentStatus(snapshot subagents.ResidentSnapshot) subagentStatusEntry {
122 entry := subagentStatusEntry{ID: snapshot.ID, State: snapshot.State, Profile: snapshot.Profile, Provider: snapshot.Provider, Model: snapshot.Model, Workspace: snapshot.WorkspaceMode, Required: snapshot.Required, OwnedElsewhere: snapshot.OwnedElsewhere, BudgetSource: snapshot.BudgetSource}
123 if snapshot.Budget.Limit > 0 {
124 budget := snapshot.Budget
125 entry.Budget = &budget
126 }
127 return entry
128}
129
130func renderSubagentStatus(response subagentStatusResponse) (core.ToolResult, error) {
131 data, err := json.Marshal(response)
132 if err != nil {
133 return core.ToolResult{}, fmt.Errorf("%s: encode status: %w", "subagent_status", err)
134 }
135 return core.ToolResult{
136 Content: []provider.Content{provider.TextBlock{Text: string(data)}},
137 Details: response,
138 }, nil
139}