diff --git a/src/agent/tools/handoff.ts b/src/agent/tools/handoff.ts index cdaafe39d..4a08c06ba 100644 --- a/src/agent/tools/handoff.ts +++ b/src/agent/tools/handoff.ts @@ -8,6 +8,7 @@ import type { ProgressEmitter } from '../progress'; import { analytics } from '@utils/analytics'; import { logToFile } from '@utils/debug'; import { runtimeEnv } from '@env'; +import { NEEDS_ATTENTION_HEADING } from '@utils/needs-attention'; import { randomBytes } from 'node:crypto'; import { closeSync, @@ -38,6 +39,7 @@ export const PUBLISH_HANDOFF_TOOL_NAME = 'publish_handoff'; export const PUBLISH_HANDOFF_DESCRIPTION = 'Publish the handoff document — the full markdown report of what the whole run did — to the wizard session. ' + 'A run publishes once: call it only when your own instructions ask you to write that report, passing the complete report as `content`, and never write the report to a file yourself. ' + + `When anything is left for the user to do, open the report, right under the H1, with a \`> ⚠️ **${NEEDS_ATTENTION_HEADING}**\` block quote, one \`> - \` bullet per item. ` + 'It is not how you report your own work — in a run made of several tasks each step finishes with complete_task, and a step that was not asked for the run report leaves this one uncalled, because the section it owns travels in its handoff.'; /** Appended for a task agent: the reminder lands as it decides it has finished. */ diff --git a/src/shared/local-dev.ts b/src/shared/local-dev.ts index 0e13e4df0..032dc5762 100644 --- a/src/shared/local-dev.ts +++ b/src/shared/local-dev.ts @@ -8,7 +8,9 @@ * `--local` here. */ -export const CONTEXT_MILL_LOCAL_URL = 'http://localhost:8765'; +// `CONTEXT_MILL_URL` points `--local-context-mill` at another port. +export const CONTEXT_MILL_LOCAL_URL = + process.env.CONTEXT_MILL_URL || 'http://localhost:8765'; export const MCP_LOCAL_URL = 'http://localhost:8787/mcp'; /** Pins the API, app, OAuth, and the LLM gateway derived from them. */ export const POSTHOG_LOCAL_URL = 'http://localhost:8010'; diff --git a/src/shared/utils/__tests__/needs-attention.test.ts b/src/shared/utils/__tests__/needs-attention.test.ts new file mode 100644 index 000000000..d62cfe570 --- /dev/null +++ b/src/shared/utils/__tests__/needs-attention.test.ts @@ -0,0 +1,56 @@ +import { readNeedsAttention } from '@utils/needs-attention'; + +const report = (block: string) => + `# Error tracking report\n\n${block}\n\n## What you still need to do\n\n1. Something\n`; + +describe('readNeedsAttention', () => { + it('returns each bullet of the warning block', () => { + const markdown = report( + [ + '> ⚠️ **Needs your attention**', + '> - Load `.env` in the app, or set `POSTHOG_API_KEY` in its environment.', + '> * Add the `POSTHOG_CLI_API_KEY` CI secret.', + ].join('\n'), + ); + expect(readNeedsAttention(markdown)).toEqual([ + 'Load `.env` in the app, or set `POSTHOG_API_KEY` in its environment.', + 'Add the `POSTHOG_CLI_API_KEY` CI secret.', + ]); + }); + + it('accepts the warning sign without its emoji variant selector', () => { + const markdown = report('> ⚠ **Needs your attention**\n> - One thing'); + expect(readNeedsAttention(markdown)).toEqual(['One thing']); + }); + + it('ignores other quote blocks and reports without the block', () => { + expect(readNeedsAttention(report('> - Just a quote'))).toEqual([]); + expect(readNeedsAttention('# Report\n\nAll done.')).toEqual([]); + }); + + it('strips terminal control characters from items', () => { + const markdown = report( + '> ⚠️ **Needs your attention**\n> - Do \x1b[31mthis\x1b]52;c;ZXZpbA==\x07 now\x9b2J', + ); + expect(readNeedsAttention(markdown)).toEqual([ + 'Do [31mthis]52;c;ZXZpbA== now2J', + ]); + }); + + it('keeps the tail of a bullet wrapped onto the next quoted line', () => { + const markdown = report( + [ + '> ⚠️ **Needs your attention**', + '> - Set `POSTHOG_API_KEY` in your deploy', + '> environment before the next release.', + '> - Add the CI secret.', + '>', + '> A closing note, not part of any item.', + ].join('\n'), + ); + expect(readNeedsAttention(markdown)).toEqual([ + 'Set `POSTHOG_API_KEY` in your deploy environment before the next release.', + 'Add the CI secret.', + ]); + }); +}); diff --git a/src/shared/utils/needs-attention.ts b/src/shared/utils/needs-attention.ts new file mode 100644 index 000000000..786b58e2c --- /dev/null +++ b/src/shared/utils/needs-attention.ts @@ -0,0 +1,34 @@ +/** The heading of the warning block a handoff report opens with when work is left. */ +export const NEEDS_ATTENTION_HEADING = 'Needs your attention'; + +const BLOCK_START = new RegExp(`^\\s*>\\s*⚠.*${NEEDS_ATTENTION_HEADING}`); + +// eslint-disable-next-line no-control-regex +const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g; + +/** The bullets of a report's `> ⚠️ **Needs your attention**` block, or none. */ +export function readNeedsAttention(markdown: string): string[] { + const lines = markdown.split('\n'); + const start = lines.findIndex((line) => BLOCK_START.test(line)); + if (start === -1) return []; + const items: string[] = []; + // Items are agent-written and printed raw to the terminal: drop escapes. + const clean = (text: string) => text.replace(CONTROL_CHARS, '').trim(); + let open = false; + for (const line of lines.slice(start + 1)) { + const quoted = /^\s*>\s?(.*)$/.exec(line); + if (!quoted) break; + const bullet = /^\s*(?:[-*]|\d+\.)\s+(.*\S)/.exec(quoted[1]); + const text = clean(bullet ? bullet[1] : quoted[1]); + if (bullet) { + open = text !== ''; + if (open) items.push(text); + } else if (!text) { + open = false; + } else if (open) { + // A bullet wrapped onto the next quoted line keeps its tail. + items[items.length - 1] += ` ${text}`; + } + } + return items; +} diff --git a/src/tui/__tests__/exit-line.test.ts b/src/tui/__tests__/exit-line.test.ts index 5b6b8b0cc..fe41666a9 100644 --- a/src/tui/__tests__/exit-line.test.ts +++ b/src/tui/__tests__/exit-line.test.ts @@ -1,4 +1,8 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; import { getExitLine } from '@tui/exit-line'; +import { buildSession } from '@programs'; import { WizardStore, Program } from '@tui/store'; import { OutroKind } from '@shared/outro'; import { HostResolution } from '@shared/host-resolution'; @@ -200,3 +204,60 @@ describe('getExitLine', () => { }); }); }); + +describe('getExitLine needs-attention block', () => { + const block = + '# Report\n\n> ⚠️ **Needs your attention**\n> - Load `.env` in the app.\n'; + + it('leads a successful exit with the handoff warning items', () => { + const store = storeWithOutro({ + kind: OutroKind.Success, + message: 'Error tracking configured!', + }); + store.setHandoffText(block); + const lines = stripAnsi(getExitLine(store)).split('\n'); + expect(lines.slice(0, 2)).toEqual([ + '⚠ Needs your attention:', + ' • Load `.env` in the app.', + ]); + expect(lines).toContain('✔ Error tracking configured!'); + }); + + it('keeps the items when the user exits before the outro', () => { + const store = new WizardStore(Program.PostHogIntegration); + store.setHandoffText(block); + const line = stripAnsi(getExitLine(store)); + expect(line).toContain('⚠ Needs your attention:'); + expect(line).toContain('exited.'); + }); + + it('reads the items from the report file when nothing was published', () => { + const installDir = fs.mkdtempSync(path.join(os.tmpdir(), 'exit-line-')); + try { + fs.writeFileSync(path.join(installDir, 'report.md'), block); + const store = new WizardStore(Program.PostHogIntegration); + store.session = buildSession({ installDir }); + store.setOutroData({ kind: OutroKind.Success, reportFile: 'report.md' }); + expect(stripAnsi(getExitLine(store))).toContain( + ' • Load `.env` in the app.', + ); + } finally { + fs.rmSync(installDir, { recursive: true, force: true }); + } + }); + + it('adds nothing when the report has no warning block', () => { + const store = storeWithOutro({ kind: OutroKind.Success, message: 'Done' }); + store.setHandoffText('# Report\n\nAll done.'); + expect(stripAnsi(getExitLine(store))).not.toContain('Needs your attention'); + }); + + it('skips the warning block on a run failure', () => { + const store = storeWithOutro({ kind: OutroKind.Error, message: 'boom' }); + store.session = { ...store.session, credentials: {} as never }; + store.setHandoffText(block); + const line = stripAnsi(getExitLine(store)); + expect(line).toContain('The wizard is unavailable'); + expect(line).not.toContain('Needs your attention'); + }); +}); diff --git a/src/tui/exit-line.ts b/src/tui/exit-line.ts index c1f8e4984..89e77b43e 100644 --- a/src/tui/exit-line.ts +++ b/src/tui/exit-line.ts @@ -19,11 +19,19 @@ import { OutroKind } from '@shared/outro'; import { isRunFailure, MINT_FAILURE_CONTACT } from '@tui/mint-failure'; import { formatTokenCount, formatCostUsd } from '@shared/token-pricing'; import { getLogFilePath } from '@utils/debug'; +import { readFileHead } from '@utils/bounded-fs'; +import { + NEEDS_ATTENTION_HEADING, + readNeedsAttention, +} from '@utils/needs-attention'; +import { join } from 'path'; const RESET_ATTRS = '\x1b[0m'; const GREEN = '\x1b[32m'; const BOLD = '\x1b[1m'; const DIM = '\x1b[2m'; +const YELLOW = '\x1b[33m'; +const REPORT_HEAD_BYTES = 16 * 1024; /** * Mirrors the hidden Ctrl+T HUD's tally into post-exit scrollback — but only @@ -66,7 +74,35 @@ function mcpLoginBlock(store: WizardStore): string | null { ); } +/** The report's warning items, from the published handoff or else the report file. */ +function needsAttentionBlock(store: WizardStore): string | null { + const reportFile = store.session.outroData?.reportFile; + const markdown = + store.handoffText ?? + (reportFile + ? readFileHead( + join(store.session.installDir, reportFile), + REPORT_HEAD_BYTES, + ) + : null); + const items = markdown ? readNeedsAttention(markdown) : []; + if (items.length === 0) return null; + return ( + `${YELLOW}${BOLD}⚠ ${NEEDS_ATTENTION_HEADING}:${RESET_ATTRS}\n` + + items.map((item) => ` • ${item}`).join('\n') + ); +} + export function getExitLine(store: WizardStore): string { + // A failed run prints its own unavailable notice; the report's warnings don't apply. + const attention = isRunFailure(store.session) + ? null + : needsAttentionBlock(store); + const body = exitSummary(store); + return attention ? `${attention}\n\n${body}` : body; +} + +function exitSummary(store: WizardStore): string { const outro = store.session.outroData; const label = store.programLabel ?? 'Wizard'; const costLine = tokenCostLine(store);