@namzu/sdk 1.4.0 → 3.0.0

package/src/advisory/__tests__/budget-enforcement.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisorDefinition, AdvisoryCallRecord } from '../../types/advisory/index.js'
+import type { StreamChunk } from '../../types/provider/index.js'
+import { assertBudgetEnforceable } from '../budget.js'
+import { AdvisoryContext } from '../context.js'
+import { TriggerEvaluator } from '../evaluator.js'
+import { AdvisoryExecutor } from '../executor.js'
+import { AdvisorRegistry } from '../registry.js'
+
+/**
+ * `AdvisoryBudget` declared six caps and enforced one. The other five were
+ * read by nothing: a host could set `maxCostPerRun` and watch an advisor
+ * spend without limit, and the only signal that the cap was inert was that
+ * nothing ever happened.
+ *
+ * Two of the six could not be honoured at all — the advisory stack is built
+ * per run, so a per-SESSION cap had no accumulator to count against — and
+ * those were removed rather than left as decoration. What remains is
+ * enforced here.
+ */
+
+function record(cost: number): AdvisoryCallRecord {
+	return {
+		advisorId: 'a',
+		request: { question: 'q' },
+		result: { advice: '' },
+		usage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		cost: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: cost, cacheDiscount: 0 },
+		durationMs: 1,
+		iteration: 1,
+		timestamp: 0,
+	}
+}
+
+function contextWith(budget: Parameters<typeof assertBudgetEnforceable>[0]['budget']) {
+	return new AdvisoryContext(
+		new AdvisorRegistry([]),
+		new AdvisoryExecutor(),
+		new TriggerEvaluator([]),
+		budget,
+	)
+}
+
+describe('a per-run cost cap actually stops the next call', () => {
+	it('allows a call while the accumulated cost is under the cap', () => {
+		const ctx = contextWith({ maxCostPerRun: 1 })
+		ctx.recordCall(record(0.4))
+		expect(ctx.checkBudget().allowed).toBe(true)
+	})
+
+	it('refuses once the accumulated cost reaches the cap', () => {
+		const ctx = contextWith({ maxCostPerRun: 1 })
+		ctx.recordCall(record(0.6))
+		ctx.recordCall(record(0.5))
+
+		const verdict = ctx.checkBudget()
+		expect(verdict.allowed).toBe(false)
+		// The operator gets the number they set and the number they hit;
+		// "budget exhausted" alone leaves them guessing which cap tripped.
+		expect(verdict.reason).toContain('1.1')
+		expect(verdict.reason).toContain('cost')
+	})
+
+	it('leaves the call cap working alongside it', () => {
+		const ctx = contextWith({ maxCallsPerRun: 1 })
+		ctx.recordCall(record(0))
+		expect(ctx.checkBudget().allowed).toBe(false)
+	})
+})
+
+describe('a cost cap without pricing is refused, not silently inert', () => {
+	const advisor = (pricing?: { inputCostPer1M: number; outputCostPer1M: number }) =>
+		({
+			id: 'a',
+			name: 'A',
+			model: 'm',
+			provider: {} as AdvisorDefinition['provider'],
+			...(pricing ? { pricing } : {}),
+		}) as AdvisorDefinition
+
+	it('throws when a cost cap is set and an advisor carries no pricing', () => {
+		expect(() =>
+			assertBudgetEnforceable({ advisors: [advisor()], budget: { maxCostPerRun: 5 } }),
+		).toThrow(/pricing/i)
+	})
+
+	it('accepts the same cap once pricing is supplied', () => {
+		expect(() =>
+			assertBudgetEnforceable({
+				advisors: [advisor({ inputCostPer1M: 1, outputCostPer1M: 2 })],
+				budget: { maxCostPerRun: 5 },
+			}),
+		).not.toThrow()
+	})
+
+	it('says nothing about pricing when no cost cap is set', () => {
+		expect(() =>
+			assertBudgetEnforceable({ advisors: [advisor()], budget: { maxCallsPerRun: 2 } }),
+		).not.toThrow()
+	})
+})
+
+describe('a per-call token cap reaches the provider', () => {
+	function providerCapturing(seen: { maxTokens?: number }) {
+		return {
+			chatStream: vi.fn(async function* (params: {
+				maxTokens?: number
+			}): AsyncGenerator<StreamChunk> {
+				seen.maxTokens = params.maxTokens
+				yield { id: 'r', delta: { content: 'ok' } } as StreamChunk
+				yield {
+					id: 'r',
+					delta: {},
+					finishReason: 'stop',
+					usage: {
+						promptTokens: 1,
+						completionTokens: 1,
+						totalTokens: 2,
+						cachedTokens: 0,
+						cacheWriteTokens: 0,
+					},
+				} as StreamChunk
+			}),
+		} as unknown as AdvisorDefinition['provider']
+	}
+
+	it('clamps an advisor that asks for more than the budget allows', async () => {
+		const seen: { maxTokens?: number } = {}
+		const exec = new AdvisoryExecutor(undefined, { maxTokensPerCall: 100 })
+		await exec.consult(
+			{
+				id: 'a',
+				name: 'A',
+				model: 'm',
+				provider: providerCapturing(seen),
+				maxResponseTokens: 5000,
+			},
+			{ question: 'q' },
+			{ messages: [], iteration: 1 },
+		)
+		expect(seen.maxTokens).toBe(100)
+	})
+
+	it('applies the cap to an advisor that names no ceiling of its own', async () => {
+		const seen: { maxTokens?: number } = {}
+		const exec = new AdvisoryExecutor(undefined, { maxTokensPerCall: 100 })
+		await exec.consult(
+			{ id: 'a', name: 'A', model: 'm', provider: providerCapturing(seen) },
+			{ question: 'q' },
+			{ messages: [], iteration: 1 },
+		)
+		expect(seen.maxTokens).toBe(100)
+	})
+
+	it('leaves a smaller advisor ceiling alone', async () => {
+		const seen: { maxTokens?: number } = {}
+		const exec = new AdvisoryExecutor(undefined, { maxTokensPerCall: 100 })
+		await exec.consult(
+			{ id: 'a', name: 'A', model: 'm', provider: providerCapturing(seen), maxResponseTokens: 40 },
+			{ question: 'q' },
+			{ messages: [], iteration: 1 },
+		)
+		expect(seen.maxTokens).toBe(40)
+	})
+})
+
+describe('cost is real when the advisor carries pricing', () => {
+	it('computes from the advisor pricing rather than reporting zero', async () => {
+		const provider = {
+			chatStream: vi.fn(async function* (): AsyncGenerator<StreamChunk> {
+				yield { id: 'r', delta: { content: 'ok' } } as StreamChunk
+				yield {
+					id: 'r',
+					delta: {},
+					finishReason: 'stop',
+					usage: {
+						promptTokens: 1_000_000,
+						completionTokens: 1_000_000,
+						totalTokens: 2_000_000,
+						cachedTokens: 0,
+						cacheWriteTokens: 0,
+					},
+				} as StreamChunk
+			}),
+		} as unknown as AdvisorDefinition['provider']
+
+		const exec = new AdvisoryExecutor()
+		const out = await exec.consult(
+			{
+				id: 'a',
+				name: 'A',
+				model: 'm',
+				provider,
+				pricing: { inputCostPer1M: 3, outputCostPer1M: 15 },
+			},
+			{ question: 'q' },
+			{ messages: [], iteration: 1 },
+		)
+		expect(out.cost.totalCost).toBe(18)
+	})
+})

