byre/internal/agents/inbox.go

package agents

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log/slog"
	"slices"
	"strings"
	"time"

	"g.fc.run/misc/byre/internal/api"
	"g.fc.run/misc/byre/internal/mcp"
	"g.fc.run/misc/byre/internal/store"
)

var attachmentKinds = []api.AttachmentKind{
	api.AttachmentKindFile, api.AttachmentKindDiff, api.AttachmentKindImage, api.AttachmentKindDiagram,
	api.AttachmentKindTask, api.AttachmentKindSnapshot, api.AttachmentKindUrl,
}

type askArgs struct {
	Context           string           `json:"context"`
	Question          string           `json:"question"`
	WhyBlocked        string           `json:"why_blocked"`
	Options           []string         `json:"options"`
	RecommendedOption string           `json:"recommended_option"`
	Attachments       []api.Attachment `json:"attachments"`
	Blocking          *bool            `json:"blocking"`
	ThreadID          string           `json:"thread_id"`
}

func (m *Manager) askTool(l *live) mcp.Tool {
	return mcp.Tool{
		Name: "ask_human",
		Description: "Ask the human a question through their inbox. Use this for every question; never ask in plain prose. " +
			"The human answers from their inbox without having read your transcript, so every question must stand on its own: " +
			"put the background they need in context. " +
			"Offer concrete options and recommend one. If blocking is true, end your turn after asking; " +
			"the answer arrives as your next message. If blocking is false, continue with work that doesn't depend on the answer. " +
			"Ask several questions in one turn by calling this once per question; they are answered together. " +
			"To answer a follow-up question from the human, call this again with the thread_id they gave you.",
		InputSchema: json.RawMessage(`{
			"type": "object",
			"properties": {
				"context": {"type": "string", "description": "Everything the human needs to answer well without reading your transcript: what you are working on, what you found, the relevant facts and data, and what each option would concretely do. Several paragraphs is normal. Markdown is rendered."},
				"question": {"type": "string", "description": "The question itself, in one or two sentences. Markdown is rendered."},
				"why_blocked": {"type": "string", "description": "What you can't do until this is answered, and why you can't decide it yourself."},
				"options": {"type": "array", "items": {"type": "string"}, "minItems": 2},
				"recommended_option": {"type": "string", "description": "One of options."},
				"attachments": {"type": "array", "items": {
					"type": "object",
					"properties": {
						"kind": {"type": "string", "enum": ["file", "diff", "image", "diagram", "task", "snapshot", "url"]},
						"path": {"type": "string"},
						"start_line": {"type": "integer"},
						"end_line": {"type": "integer"},
						"ref": {"type": "string"},
						"url": {"type": "string"},
						"mermaid": {"type": "string"},
						"task_id": {"type": "string"},
						"snapshot_id": {"type": "string"},
						"caption": {"type": "string"}
					},
					"required": ["kind"]
				}},
				"blocking": {"type": "boolean"},
				"thread_id": {"type": "string"}
			},
			"required": ["context", "question", "why_blocked", "options", "recommended_option", "blocking"]
		}`),
		Handler: func(ctx context.Context, raw json.RawMessage) (string, error) {
			return m.ask(ctx, l, raw)
		},
	}
}

func (m *Manager) ask(ctx context.Context, l *live, raw json.RawMessage) (string, error) {
	args := askArgs{}
	err := json.Unmarshal(raw, &args)
	if err != nil {
		return "", fmt.Errorf("malformed ask_human call: %w", err)
	}

	err = m.validateAsk(ctx, l, args)
	if err != nil {
		return "", err
	}

	id := store.NewID()
	thread := args.ThreadID
	if thread == "" {
		thread = id
	}

	priority := api.Fyi
	if *args.Blocking {
		priority = api.Blocked
	}

	attachments := args.Attachments
	if attachments == nil {
		attachments = []api.Attachment{}
	}

	payload := map[string]any{
		"context":            args.Context,
		"question":           args.Question,
		"why_blocked":        args.WhyBlocked,
		"options":            args.Options,
		"recommended_option": args.RecommendedOption,
		"attachments":        attachments,
	}

	err = m.store.CreateInboxItem(ctx, m.newItem(l, id, thread, api.Question, priority, *args.Blocking, store.ToPayload(payload)))
	if err != nil {
		return "", err
	}

	m.mu.Lock()
	l.asked = true
	m.mu.Unlock()

	if *args.Blocking {
		return fmt.Sprintf("Question %s filed in the human's inbox. It is blocking: end your turn now. The answer will arrive as your next message.", id), nil
	}
	return fmt.Sprintf("Question %s filed in the human's inbox. Continue with work that doesn't depend on it; the answer will arrive as a later message.", id), nil
}

