package main import ( "context" "errors" "fmt" "os" "slices" "strings" "sync" ) const ( // subagentNote is the first message of the log of a subagent. subagentNote = "subagent" // subagentNoteEffort follows subagentNote when the subagent has its own // effort. subagentNoteEffort = " at effort " ) // errSubagentClosed tells that the runs of the subagents ended with the loop. var errSubagentClosed = errors.New("the daemon stops, so no subagent starts") // SubagentRuns runs the subagents of one agent in the background. Each run is a // goroutine with its own context, which only Stop and Close end. A run is one // or more request chains. The first request of each chain holds the view of the // agent at the start of the run, then the state of the turn, then the whole log // of the subagent. A message of Tell that comes during a chain joins its next // request after the tool results. One that comes after the final answer starts // one more chain, which reads the log again. The report of the run goes to // report: the final answer of each chain, or the error of a failed call. Stop // ends one run, and its report says that it stopped. At the stop of the daemon // the runs end with no report. // // Spawn and Tell split the view with the layout of the agent, which has no // lock. They are tools, so they run in the goroutine of the turns, as each // split of a turn does. type SubagentRuns struct { agent *Agent memory *Memory subagents *Subagents layout *ViewLayout client ChainClient state func() string report func(text string, stopped bool) note func(text string) error notify func(Event) mutex sync.Mutex running map[string]*SubagentRun closed bool workers sync.WaitGroup } // Spawn starts one subagent for each task and returns their names at once. It // waits until the view has no pending summary, and gives the view to each // subagent. A nil effort is the effort of the agent. func (r *SubagentRuns) Spawn(ctx context.Context, tasks []string, effort *string) (string, error) { if len(tasks) == 0 { return "", errors.New("no tasks") } r.mutex.Lock() closed := r.closed r.mutex.Unlock() if closed { return "", errSubagentClosed } note := subagentNote runEffort := r.agent.config.Effort if effort != nil && !slices.Contains(promptEfforts, *effort) { return "", fmt.Errorf("no effort %q: one of %s", *effort, strings.Join(promptEfforts, ", ")) } if effort != nil && *effort != runEffort { note += subagentNoteEffort + *effort runEffort = *effort } err := r.memory.Settle(ctx) if err != nil { return "", fmt.Errorf("wait for the summaries: %w", err) } view, err := r.layout.Split(r.memory.ViewLines(nil)) if err != nil { return "", err } names := make([]string, 0, len(tasks)) for _, task := range tasks { name, err := r.create(ctx, note, task, view, runEffort) if err != nil && len(names) > 0 { return "", fmt.Errorf("started %s, then: %w", strings.Join(names, ", "), err) } if err != nil { return "", err } names = append(names, name) } return "Started " + strings.Join(names, ", ") + ". Each one's report will reach you as a message when it finishes.", nil } // Tell sends message to the subagent name. A running subagent reads it between // its tool calls, and its report answers it. A finished subagent goes on from // its log with a new run, with the view of now and the effort of its note. func (r *SubagentRuns) Tell(ctx context.Context, name, message string) (string, error) { r.mutex.Lock() run, found := r.running[name] if found { defer r.mutex.Unlock() told, err := run.subagent.Append("user", message) if err != nil { return "", err } run.pending = append(run.pending, told) return "Sent. " + name + " reads it between its tool calls, and its report answers it.", nil } closed := r.closed r.mutex.Unlock() if closed { return "", errSubagentClosed } subagent, err := r.subagents.Get(ctx, name) if err != nil { return "", err } effort, err := r.effort(subagent) if err != nil { return "", err } err = r.memory.Settle(ctx) if err != nil { return "", fmt.Errorf("wait for the summaries: %w", err) } view, err := r.layout.Split(r.memory.ViewLines(nil)) if err != nil { return "", err } _, err = subagent.Append("user", message) if err == nil { err = subagent.Flush(ctx) } if err != nil { return "", err } err = r.start(ctx, &SubagentRun{ subagent: subagent, view: view, effort: effort, }) if err != nil { return "", err } return "Sent. " + name + "'s reply will reach you as a message.", nil } // Stop ends the run of the subagent name and tells if it ran. The chat gets the // note "Stopped by the user: NAME." under the mutex, so the note comes before // the report of the run. func (r *SubagentRuns) Stop(name string) (bool, error) { r.mutex.Lock() defer r.mutex.Unlock() run, found := r.running[name] if !found { return false, nil } err := r.note("Stopped by the user: " + name + ".") if err != nil { return true, err } run.stopped = true run.cancel() return true, nil } // Close ends every run and waits for them. No subagent starts after Close. func (r *SubagentRuns) Close() { r.mutex.Lock() r.closed = true for _, run := range r.running { run.cancel() } r.mutex.Unlock() r.workers.Wait() } // create makes a new subagent with its note, its task, and its work directory, // and starts its run. func (r *SubagentRuns) create(ctx context.Context, note, task string, view []string, effort string) (string, error) { subagent, err := r.subagents.Create(ctx) if err != nil { return "", err } for _, message := range [][2]string{{"note", note}, {"user", task}} { _, err = subagent.Append(message[0], message[1]) if err != nil { return "", err } } err = subagent.Flush(ctx) if err != nil { return "", err } err = os.MkdirAll(subagent.WorkDir(), 0o700) if err != nil { return "", fmt.Errorf("create work directory: %w", err) } return subagent.name, r.start(ctx, &SubagentRun{ subagent: subagent, view: view, effort: effort, }) } // effort returns the effort of subagent from the note at the start of its log: // the effort of the agent, or the effort that the note names. func (r *SubagentRuns) effort(subagent *Subagent) (string, error) { note, err := subagent.First() if err != nil { return "", err } effort, own := strings.CutPrefix(note.Text, subagentNote+subagentNoteEffort) switch { case note.Kind != "note": case own: return effort, nil case note.Text == subagentNote: return r.agent.config.Effort, nil } return "", fmt.Errorf("the log of %s does not start with a subagent note", subagent.name) } // start runs run in the background. Its context keeps the values of ctx, but // only Stop and Close end it. func (r *SubagentRuns) start(ctx context.Context, run *SubagentRun) error { ctx, run.cancel = context.WithCancel(context.WithoutCancel(ctx)) r.mutex.Lock() _, found := r.running[run.subagent.name] if r.closed || found { r.mutex.Unlock() run.cancel() if found { return fmt.Errorf("%s runs already", run.subagent.name) } return errSubagentClosed } r.running[run.subagent.name] = run r.workers.Add(1) r.mutex.Unlock() r.notify(Event{ Kind: "subagent", Text: run.subagent.name, }) go r.run(ctx, run) return nil } // run runs the chains of run and reports its end, unless Close ended it. A // chain follows while messages wait after the final answer of the chain before // it, and no chain failed. A chain that Stop ends gives the reply "stopped". func (r *SubagentRuns) run(ctx context.Context, run *SubagentRun) { defer r.workers.Done() defer run.cancel() var replies []string stopped := false for more := true; more; { reply, err := r.chain(ctx, run) r.mutex.Lock() stopped = run.stopped switch { case err != nil && stopped: reply = "stopped" case err != nil: reply = "failed: " + err.Error() } more = err == nil && ctx.Err() == nil && len(run.pending) > 0 run.pending = nil if !more { delete(r.running, run.subagent.name) } r.mutex.Unlock() replies = append(replies, reply) } if ctx.Err() != nil && !stopped { return } r.report(subagentReport(run.subagent.name, replies), stopped) } // chain runs one request chain of run and returns its final answer. func (r *SubagentRuns) chain(ctx context.Context, run *SubagentRun) (string, error) { instructions, err := r.agent.SubagentPrompt() if err != nil { return "", err } log, err := run.subagent.Show() if err != nil { return "", err } input := make([]any, 0, len(run.view)+2) for _, text := range run.view { input = append(input, modelUserMessage(text)) } input = append(input, modelUserMessage(r.state()), modelUserMessage(log)) chain := &Chain{ client: r.client, tools: &Toolbox{ log: run.subagent, chat: r.memory, subagents: r.subagents, workdir: run.subagent.WorkDir(), }, request: ModelRequest{ Model: r.agent.config.Model, Effort: run.effort, Instructions: instructions, Tools: promptSubagentTools(), Agent: run.subagent.name, }, take: func() []Message { return r.take(run) }, } return chain.Run(ctx, input) } // take returns the messages of Tell that wait for a request of run, and // removes them. func (r *SubagentRuns) take(run *SubagentRun) []Message { r.mutex.Lock() defer r.mutex.Unlock() messages := run.pending run.pending = nil return messages } // SubagentRun is one run of a subagent: the view that its requests get, its // effort, the end of its context, the messages of Tell that wait for a request, // and whether Stop ended it. The mutex of SubagentRuns protects the messages // and the stop. type SubagentRun struct { subagent *Subagent view []string effort string cancel context.CancelFunc pending []Message stopped bool } // subagentReport returns the report of the subagent name with its replies: the // name in brackets, a new line, the replies, and the zoom that gives its whole // chat. func subagentReport(name string, replies []string) string { return "[" + name + "]\n" + strings.Join(replies, "\n\n") + "\n\nFull chat: zoom(\"" + name + "\")" }