byre/internal/agents/guidance.go

package agents

import (
	"context"
	"encoding/json"
	"fmt"
	"regexp"
	"strings"
	"unicode/utf8"

	"g.fc.run/ai/byre/internal/api"
	"g.fc.run/ai/byre/internal/claude"
	"g.fc.run/ai/byre/internal/store"
	"g.fc.run/ai/byre/internal/todo"
)

const guidance = `You are running inside byre. The human reads your work in byre's app, not a terminal.
- Ask every question with byre's ask_human tool, never in prose. Anything that leaves you waiting on the human's pick or go-ahead is a question, however it is worded and with or without a question mark: options they asked you to suggest, a proposal waiting for approval, "tell me which you want".
- End every turn with a short final message for the human: what you did, anything you departed from in the plan or instructions, risks, and what's next. byre shows it as the turn's summary at the end of the transcript. State every departure from the plan.
- A turn that asks a question has no summary; put everything the human needs in the question's context.
- In that final message and in ask_human context, put long supporting detail (logs, full lists, data) in collapsed sections the human expands on demand: a line <details><summary>Title</summary>, the Markdown content, then a line </details>.
- Don't commit. byre commits everything in the worktree at the end of each turn, using the turn's final message.
- Don't push, don't switch or touch other branches, and don't run git maintenance (gc, prune, worktree prune). byre handles merging and pushing.
- TODO.md at the repo root is the project's list of work for byre; its format is the read_knowledge article todo-file.`

const proseQuestionNudge = "Your final message asks the human something in prose. Ask it with byre's ask_human tool " +
	"(context with the choices inline as `- ( ) choice` / `- (*) recommended` or `- [ ] choice` / `- [x] recommended` list items, and question), " +
	"then end your turn without a summary; put everything the human needs in the question's context."

var (
	fencedCode   = regexp.MustCompile("(?s)```.*?```")
	inlineCode   = regexp.MustCompile("`[^`\n]*`")
	quoted       = regexp.MustCompile(`"[^"\n]*"|“[^”\n]*”`)
	blockquote   = regexp.MustCompile(`(?m)^\s*>.*$`)
	tableRow     = regexp.MustCompile(`(?m)^\s*\|.*$`)
	details      = regexp.MustCompile(`(?s)<details>.*?</details>`)
	paragraphs   = regexp.MustCompile(`\n\s*\n`)
	endsQuestion = regexp.MustCompile(`\?[*_)\]]*(\s|$)`)
)

func asksQuestion(text string) bool {
	text = fencedCode.ReplaceAllString(text, "")
	text = inlineCode.ReplaceAllString(text, "")
	text = quoted.ReplaceAllString(text, "")
	text = blockquote.ReplaceAllString(text, "")
	text = tableRow.ReplaceAllString(text, "")
	text = details.ReplaceAllString(text, "")
	paras := paragraphs.Split(strings.TrimSpace(text), -1)
	return endsQuestion.MatchString(paras[len(paras)-1])
}

func (m *Manager) bounceProseQuestion(l *live) claude.HookFunc {
	return func(ctx context.Context, input json.RawMessage) (map[string]any, error) {
		in := struct {
			LastAssistantMessage string `json:"last_assistant_message"`
		}{}
		err := json.Unmarshal(input, &in)
		if err != nil {
			return nil, err
		}

		bounce, err := m.takeBounce(ctx, l, in.LastAssistantMessage)
		if err != nil || !bounce {
			return map[string]any{}, err
		}
		return map[string]any{"decision": "block", "reason": proseQuestionNudge}, nil
	}
}

