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