package/src/advisory/__tests__/structured-response.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisorDefinition } from '../../types/advisory/index.js'
+import type { StreamChunk } from '../../types/provider/index.js'
+import { AdvisoryExecutor } from '../executor.js'
+import { ADVISORY_RESPONSE_CONTRACT, parseAdvisoryResponse } from '../parse.js'
+
+/**
+ * `AdvisoryResult.warnings` and `.decisions` had two consumers each — the
+ * advisory phase folds decisions into working state and renders warnings
+ * back to the executing agent, and the advisory tool renders both — and no
+ * producer at all. The parser returned `{ advice }` and a comment saying
+ * structure came later. Every consumer branch was dead in a real run, and
+ * their tests passed because they built the result by hand.
+ */
+
+describe('an advisor answer is read back into its parts', () => {
+	it('lifts warnings and decisions out of the prose', () => {
+		const parsed = parseAdvisoryResponse(
+			[
+				'Proceed, but slowly.',
+				'<warnings>',
+				'- the store is not transactional',
+				'- retries are not idempotent',
+				'</warnings>',
+				'<decisions>',
+				'- keep the existing schema',
+				'</decisions>',
+			].join('\n'),
+		)
+
+		expect(parsed.warnings).toEqual([
+			'the store is not transactional',
+			'retries are not idempotent',
+		])
+		expect(parsed.decisions).toEqual(['keep the existing schema'])
+	})
+
+	it('leaves the blocks out of the advice, so nothing is said twice', () => {
+		const parsed = parseAdvisoryResponse('Do it.\n<warnings>\n- careful\n</warnings>')
+
+		expect(parsed.advice).toBe('Do it.')
+		expect(parsed.advice).not.toContain('careful')
+	})
+
+	it('accepts whichever bullet the model reached for', () => {
+		const parsed = parseAdvisoryResponse('<decisions>\n1. first\n* second\n• third\n</decisions>')
+
+		expect(parsed.decisions).toEqual(['first', 'second', 'third'])
+	})
+
+	it('omits the fields entirely rather than reporting empty ones', () => {
+		const parsed = parseAdvisoryResponse('Just advice.\n<warnings>\n\n</warnings>')
+
+		expect(parsed.advice).toBe('Just advice.')
+		expect(parsed.warnings).toBeUndefined()
+		expect(parsed.decisions).toBeUndefined()
+	})
+
+	it('treats an unclosed block as prose instead of guessing where it ends', () => {
+		const parsed = parseAdvisoryResponse('Careful.\n<warnings>\n- half a thought')
+
+		expect(parsed.warnings).toBeUndefined()
+		expect(parsed.advice).toContain('half a thought')
+	})
+
+	it('reads a plain answer as pure advice', () => {
+		expect(parseAdvisoryResponse('  Ship it.  ')).toEqual({ advice: 'Ship it.' })
+	})
+})
+
+describe('every advisor is told the convention its answer is read with', () => {
+	function capturingProvider(seen: { system?: string }) {
+		return {
+			chatStream: vi.fn(async function* (params: {
+				messages: Array<{ role: string; content: string | null }>
+			}): AsyncGenerator<StreamChunk> {
+				seen.system = params.messages.find((m) => m.role === 'system')?.content ?? undefined
+				yield { id: 'r', delta: { content: 'ok' } } as StreamChunk
+				yield {
+					id: 'r',
+					delta: {},
+					finishReason: 'stop',
+					usage: {
+						promptTokens: 0,
+						completionTokens: 0,
+						totalTokens: 0,
+						cachedTokens: 0,
+						cacheWriteTokens: 0,
+					},
+				} as StreamChunk
+			}),
+		} as unknown as AdvisorDefinition['provider']
+	}
+
+	async function systemPromptFor(advisor: Partial<AdvisorDefinition>): Promise<string> {
+		const seen: { system?: string } = {}
+		await new AdvisoryExecutor().consult(
+			{ id: 'a', name: 'A', model: 'm', provider: capturingProvider(seen), ...advisor },
+			{ question: 'q' },
+			{ messages: [], iteration: 1 },
+		)
+		return seen.system ?? ''
+	}
+
+	it('appends the contract to the default prompt', async () => {
+		expect(await systemPromptFor({})).toContain(ADVISORY_RESPONSE_CONTRACT)
+	})
+
+	// The failure that hides: a host writes its own prompt, the advisor is
+	// never told the convention, and its warnings are silently unparseable.
+	it('appends it to a host-written prompt too, without discarding that prompt', async () => {
+		const prompt = await systemPromptFor({ systemPrompt: 'You are terse.' })
+
+		expect(prompt).toContain('You are terse.')
+		expect(prompt).toContain(ADVISORY_RESPONSE_CONTRACT)
+	})
+
+	it('appends it to a persona-assembled prompt too', async () => {
+		const prompt = await systemPromptFor({
+			persona: {
+				identity: { role: 'reviewer', description: 'Reviews plans.' },
+			} as AdvisorDefinition['persona'],
+		})
+
+		expect(prompt).toContain(ADVISORY_RESPONSE_CONTRACT)
+	})
+})