func (m *Manager) validateAsk(ctx context.Context, l *live, args askArgs) error {
	problems := []string{}

	if strings.TrimSpace(args.Context) == "" {
		problems = append(problems, "context is empty: give the background the human needs to answer without reading your transcript")
	}
	if strings.TrimSpace(args.Question) == "" {
		problems = append(problems, "question is empty")
	}
	if strings.TrimSpace(args.WhyBlocked) == "" {
		problems = append(problems, "why_blocked is empty: say what you can't do until this is answered and why you can't decide it yourself")
	}
	if len(args.Options) < 2 {
		problems = append(problems, "options needs at least two concrete choices")
	}
	if !slices.Contains(args.Options, args.RecommendedOption) {
		problems = append(problems, "recommended_option must be exactly one of options")
	}
	if args.Blocking == nil {
		problems = append(problems, "blocking is required")
	}
	for i, a := range args.Attachments {
		if !slices.Contains(attachmentKinds, a.Kind) {
			problems = append(problems, fmt.Sprintf("attachments[%d].kind %q is not one of %v", i, a.Kind, attachmentKinds))
		}
	}

	if args.ThreadID != "" {
		item, err := m.store.GetInboxItem(ctx, args.ThreadID)
		switch {
		case errors.Is(err, store.ErrNotFound):
			problems = append(problems, fmt.Sprintf("thread_id %s does not exist", args.ThreadID))
		case err != nil:
			return err
		case item.AgentSessionId != l.id:
			problems = append(problems, fmt.Sprintf("thread_id %s belongs to another session", args.ThreadID))
		}
	}

	if len(problems) > 0 {
		return fmt.Errorf("ask_human rejected, nothing was filed. Fix and call again: %s", strings.Join(problems, "; "))
	}
	return nil
}

func (m *Manager) fileSummary(l *live, text string) string {
	id := store.NewID()
	err := m.store.CreateInboxItem(context.Background(), m.newItem(l, id, id, api.Report, api.Fyi, false, map[string]any{"text": text}))
	if err != nil {
		slog.Error("file turn summary", "session", l.id, "err", err)
		return ""
	}
	return id
}

func (m *Manager) fileError(l *live, msg string) {
	id := store.NewID()
	err := m.store.CreateInboxItem(context.Background(), m.newItem(l, id, id, api.SessionError, api.Blocked, true, map[string]any{"error": msg}))
	if err != nil {
		slog.Error("file session error", "session", l.id, "err", err)
	}
}

func (m *Manager) fileRateLimited(l *live, info map[string]any, failure string) {
	id := store.NewID()
	payload := map[string]any{"vendor": string(l.vendor), "rate_limit": info, "error": failure}
	err := m.store.CreateInboxItem(context.Background(), m.newItem(l, id, id, api.RateLimited, api.Blocked, true, payload))
	if err != nil {
		slog.Error("file rate limit", "session", l.id, "err", err)
	}
}

func (m *Manager) newItem(l *live, id, thread string, kind api.InboxItemKind, priority api.InboxItemPriority, blocking bool, payload map[string]any) api.InboxItem {
	return api.InboxItem{
		Id:             id,
		ProjectId:      l.projectID,
		TaskId:         l.taskID,
		AgentSessionId: l.id,
		ThreadId:       thread,
		Kind:           kind,
		Priority:       priority,
		Blocking:       blocking,
		Payload:        payload,
		State:          api.Open,
		CreatedAt:      time.Now().UTC(),
		Responses:      []api.InboxResponse{},
	}
}

func (m *Manager) Deliver(ctx context.Context, sessionID string) error {
	m.deliverMu.Lock()
	defer m.deliverMu.Unlock()

	sess, err := m.store.GetSession(ctx, sessionID)
	if err != nil {
		return err
	}
	if sess.State != api.AgentSessionStateIdle {
		return nil
	}

	waiting, err := m.store.AwaitingHuman(ctx, sessionID)
	if err != nil {
		return err
	}
	if waiting > 0 {
		return nil
	}

	pending, err := m.store.Undelivered(ctx, sessionID)
	if err != nil {
		return err
	}
	if len(pending) == 0 {
		return nil
	}

	task, err := m.store.GetTask(ctx, sess.TaskId)
	if err != nil {
		return err
	}

	_, err = m.turn(ctx, sess, task, pending[0].Response.User, deliveryMessage(pending))
	if errors.Is(err, ErrConflict) {
		return nil
	}
	if err != nil {
		return err
	}

	ids := []string{}
	for _, p := range pending {
		ids = append(ids, p.Response.Id)
	}
	return m.store.MarkDelivered(ctx, ids)
}

func deliveryMessage(pending []store.Pending) string {
	b := &strings.Builder{}
	b.WriteString("Responses from your inbox:\n")

	for _, p := range pending {
		r := p.Response
		b.WriteString("\n")

		switch p.Item.Kind {
		case api.Question:
			fmt.Fprintf(b, "Your question %s: %s\n", p.Item.Id, p.Item.Payload["question"])
		case api.SessionError:
			fmt.Fprintf(b, "Your error %s: %s\n", p.Item.Id, p.Item.Payload["error"])
		case api.RateLimited:
			fmt.Fprintf(b, "Your rate-limited turn %s: %s\n", p.Item.Id, p.Item.Payload["error"])
		}

		switch r.Type {
		case api.Option:
			fmt.Fprintf(b, "%s chose: %s\n", r.User, *r.Option)
		case api.Other:
			if p.Item.Kind == api.Question {
				fmt.Fprintf(b, "%s answered (none of your options): %s\n", r.User, *r.Text)
				fmt.Fprintf(b, "If this asks you something back, answer by calling ask_human with thread_id %q.\n", p.Item.ThreadId)
			} else {
				fmt.Fprintf(b, "%s replied: %s\n", r.User, *r.Text)
			}
		}

		for _, a := range r.Attachments {
			j, err := json.Marshal(a)
			if err != nil {
				continue
			}
			fmt.Fprintf(b, "Attachment: %s\n", j)
		}
	}

	return b.String()
}