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}
44
45const subagentStatusSchema = `{
46 "type": "object",
47 "properties": {
48 "agent_id": {
49 "type": "string",
50 "description": "Optional child id or unique id prefix. Omit it to list all resident sub-agents."
51 }
52 }
53}`
54
55func (t *SubagentStatusTool) Name() string { return SubagentStatusToolName }
56
57func (t *SubagentStatusTool) Description() string {
58 return "Query live status for one background sub-agent or list all visible workers without waiting for completion."
59}
60
61func (t *SubagentStatusTool) Schema() json.RawMessage {
62 return json.RawMessage(subagentStatusSchema)
63}
64
65func (t *SubagentStatusTool) Execute(ctx context.Context, raw json.RawMessage, _ func(string)) (core.ToolResult, error) {
66 if ctx != nil {
67 select {
68 case <-ctx.Done():
69 return core.ToolResult{}, ctx.Err()
70 default:
71 }
72 }
73 prefix := t.Name()
74 if t.ResidentManager == nil {
75 return protocolToolError(prefix + ": subagent runtime not available in this mode")
76 }
77 if t.Enabled == nil || !t.Enabled() {
78 return protocolToolError(prefix + ": subagent status is unavailable in this mode")
79 }
80
81 var args subagentStatusArgs
82 if err := decodeSubagentArgs(raw, &args); err != nil {
83 return core.ToolResult{}, err
84 }
85 snapshots := t.ResidentManager.Snapshot()
86 id := strings.TrimSpace(args.AgentID)
87 if id == "" {
88 entries := make([]subagentStatusEntry, 0, len(snapshots))
89 for _, snapshot := range snapshots {
90 entries = append(entries, publicResidentStatus(snapshot))
91 }
92 return renderSubagentStatus(subagentStatusResponse{Agents: entries})
93 }
94 snapshot, ok := findResidentStatusSnapshot(snapshots, id)
95 if !ok {
96 return protocolToolError(fmt.Sprintf("%s: no such agent %q", prefix, id))
97 }
98 entry := publicResidentStatus(snapshot)
99 return renderSubagentStatus(subagentStatusResponse{Agent: &entry})
100}
101
102func findResidentStatusSnapshot(snapshots []subagents.ResidentSnapshot, id string) (subagents.ResidentSnapshot, bool) {
103 for _, snapshot := range snapshots {
104 if snapshot.ID == id {
105 return snapshot, true
106 }
107 }
108 var match subagents.ResidentSnapshot
109 hits := 0
110 for _, snapshot := range snapshots {
111 if strings.HasPrefix(snapshot.ID, id) {
112 match = snapshot
113 hits++
114 }
115 }
116 return match, hits == 1
117}
118
119func publicResidentStatus(snapshot subagents.ResidentSnapshot) subagentStatusEntry {
120 return 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}
121}
122
123func renderSubagentStatus(response subagentStatusResponse) (core.ToolResult, error) {
124 data, err := json.Marshal(response)
125 if err != nil {
126 return core.ToolResult{}, fmt.Errorf("%s: encode status: %w", "subagent_status", err)
127 }
128 return core.ToolResult{
129 Content: []provider.Content{provider.TextBlock{Text: string(data)}},
130 Details: response,
131 }, nil
132}