package/src/advisory/budget.ts

@@ -0,0 +1,27 @@
+import type { AdvisorDefinition, AdvisoryBudget } from '../types/advisory/index.js'
+
+/**
+ * Refuse a budget the runtime cannot honour.
+ *
+ * A cost cap is enforced against real spend, and real spend needs a price.
+ * Without one every call costs zero, so the cap never trips — the host sets
+ * a limit, sees no error, and learns it was decoration only from the bill.
+ * Refusing at construction is the same trade the runtime makes elsewhere:
+ * a configuration that cannot do what it says is an error, not a default.
+ */
+export function assertBudgetEnforceable(config: {
+	readonly advisors: readonly AdvisorDefinition[]
+	readonly budget?: AdvisoryBudget | undefined
+}): void {
+	if (config.budget?.maxCostPerRun === undefined) return
+
+	const unpriced = config.advisors.filter((a) => a.pricing === undefined).map((a) => a.id)
+	if (unpriced.length === 0) return
+
+	throw new Error(
+		`Advisory budget sets maxCostPerRun but ${unpriced.length === 1 ? 'advisor' : 'advisors'} ` +
+			`${unpriced.join(', ')} carr${unpriced.length === 1 ? 'ies' : 'y'} no pricing, so cost ` +
+			'cannot be measured and the cap could never be reached. Give each advisor a `pricing` ' +
+			'entry, or drop the cost cap and bound the run with `maxCallsPerRun`.',
+	)
+}