func (m *Manager) takeBounce(ctx context.Context, l *live, final string) (bool, error) {
	if !asksQuestion(final) {
		return false, nil
	}
	first, err := m.store.FirstPrompt(ctx, l.taskID)
	if err != nil {
		return false, err
	}
	if strings.Contains(first, discussPrompt) {
		return false, nil
	}
	open, err := m.store.ListInbox(ctx, store.InboxFilter{TaskID: l.taskID, State: api.Open})
	if err != nil {
		return false, err
	}
	if len(open) > 0 {
		return false, nil
	}

	m.mu.Lock()
	if l.asked || l.bounced || l.compacting {
		m.mu.Unlock()
		return false, nil
	}
	l.bounced = true
	m.mu.Unlock()
	err = m.emit(ctx, l, "byre", "user.message", map[string]any{"text": proseQuestionNudge, "mid_turn": true, "bounce": true})
	return err == nil, err
}

func (m *Manager) taskGuidance(ctx context.Context, task api.Task) (string, error) {
	g := guidance + "\n- Run dev servers and anything else that listens on 127.0.0.1, on any free port. Other tasks' servers run on this Mac too, so when a port is taken, use another. To show the human a running server, call byre's expose_port tool." +
		"\n- This worktree starts with only what git tracks. Before other work in a new worktree, do any setup the project's AGENTS.md describes."
	if task.Title == "" {
		g += "\n- This task has no title yet. First thing, before any other work, call set_titles with a very short, distinct, to-the-point task title (two to four words) and a merge commit title that describes the work, and call it again whenever the work moves on."
	} else {
		g += fmt.Sprintf("\n- This task's title is %q. First thing, call set_titles with a merge commit title that describes the work, and a task title that is very short (two to four words), distinct and to the point (this one, if it already is), and call it again whenever the work moves on.", task.Title)
	}
	if task.TodoItem != nil {
		g += fmt.Sprintf("\n- This task was started from the item %q in %s at the repo root. When the work is done, remove that item from %s in this worktree, so the removal lands in the same merge as the work.",
			*task.TodoItem, todo.File, todo.File)
	}
	if task.ParentTaskId != nil && task.WorkflowStage == nil {
		parent, err := m.store.GetTask(ctx, *task.ParentTaskId)
		if err != nil {
			return "", err
		}
		g += subtaskGuidance(parent)
	}
	if task.ForkedFrom == nil {
		return g, nil
	}
	src, err := m.store.GetTask(ctx, *task.ForkedFrom)
	if err != nil {
		return "", err
	}
	return g + forkGuidance(task, src), nil
}

func longTitleGuidance(task api.Task) string {
	n := utf8.RuneCountInString(task.MergeTitle)
	if n <= maxMergeTitle {
		return ""
	}
	return fmt.Sprintf("\n- This task's merge commit title, %q, is %d characters, over the %d allowed, so Merge will refuse it. Early in your first turn, call set_titles with a one-line merge title of at most %d characters that describes the work.",
		task.MergeTitle, n, maxMergeTitle, maxMergeTitle)
}

func subtaskGuidance(parent api.Task) string {
	return fmt.Sprintf("\n- This task is a subtask of byre task %q (%s), whose agent created it and manages it. Your final message at the end of each turn is sent to that agent, which may answer with more instructions. "+
		"Your work reaches %s's branch or the default branch when the subtask is merged.",
		parent.Title, parent.Id, parent.Id)
}

func forkGuidance(task, src api.Task) string {
	return fmt.Sprintf("\n- This conversation was forked from byre task %q at its snapshot %d, into a task of its own: branch %s, worktree %s, which held that snapshot's files when the fork was made. "+
		"Everything before the fork happened in %s, which belongs to the other task: from now on read and change files only in %s, never in the other worktree, and use paths under it.",
		src.Title, *task.ForkedAt, task.Branch, task.WorktreePath, src.WorktreePath, task.WorktreePath)
}

func remindGuidance(text string) claude.HookFunc {
	return func(ctx context.Context, input json.RawMessage) (map[string]any, error) {
		return map[string]any{
			"hookSpecificOutput": map[string]any{
				"hookEventName":     "UserPromptSubmit",
				"additionalContext": text,
			},
		}, nil
	}
}