byre/internal/agents/guidance.go

package agents

import (
	"context"
	"encoding/json"
	"fmt"
	"regexp"

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

const guidance = `You are running inside byre. The human reads your work in byre's web UI, not a terminal.
- Ask every question with byre's ask_human tool, never in prose.
- 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 blocking 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.`

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, question, why_blocked), " +
	"then end your turn with a short summary."

var (
	fencedCode   = regexp.MustCompile("(?s)```.*?```")
	inlineCode   = regexp.MustCompile("`[^`\n]*`")
	quoted       = regexp.MustCompile(`"[^"\n]*"|“[^”\n]*”`)
	blockquote   = regexp.MustCompile(`(?m)^\s*>.*$`)
	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, "")
	return endsQuestion.MatchString(text)
}

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
		}

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

func (m *Manager) takeBounce(l *live, final string) bool {
	m.mu.Lock()
	defer m.mu.Unlock()
	if l.asked || l.bounced || l.compacting || !asksQuestion(final) {
		return false
	}
	l.bounced = true
	return true
}

func (m *Manager) taskGuidance(ctx context.Context, task api.Task) (string, error) {
	g := guidance + fmt.Sprintf("\n- This task's ports are %d to %d; $PORT holds the first. Run dev servers and anything else that listens on these, so parallel tasks don't collide, and listen on 127.0.0.1. 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.",
		task.PortBase, task.PortBase+store.PortBlock-1)
	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.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 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
	}
}