package/src/advisory/context.ts

@@ -34,6 +34,11 @@ export class AdvisoryContext {
 		return { remaining, total, used }
 	}
 
+	/** Advisory spend so far this run, summed from the recorded calls. */
+	spentCost(): number {
+		return this.callHistory.reduce((sum, call) => sum + call.cost.totalCost, 0)
+	}
+
 	checkBudget(): { allowed: boolean; reason?: string } {
 		const { remaining, total } = this.getBudgetStatus()
 		if (remaining !== undefined && remaining <= 0) {
@@ -42,6 +47,20 @@ export class AdvisoryContext {
 				reason: `Advisory budget exhausted: ${total} calls used of ${total} allowed per run`,
 			}
 		}
+
+		// Checked before the call, not after: a cap that only reports
+		// overspend once it has happened is a log line, not a budget.
+		const costCap = this.budget?.maxCostPerRun
+		if (costCap !== undefined) {
+			const spent = this.spentCost()
+			if (spent >= costCap) {
+				return {
+					allowed: false,
+					reason: `Advisory budget exhausted: cost ${spent} of ${costCap} allowed per run`,
+				}
+			}
+		}
+
 		return { allowed: true }
 	}
 }

package/src/advisory/executor.test.ts

@@ -6,17 +6,19 @@
  *     - Builds a context message block (see buildContext tests).
  *     - Concatenates `[system, ...context, user(question)]` and calls
  *       `advisor.provider.chat(...)` with `toolChoice: 'none'`.
- *     - Parses the response via a passthrough `{ advice: rawContent }`
- *       shape (no structured parsing yet — advisor.ts line 166-168).
- *     - Returns `{result, usage, cost, durationMs}`. `cost` is a
- *       zero-value `CostInfo` — pricing is provider-specific and not
- *       applied here.
+ *     - Parses the response with `parseAdvisoryResponse`, lifting any
+ *       `<warnings>` / `<decisions>` blocks out of the prose.
+ *     - Returns `{result, usage, cost, durationMs}`. `cost` is computed
+ *       from `advisor.pricing` when present, and zero-valued when the
+ *       advisor carries none.
  *
  *   - `buildSystemPrompt` priority:
- *     1. `advisor.systemPrompt` (verbatim).
+ *     1. `advisor.systemPrompt`.
  *     2. `advisor.persona` (via `assembleSystemPrompt`).
  *     3. Fallback: "You are <name>, an advisory agent." + optional
  *        domains line + "Provide concise, actionable advice..."
+ *     Every branch is followed by the response contract, so an advisor
+ *     with its own prompt is still told how its answer is read back.
  *
  *   - `buildContext`:
  *     - Returns [] when `request.includeContext === false`.
@@ -46,6 +48,7 @@ import type {
 } from '../types/provider/index.js'
 
 import { type AdvisoryCallContext, AdvisoryExecutor } from './executor.js'
