git.giacomolli.uk - onechat/blob - subagent_run.go

   1 package main
   2
   3 import (
   4         "context"
   5         "encoding/json"
   6         "errors"
   7         "fmt"
   8         "log/slog"
   9         "maps"
  10         "os"
  11         "path/filepath"
  12         "slices"
  13         "strings"
  14         "sync"
  15         "time"
  16 )
  17
  18 const (
  19         // subagentNote is the first message of the log of a subagent.
  20         subagentNote = "subagent"
  21
  22         // subagentNoteEffort follows subagentNote when the subagent has its own
  23         // effort.
  24         subagentNoteEffort = " at effort "
  25
  26         // subagentWorkFileName is the file of the names of the running
  27         // subagents in the directory of an agent.
  28         subagentWorkFileName = "work.json"
  29 )
  30
  31 // The statuses of the end of a run, in the work event of its report.
  32 const (
  33         subagentFinished = "finished"
  34         subagentStopped  = "stopped"
  35         subagentFailed   = "failed"
  36 )
  37
  38 // errSubagentClosed tells that the runs of the subagents ended with the loop.
  39 var errSubagentClosed = errors.New("the daemon stops, so no subagent starts")
  40
  41 // SubagentRuns runs the subagents of one agent in the background. Each run is a
  42 // goroutine with its own context, which only Stop and Close end. A run is one
  43 // or more request chains. The first request of each chain holds the view of the
  44 // agent at the start of the run, then the state of the turn, then the whole log
  45 // of the subagent. A message of Tell that comes during a chain joins its next
  46 // request after the tool results. One that comes after the final answer starts
  47 // one more chain, which reads the log again. The report of the run goes to
  48 // report: the final answer of each chain, or the error of a failed call. The
  49 // logger gets one line at the end of a run: done, failed with the cause, or
  50 // stopped. Stop ends one run, and its report says that it stopped. At the stop
  51 // of the daemon the runs end with no report.
  52 //
  53 // work.json in the directory of the agent holds the names of the running
  54 // subagents. Each start and each end of a run writes it whole, but Close does
  55 // not, so after a stop of the daemon it names the runs that the stop cut, and
  56 // Resume goes on with them. The logs alone cannot tell this, because a stop
  57 // can cut a run just after its final reply.
  58 //
  59 // Spawn and Tell split the view with the layout of the agent, which has no
  60 // lock. They are tools, so they run in the goroutine of the turns, as each
  61 // split of a turn does.
  62 type SubagentRuns struct {
  63         agent     *Agent
  64         memory    *Memory
  65         subagents *Subagents
  66         layout    *ViewLayout
  67         client    ChainClient
  68         state     func() string
  69         report    func(name, text, status string)
  70         note      func(text string) error
  71         fail      func(err error)
  72         logger    *slog.Logger
  73         notify    func(Event)
  74
  75         mutex   sync.Mutex
  76         running map[string]*SubagentRun
  77         closed  bool
  78         workers sync.WaitGroup
  79 }
  80
  81 // SubagentRun is one run of a subagent: the view that its requests get, its
  82 // effort, the end of its context, the messages of Tell that wait for a request,
  83 // whether Stop ended it, and the time it started. The mutex of SubagentRuns
  84 // protects the messages and the stop.
  85 type SubagentRun struct {
  86         subagent *Subagent
  87         view     []string
  88         effort   string
  89         cancel   context.CancelFunc
  90         pending  []Message
  91         stopped  bool
  92         started  time.Time
  93 }
  94
  95 // SubagentWorkFile is the content of work.json.
  96 type SubagentWorkFile struct {
  97         Running []string `json:"running"`
  98 }
  99
 100 // Spawn starts one subagent for each task and returns their names at once. It
 101 // waits until the view has no pending summary, and gives the view to each
 102 // subagent. A nil effort is the effort of the agent.
 103 func (r *SubagentRuns) Spawn(ctx context.Context, tasks []string, effort *string) (string, error) {
 104         if len(tasks) == 0 {
 105                 return "", errors.New("no tasks")
 106         }
 107
 108         r.mutex.Lock()
 109
 110         closed := r.closed
 111         r.mutex.Unlock()
 112
 113         if closed {
 114                 return "", errSubagentClosed
 115         }
 116
 117         note := subagentNote
 118         runEffort := r.agent.config.Effort
 119         if effort != nil && !slices.Contains(promptEfforts, *effort) {
 120                 return "", fmt.Errorf("no effort %q: one of %s", *effort, strings.Join(promptEfforts, ", "))
 121         }
 122
 123         if effort != nil && *effort != runEffort {
 124                 note += subagentNoteEffort + *effort
 125                 runEffort = *effort
 126         }
 127
 128         err := r.memory.Settle(ctx)
 129         if err != nil {
 130                 return "", fmt.Errorf("wait for the summaries: %w", err)
 131         }
 132
 133         view, err := r.layout.Split(r.memory.ViewLines(nil))
 134         if err != nil {
 135                 return "", err
 136         }
 137
 138         names := make([]string, 0, len(tasks))
 139         for _, task := range tasks {
 140                 name, err := r.create(ctx, note, task, view, runEffort)
 141                 if err != nil && len(names) > 0 {
 142                         return "", fmt.Errorf("started %s, then: %w", strings.Join(names, ", "), err)
 143                 }
 144
 145                 if err != nil {
 146                         return "", err
 147                 }
 148
 149                 names = append(names, name)
 150         }
 151
 152         return "Started " + strings.Join(names, ", ") + ". Each one's report will reach you as a message when it finishes.", nil
 153 }
 154
 155 // Tell sends message to the subagent name. A running subagent reads it between
 156 // its tool calls, and its report answers it. A finished subagent goes on from
 157 // its log with a new run, with the view of now and the effort of its note.
 158 func (r *SubagentRuns) Tell(ctx context.Context, name, message string) (string, error) {
 159         r.mutex.Lock()
 160
 161         run, found := r.running[name]
 162         if found {
 163                 defer r.mutex.Unlock()
 164
 165                 told, err := run.subagent.Append("user", message)
 166                 if err != nil {
 167                         return "", err
 168                 }
 169
 170                 run.pending = append(run.pending, told)
 171
 172                 return "Sent. " + name + " reads it between its tool calls, and its report answers it.", nil
 173         }
 174
 175         closed := r.closed
 176         r.mutex.Unlock()
 177
 178         if closed {
 179                 return "", errSubagentClosed
 180         }
 181
 182         subagent, err := r.subagents.Get(ctx, name)
 183         if err != nil {
 184                 return "", err
 185         }
 186
 187         effort, err := r.effort(subagent)
 188         if err != nil {
 189                 return "", err
 190         }
 191
 192         err = r.memory.Settle(ctx)
 193         if err != nil {
 194                 return "", fmt.Errorf("wait for the summaries: %w", err)
 195         }
 196
 197         view, err := r.layout.Split(r.memory.ViewLines(nil))
 198         if err != nil {
 199                 return "", err
 200         }
 201
 202         _, err = subagent.Append("user", message)
 203         if err == nil {
 204                 err = subagent.Flush(ctx)
 205         }
 206
 207         if err != nil {
 208                 return "", err
 209         }
 210
 211         err = r.start(ctx, &SubagentRun{
 212                 subagent: subagent,
 213                 view:     view,
 214                 effort:   effort,
 215         })
 216         if err != nil {
 217                 return "", err
 218         }
 219
 220         return "Sent. " + name + "'s reply will reach you as a message.", nil
 221 }
 222
 223 // Stop ends the run of the subagent name and tells if it ran. The chat gets the
 224 // note "Stopped by the user: NAME." under the mutex, so the note comes before
 225 // the report of the run.
 226 func (r *SubagentRuns) Stop(name string) (bool, error) {
 227         r.mutex.Lock()
 228         defer r.mutex.Unlock()
 229
 230         run, found := r.running[name]
 231         if !found {
 232                 return false, nil
 233         }
 234
 235         err := r.note("Stopped by the user: " + name + ".")
 236         if err != nil {
 237                 return true, err
 238         }
 239
 240         run.stopped = true
 241         run.cancel()
 242
 243         return true, nil
 244 }
 245
 246 // Resume goes on with the runs that a stop of the daemon cut, as work.json
 247 // names them. The chat gets the note "The daemon restarted, cutting NAMES;
 248 // nothing was lost: go on.", and each cut subagent gets the same text as a
 249 // message of Tell. A subagent that cannot go on gets a failed report.
 250 func (r *SubagentRuns) Resume(ctx context.Context) error {
 251         names, err := r.load()
 252         if err != nil || len(names) == 0 {
 253                 return err
 254         }
 255
 256         text := "The daemon restarted, cutting " + strings.Join(names, ", ") + "; nothing was lost: go on."
 257         err = r.note(text)
 258         if err != nil {
 259                 return err
 260         }
 261
 262         for _, name := range names {
 263                 _, err = r.Tell(ctx, name, text)
 264                 if err != nil {
 265                         r.logger.Error("subagent lost at restart", "name", name, "err", err)
 266                         r.report(name, subagentReport(name, []string{"failed: " + err.Error()}), subagentFailed)
 267                 }
 268         }
 269
 270         // A subagent that cannot go on does not run, so work.json no longer
 271         // names it, and the next start does not try it again.
 272         r.mutex.Lock()
 273         defer r.mutex.Unlock()
 274
 275         return r.save()
 276 }
 277
 278 // Snapshot locks the run state, memory, and subagent logs while snapshot reads
 279 // the agent files. The lock order agrees with Stop, which logs under the run
 280 // lock.
 281 func (r *SubagentRuns) Snapshot(ctx context.Context, snapshot func() error) error {
 282         r.mutex.Lock()
 283         defer r.mutex.Unlock()
 284
 285         return r.memory.Snapshot(ctx, func() error {
 286                 return r.subagents.Snapshot(ctx, snapshot)
 287         })
 288 }
 289
 290 // Close ends every run and waits for them. No subagent starts after Close.
 291 func (r *SubagentRuns) Close() {
 292         r.mutex.Lock()
 293
 294         r.closed = true
 295         for _, run := range r.running {
 296                 run.cancel()
 297         }
 298
 299         r.mutex.Unlock()
 300
 301         r.workers.Wait()
 302 }
 303
 304 // create makes a new subagent with its note, its task, and its work directory,
 305 // and starts its run.
 306 func (r *SubagentRuns) create(ctx context.Context, note, task string, view []string, effort string) (string, error) {
 307         subagent, err := r.subagents.Create(ctx)
 308         if err != nil {
 309                 return "", err
 310         }
 311
 312         for _, message := range [][2]string{{"note", note}, {"user", task}} {
 313                 _, err = subagent.Append(message[0], message[1])
 314                 if err != nil {
 315                         return "", err
 316                 }
 317         }
 318
 319         err = subagent.Flush(ctx)
 320         if err != nil {
 321                 return "", err
 322         }
 323
 324         err = os.MkdirAll(subagent.WorkDir(), 0o700)
 325         if err != nil {
 326                 return "", fmt.Errorf("create work directory: %w", err)
 327         }
 328
 329         return subagent.name, r.start(ctx, &SubagentRun{
 330                 subagent: subagent,
 331                 view:     view,
 332                 effort:   effort,
 333         })
 334 }
 335
 336 // effort returns the effort of subagent from the note at the start of its log:
 337 // the effort of the agent, or the effort that the note names.
 338 func (r *SubagentRuns) effort(subagent *Subagent) (string, error) {
 339         note, err := subagent.First()
 340         if err != nil {
 341                 return "", err
 342         }
 343
 344         effort, own := strings.CutPrefix(note.Text, subagentNote+subagentNoteEffort)
 345         switch {
 346         case note.Kind != "note":
 347         case own:
 348                 return effort, nil
 349         case note.Text == subagentNote:
 350                 return r.agent.config.Effort, nil
 351         }
 352
 353         return "", fmt.Errorf("the log of %s does not start with a subagent note", subagent.name)
 354 }
 355
 356 // start runs run in the background and logs its start. Its context keeps the
 357 // values of ctx, but only Stop and Close end it.
 358 func (r *SubagentRuns) start(ctx context.Context, run *SubagentRun) error {
 359         ctx, run.cancel = context.WithCancel(context.WithoutCancel(ctx))
 360
 361         r.mutex.Lock()
 362
 363         _, found := r.running[run.subagent.name]
 364         if r.closed || found {
 365                 r.mutex.Unlock()
 366                 run.cancel()
 367
 368                 if found {
 369                         return fmt.Errorf("%s runs already", run.subagent.name)
 370                 }
 371
 372                 return errSubagentClosed
 373         }
 374
 375         r.running[run.subagent.name] = run
 376         err := r.save()
 377         if err != nil {
 378                 delete(r.running, run.subagent.name)
 379                 r.mutex.Unlock()
 380                 run.cancel()
 381
 382                 return err
 383         }
 384
 385         r.workers.Add(1)
 386         r.mutex.Unlock()
 387
 388         run.started = r.subagents.clock()
 389         r.logger.Info("subagent started", "name", run.subagent.name)
 390         r.notify(Event{
 391                 Kind: "subagent",
 392                 Text: run.subagent.name,
 393         })
 394
 395         go r.run(ctx, run)
 396
 397         return nil
 398 }
 399
 400 // load reads the names of work.json. A missing file names none.
 401 func (r *SubagentRuns) load() ([]string, error) {
 402         data, err := os.ReadFile(r.workPath())
 403         if errors.Is(err, os.ErrNotExist) {
 404                 return nil, nil
 405         }
 406
 407         if err != nil {
 408                 return nil, fmt.Errorf("read running subagents: %w", err)
 409         }
 410
 411         var file SubagentWorkFile
 412
 413         err = json.Unmarshal(data, &file)
 414         if err != nil {
 415                 return nil, fmt.Errorf("decode running subagents: %w", err)
 416         }
 417
 418         return file.Running, nil
 419 }
 420
 421 // save writes the names of the running subagents to work.json. The caller
 422 // holds the mutex.
 423 func (r *SubagentRuns) save() error {
 424         file := SubagentWorkFile{
 425                 Running: append([]string{}, slices.Sorted(maps.Keys(r.running))...),
 426         }
 427
 428         data, err := json.Marshal(file)
 429         if err != nil {
 430                 return fmt.Errorf("encode running subagents: %w", err)
 431         }
 432
 433         err = writeFileAtomic(r.workPath(), append(data, '\n'))
 434         if err != nil {
 435                 return fmt.Errorf("save running subagents: %w", err)
 436         }
 437
 438         return nil
 439 }
 440
 441 func (r *SubagentRuns) workPath() string {
 442         return filepath.Join(r.agent.dir, subagentWorkFileName)
 443 }
 444
 445 // run runs the chains of run and reports and logs its end with the length of
 446 // the run, unless Close ended it. A chain follows while messages wait after the
 447 // final answer of the chain before it, and no chain failed. A chain that Stop
 448 // ends gives the reply "stopped".
 449 func (r *SubagentRuns) run(ctx context.Context, run *SubagentRun) {
 450         defer r.workers.Done()
 451         defer run.cancel()
 452
 453         var (
 454                 replies []string
 455                 failure error
 456         )
 457
 458         stopped := false
 459         status := subagentFinished
 460         for more := true; more; {
 461                 reply, err := r.chain(ctx, run)
 462
 463                 r.mutex.Lock()
 464
 465                 stopped = run.stopped
 466                 switch {
 467                 case err != nil && stopped:
 468                         reply = "stopped"
 469                 case err != nil:
 470                         reply = "failed: " + err.Error()
 471                         status = subagentFailed
 472                         failure = err
 473                 }
 474
 475                 more = err == nil && ctx.Err() == nil && len(run.pending) > 0
 476                 run.pending = nil
 477
 478                 var saveErr error
 479
 480                 if !more {
 481                         delete(r.running, run.subagent.name)
 482
 483                         if !r.closed {
 484                                 saveErr = r.save()
 485                         }
 486                 }
 487
 488                 r.mutex.Unlock()
 489
 490                 if saveErr != nil {
 491                         r.fail(saveErr)
 492                 }
 493
 494                 replies = append(replies, reply)
 495         }
 496
 497         if ctx.Err() != nil && !stopped {
 498                 return
 499         }
 500
 501         if stopped {
 502                 status = subagentStopped
 503         }
 504
 505         length := r.subagents.clock().Sub(run.started)
 506         switch status {
 507         case subagentStopped:
 508                 r.logger.Info("subagent stopped", "name", run.subagent.name, "after", length)
 509         case subagentFailed:
 510                 r.logger.Error("subagent failed", "name", run.subagent.name, "after", length, "err", failure)
 511         default:
 512                 r.logger.Info("subagent done", "name", run.subagent.name, "after", length)
 513         }
 514
 515         r.report(run.subagent.name, subagentReport(run.subagent.name, replies), status)
 516 }
 517
 518 // chain runs one request chain of run and returns its final answer.
 519 func (r *SubagentRuns) chain(ctx context.Context, run *SubagentRun) (string, error) {
 520         instructions, err := r.agent.SubagentPrompt()
 521         if err != nil {
 522                 return "", err
 523         }
 524
 525         log, err := run.subagent.Show()
 526         if err != nil {
 527                 return "", err
 528         }
 529
 530         input := make([]any, 0, len(run.view)+2)
 531         for _, text := range run.view {
 532                 input = append(input, modelUserMessage(text))
 533         }
 534
 535         input = append(input, modelUserMessage(r.state()), modelUserMessage(log))
 536         chain := &Chain{
 537                 client: r.client,
 538                 images: r.agent.Images(),
 539                 tools: &Toolbox{
 540                         log:       run.subagent,
 541                         chat:      r.memory,
 542                         subagents: r.subagents,
 543                         workdir:   run.subagent.WorkDir(),
 544                         images:    r.agent.Images(),
 545                 },
 546                 request: ModelRequest{
 547                         Model:        r.agent.config.Model,
 548                         Effort:       run.effort,
 549                         Instructions: instructions,
 550                         Tools:        promptSubagentTools(),
 551                         Agent:        run.subagent.name,
 552                 },
 553                 take: func() []Message {
 554                         return r.take(run)
 555                 },
 556         }
 557
 558         return chain.Run(ctx, input)
 559 }
 560
 561 // take returns the messages of Tell that wait for a request of run, and
 562 // removes them.
 563 func (r *SubagentRuns) take(run *SubagentRun) []Message {
 564         r.mutex.Lock()
 565         defer r.mutex.Unlock()
 566
 567         messages := run.pending
 568         run.pending = nil
 569
 570         return messages
 571 }
 572
 573 // subagentReport returns the report of the subagent name with its replies: the
 574 // name in brackets, a new line, the replies, and the zoom that gives its whole
 575 // chat.
 576 func subagentReport(name string, replies []string) string {
 577         return "[" + name + "]\n" + strings.Join(replies, "\n\n") + "\n\nFull chat: zoom(\"" + name + "\")"
 578 }