@namzu/sdk 62.6.0 → 62.7.0

package/src/runtime/query/turn/completion-audit.ts

@@ -5,10 +5,22 @@
  *
  * It blocks at most once per turn. After the one reminder the turn may end
  * however it likes, so the audit can never trap a run.
+ *
+ * The one reminder has four wordings. The original says nothing was run; when
+ * the turn's outcome record says more, the reminder says exactly that: a check
+ * ran with its exit status hidden, a check passed and files then changed, or a
+ * check failed. Which wording is used never changes how often the audit fires.
  */
 
+import type { TurnOutcome } from '../../../types/session/outcome.js'
+
 /** Tools that write to the project regardless of their input. */
-const WRITING_TOOLS = new Set(['edit', 'write', 'apply_patch', 'notebook_edit'])
+export const WRITING_TOOLS: ReadonlySet<string> = new Set([
+	'edit',
+	'write',
+	'apply_patch',
+	'notebook_edit',
+])
 
 /**
  * A command that checks work: a project runner invoked with a test, lint,
@@ -28,6 +40,41 @@ export function isVerificationCommand(command: string): boolean {
 export const COMPLETION_AUDIT_MESSAGE =
 	"Files were changed in this turn and nothing was run afterwards to check them. Before you finish: rerun the reproduction of the defect, if there was one; run the project's tests and its lint or format check; confirm the diff holds only what was asked; name any throwaway file you made. Then give your answer, stating what you ran and what you did not run. If a check cannot be run here, say which and why."
 
+/** The longest command a reminder repeats back, in characters. */
+export const COMPLETION_AUDIT_MAX_COMMAND_CHARS = 120
+
+/** The command as a reminder may show it: one line, printable, backticks dropped, at most 120 characters. */
+export function auditCommandText(command: string): string {
+	let plain = ''
+	for (const ch of command) {
+		const code = ch.charCodeAt(0)
+		plain += code < 0x20 || code === 0x7f || ch === '`' ? ' ' : ch
+	}
+	const flat = plain.replace(/\s+/g, ' ').trim()
+	if (flat.length <= COMPLETION_AUDIT_MAX_COMMAND_CHARS) return flat
+	return `${flat.slice(0, COMPLETION_AUDIT_MAX_COMMAND_CHARS - 3)}...`
+}
+
+const AUDIT_TAIL =
+	'Then give your answer, stating what you ran and what you did not run. If a check cannot be run here, say which and why.'
+
+/** The reminder for a check that ran with its exit status hidden (a pipe, `;`, `||`, a trailing `&`). */
+export function maskedCheckMessage(command: string): string {
+	return `Files were changed in this turn, and a check run, \`${auditCommandText(command)}\`, had its exit status hidden, so it cannot be told whether it passed. Run it again on its own, without the pipe or anything else attached to it; its output is already trimmed to the head and tail. ${AUDIT_TAIL}`
+}
+
+/** The reminder for a check that passed before files changed again. */
+export function staleCheckMessage(command: string | undefined): string {
+	const named = command === undefined ? 'A check' : `\`${auditCommandText(command)}\``
+	return `${named} passed in this turn, but files were changed after it, so it says nothing about the files as they are now. Run the checks again. ${AUDIT_TAIL}`
+}
+
+/** The reminder for a check whose latest run failed. */
+export function failingCheckMessage(command: string | undefined): string {
+	const named = command === undefined ? 'A check' : `\`${auditCommandText(command)}\``
+	return `${named} failed in this turn and has not passed since. Fix what it reports, or say why it cannot pass, and run it again. ${AUDIT_TAIL}`
+}
+
 /** A finished tool call as the audit sees it. */
 export interface AuditedCall {
 	readonly toolName: string
@@ -59,13 +106,37 @@ export class CompletionAudit {
 		}
 	}
 
+	/**
+	 * The reminder to give, or `undefined` when the turn may end. At most one per
+	 * turn across every wording: asking records the block. Nothing is said for a
+	 * turn that changed no file through a write tool. `outcome` is read only
+	 * when the audit has something to say.
+	 */
+	takeReminder(outcome?: () => TurnOutcome | undefined): string | undefined {
+		if (this.blocked || !this.edited) return undefined
+		const record = outcome?.()
+		let message: string | undefined
+		const failed = record?.checks.find((check) => check.result === 'failed')
+		const masked = record?.checks.find((check) => check.result === 'masked')
+		if (record?.verdict === 'failing' && failed) message = failingCheckMessage(failed.command)
+		else if (record?.verdict === 'stale') {
+			message = staleCheckMessage(
+				[...record.checks].reverse().find((c) => c.result === 'passed')?.command,
+			)
+		} else if (record?.verdict === 'inconclusive' && masked) {
+			message = maskedCheckMessage(masked.command)
+		} else if (!this.checkedSinceEdit) message = COMPLETION_AUDIT_MESSAGE
+		if (message === undefined) return undefined
+		this.blocked = true
+		return message
+	}
+
 	/**
 	 * Whether the turn must be held back from ending. True at most once: asking
-	 * records the block.
+	 * records the block. This is `takeReminder()` without an outcome record, kept
+	 * for callers that only need the yes or no.
 	 */
 	takeBlock(): boolean {
-		if (this.blocked || !this.edited || this.checkedSinceEdit) return false
-		this.blocked = true
-		return true
+		return this.takeReminder() !== undefined
 	}
 }