+import { ADVISORY_RESPONSE_CONTRACT } from './parse.js'
 
 /**
  * Builds a minimal mock provider for advisory tests. Phase 2 of
@@ -159,12 +162,13 @@ describe('AdvisoryExecutor — consult happy path', () => {
 })
 
 describe('AdvisoryExecutor — buildSystemPrompt', () => {
-	it('uses advisor.systemPrompt verbatim when set', async () => {
+	it('keeps advisor.systemPrompt and appends the response contract', async () => {
 		const provider = mockProvider()
 		const e = new AdvisoryExecutor()
 		await e.consult(advisor({ provider, systemPrompt: 'FIXED PROMPT' }), req, ctx())
 		const call = vi.mocked(provider.chatStream).mock.calls[0]?.[0] as ChatCompletionParams
-		expect(call.messages[0]?.content).toBe('FIXED PROMPT')
+		expect(call.messages[0]?.content).toContain('FIXED PROMPT')
+		expect(call.messages[0]?.content).toContain(ADVISORY_RESPONSE_CONTRACT)
 	})
 
 	it('falls back to name + domains + boilerplate when no systemPrompt or persona', async () => {

package/src/advisory/executor.ts

@@ -1,12 +1,15 @@
 import { CHARS_PER_TOKEN } from '../constants/limits.js'
 import { assembleSystemPrompt } from '../persona/assembler.js'
 import { collect } from '../provider/collect.js'
-import type { AdvisorDefinition } from '../types/advisory/config.js'
+
+import type { AdvisorDefinition, AdvisoryBudget } from '../types/advisory/config.js'
 import type { AdvisoryRequest, AdvisoryResult } from '../types/advisory/result.js'
 import type { CostInfo, TokenUsage } from '../types/common/index.js'
 import { type Message, createSystemMessage, createUserMessage } from '../types/message/index.js'
 import type { LLMToolSchema } from '../types/tool/index.js'
+import { calculateCost } from '../utils/cost.js'
 import { type Logger, getRootLogger } from '../utils/logger.js'
+import { ADVISORY_RESPONSE_CONTRACT, parseAdvisoryResponse } from './parse.js'
 
 export interface AdvisoryCallContext {
 	readonly messages: Message[]
@@ -24,9 +27,23 @@ export interface AdvisoryExecutionResult {
 
 export class AdvisoryExecutor {
 	private readonly logger: Logger
+	private readonly budget: AdvisoryBudget | undefined
 
-	constructor(logger?: Logger) {
+	constructor(logger?: Logger, budget?: AdvisoryBudget) {
 		this.logger = (logger ?? getRootLogger()).child({ component: 'AdvisoryExecutor' })
+		this.budget = budget
+	}
+
+	/**
+	 * The response ceiling for one call: the tighter of what the advisor
+	 * asks for and what the budget allows. An advisor that names no ceiling
+	 * still gets the budget's, which is the whole point of a per-call cap.
+	 */
+	private responseTokenCeiling(advisor: AdvisorDefinition): number | undefined {
+		const cap = this.budget?.maxTokensPerCall
+		if (cap === undefined) return advisor.maxResponseTokens
+		if (advisor.maxResponseTokens === undefined) return cap
+		return Math.min(advisor.maxResponseTokens, cap)
 	}
 
 	async consult(
@@ -57,16 +74,16 @@ export class AdvisoryExecutor {
 				model: advisor.model,
 				messages,
 				temperature: advisor.temperature,
-				maxTokens: advisor.maxResponseTokens,
+				maxTokens: this.responseTokenCeiling(advisor),
 				toolChoice: 'none',
 			}),
 		)
 
 		const durationMs = Date.now() - startMs
 
-		const result = this.parseResult(response.message.content ?? '')
+		const result = parseAdvisoryResponse(response.message.content ?? '')
 
-		const cost = this.computeCost(response.usage)
+		const cost = this.computeCost(advisor, response.usage)
 
 		this.logger.info('advisory call completed', {
 			advisorId: advisor.id,
@@ -84,6 +101,13 @@ export class AdvisoryExecutor {
 	}
 
 	private buildSystemPrompt(advisor: AdvisorDefinition): string {
+		// The contract is appended to every branch, not folded into the
+		// default: an advisor with its own prompt or a persona is still read
+		// back by the same parser, and used to be the one never told so.
+		return `${this.describeAdvisor(advisor)}\n\n${ADVISORY_RESPONSE_CONTRACT}`
+	}
+
+	private describeAdvisor(advisor: AdvisorDefinition): string {
 		if (advisor.systemPrompt) {
 			return advisor.systemPrompt
 		}
@@ -170,28 +194,16 @@ export class AdvisoryExecutor {
 	}
 
 	/**
-	 * Parses the raw LLM response into an AdvisoryResult.
+	 * Cost for one call, from the advisor's own pricing.
 	 *
-	 * Phase 1: text-only extraction. Structured parsing comes later.
+	 * Zero when the advisor carries none — which is honest, not a
+	 * placeholder: a cost CAP over unpriced advisors is refused at
+	 * construction, so nothing enforces against this zero.
 	 */
-	private parseResult(rawContent: string): AdvisoryResult {
-		return {
-			advice: rawContent,
-		}
-	}
-
-	/**
-	 * Computes cost from token usage.
-	 *
-	 * Returns zero-value cost since pricing is provider-specific.
-	 * Callers with pricing data can recompute via calculateCost().
-	 */
-	private computeCost(_usage: TokenUsage): CostInfo {
-		return {
-			inputCostPer1M: 0,
-			outputCostPer1M: 0,
-			totalCost: 0,
-			cacheDiscount: 0,
+	private computeCost(advisor: AdvisorDefinition, usage: TokenUsage): CostInfo {
+		if (!advisor.pricing) {
+			return { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 }
 		}
+		return calculateCost(usage, advisor.pricing)
 	}
 }

package/src/advisory/index.ts

@@ -1,3 +1,5 @@
+export { assertBudgetEnforceable } from './budget.js'
+export { ADVISORY_RESPONSE_CONTRACT, parseAdvisoryResponse } from './parse.js'
 export { AdvisorRegistry } from './registry.js'
 export { AdvisoryExecutor } from './executor.js'
 export type { AdvisoryCallContext, AdvisoryExecutionResult } from './executor.js'

package/src/advisory/parse.ts

@@ -0,0 +1,63 @@
+import type { AdvisoryResult } from '../types/advisory/result.js'
+
+/**
+ * The response shape asked of every advisor.
+ *
+ * Appended to whatever prompt the advisor already carries — a persona or a
+ * host-written system prompt describes WHO the advisor is, and this
+ * describes how its answer is read back. Keeping it separate is what lets a
+ * custom prompt keep working: the two used to be the same string, so an
+ * advisor with its own prompt was never told the convention and its
+ * warnings could not be found.
+ */
+export const ADVISORY_RESPONSE_CONTRACT = [
+	'Write your advice as prose.',
+	'If you have warnings the executing agent must not miss, put them in a `<warnings>` block, one per line, each starting with `-`.',
+	'If you have made decisions the executing agent should carry forward, put them in a `<decisions>` block in the same form.',
+	'Both blocks are optional. Omit a block entirely rather than emitting an empty one.',
+].join(' ')
+
+const BLOCK = (tag: string) => new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, 'gi')
+
+/** Bullet, dash, asterisk or `1.` — whichever the model reached for. */
+const LEADER = /^\s*(?:[-*•]|\d+[.)])\s*/
+
+function itemsIn(block: string): string[] {
+	return block
+		.split('\n')
+		.map((line) => line.replace(LEADER, '').trim())
+		.filter((line) => line.length > 0)
+}
+
+/**
+ * Read an advisor's answer.
+ *
+ * The structured half of `AdvisoryResult` had readers and no writer: the
+ * parser returned `{ advice }` and nothing else, so an advisor's decisions
+ * never reached working state and its warnings never reached the executing
+ * agent. Both consumers were written, tested against hand-built results,
+ * and permanently unreachable in a real run.
+ */
+export function parseAdvisoryResponse(rawContent: string): AdvisoryResult {
+	const warnings: string[] = []
+	const decisions: string[] = []
+	let advice = rawContent
+
+	for (const [tag, sink] of [
+		['warnings', warnings],
+		['decisions', decisions],
+	] as const) {
+		for (const match of rawContent.matchAll(BLOCK(tag))) {
+			sink.push(...itemsIn(match[1] ?? ''))
+		}
+		// Stripped from the advice so the executing agent is not shown the
+		// same warning twice — once as prose, once under its own heading.
+		advice = advice.replace(BLOCK(tag), '')
+	}
+
+	return {
+		advice: advice.trim(),
+		...(warnings.length > 0 ? { warnings } : {}),
+		...(decisions.length > 0 ? { decisions } : {}),
+	}
+}