@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/exec/request/limits.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Every ceiling one request is held to (headless-request-scope-and-typed-result
+ * section 4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * STRUCTURE, NOT POLICY, for the reason `exec/result/limits.ts` records: a request
+ * budget is a property of the WIRE (what one `request_end` can carry, what one
+ * timer may bound), not a user preference, so nothing here is persisted and nothing
+ * here is reachable through `config.json`.
+ */
+export declare const REQUEST_LIMITS: {
+    /**
+     * The shortest request wall-clock budget worth having.
+     *
+     * Below a second the flag would only ever produce `timeout` before the first
+     * provider round trip finishes, which is a footgun rather than a budget.
+     */
+    readonly minRequestTimeoutMs: 1000;
+    /**
+     * The longest one request may be bounded to.
+     *
+     * SAME VALUE AS `BRIDGE_LIMITS.maxDecisionTimeoutMs` ON PURPOSE: both answer
+     * "how long may a caller make this process wait without hearing from it", and
+     * two different answers to that question in one protocol is a bug waiting for a
+     * caller to find it.
+     */
+    readonly maxRequestTimeoutMs: 1800000;
+    /** Turns one request may take. Far above any real prompt; a runaway guard. */
+    readonly maxRequestTurns: 200;
+    /**
+     * Request ids remembered as "already settled", for de-duplication.
+     *
+     * NOT the emitter of the event (see the two writers in `runner.ts`): it is the
+     * authority that makes "exactly one `request_end` per request" true. A FIFO
+     * because a long-lived process must not grow it without bound.
+     */
+    readonly maxTrackedRequests: 512;
+    /**
+     * `request_end.result` character ceiling.
+     *
+     * EVENT FRAME TRUNCATION, not the value ceiling - the full text is still on the
+     * `assistant` event, and the accepted structured value has its own limit in
+     * `RESULT_LIMITS.maxResultValueBytes`. Keeping the two ideas apart is what stops
+     * "the answer got cut" from being indistinguishable from "the answer was too
+     * big to accept".
+     */
+    readonly maxResultChars: 8192;
+};
+/** The union of every value in `REQUEST_LIMITS`; useful for tests and docs. */
+export type RequestLimits = typeof REQUEST_LIMITS;

package/dist/exec/request/limits.js

@@ -0,0 +1,49 @@
+/**
+ * Every ceiling one request is held to (headless-request-scope-and-typed-result
+ * section 4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * STRUCTURE, NOT POLICY, for the reason `exec/result/limits.ts` records: a request
+ * budget is a property of the WIRE (what one `request_end` can carry, what one
+ * timer may bound), not a user preference, so nothing here is persisted and nothing
+ * here is reachable through `config.json`.
+ */
+export const REQUEST_LIMITS = {
+    /**
+     * The shortest request wall-clock budget worth having.
+     *
+     * Below a second the flag would only ever produce `timeout` before the first
+     * provider round trip finishes, which is a footgun rather than a budget.
+     */
+    minRequestTimeoutMs: 1_000,
+    /**
+     * The longest one request may be bounded to.
+     *
+     * SAME VALUE AS `BRIDGE_LIMITS.maxDecisionTimeoutMs` ON PURPOSE: both answer
+     * "how long may a caller make this process wait without hearing from it", and
+     * two different answers to that question in one protocol is a bug waiting for a
+     * caller to find it.
+     */
+    maxRequestTimeoutMs: 1_800_000,
+    /** Turns one request may take. Far above any real prompt; a runaway guard. */
+    maxRequestTurns: 200,
+    /**
+     * Request ids remembered as "already settled", for de-duplication.
+     *
+     * NOT the emitter of the event (see the two writers in `runner.ts`): it is the
+     * authority that makes "exactly one `request_end` per request" true. A FIFO
+     * because a long-lived process must not grow it without bound.
+     */
+    maxTrackedRequests: 512,
+    /**
+     * `request_end.result` character ceiling.
+     *
+     * EVENT FRAME TRUNCATION, not the value ceiling - the full text is still on the
+     * `assistant` event, and the accepted structured value has its own limit in
+     * `RESULT_LIMITS.maxResultValueBytes`. Keeping the two ideas apart is what stops
+     * "the answer got cut" from being indistinguishable from "the answer was too
+     * big to accept".
+     */
+    maxResultChars: 8_192,
+};

package/dist/exec/request/scope.d.ts

@@ -0,0 +1,106 @@
+/**
+ * One request, as an object with a budget, an account and a cancellation
+ * (headless-request-scope-and-typed-result section 2.4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ONE WRITER FOR EVERY REQUEST-LEVEL FACT. The turn count, the wall clock, the
+ * cancellation intent, the "already aborted for an accepted result" latch and the
+ * de-duplication table all live in here, so the runner only ever ASKS. A second
+ * writer anywhere is how "the request ended but nobody was told" happens.
+ *
+ * THE TIMER IS THE SUBTLE PART (review P1-4). A `setTimeout` that fires after the
+ * request it belongs to has ended would abort the NEXT request - one request's
+ * budget killing another, which is the single thing this whole file exists to
+ * prevent. Three latches, not one: `begin()` clears the previous timer and bumps a
+ * generation, the callback refuses to act unless its generation is still current,
+ * and `end()` clears the timer synchronously. This codebase has paid for the same
+ * lesson three times (`runGen`, `abortRequested`, `requestVersion`); the comment is
+ * here so the fourth time is cheaper.
+ */
+import type { ExecCost, ExecRequestError, ExecRequestStopReason, ExecUsage } from '../events.js';
+/** The process-level counters a request is measured against. */
+export interface RequestTotals {
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    cost: ExecCost;
+}
+export interface RequestScopeOptions {
+    /** `--request-max-turns`, or absent for "no ceiling". */
+    maxTurns?: number;
+    /** `--request-max-duration`, or absent. Bridge-only, like the turns ceiling. */
+    maxDurationMs?: number;
+    now: () => number;
+    /**
+     * Called when the wall-clock budget expires FOR THE CURRENT REQUEST ONLY.
+     *
+     * Takes the generation so a caller can assert what it received: a callback whose
+     * number is not the scope's current generation must do nothing.
+     */
+    onDurationExpired: (generation: number) => void;
+    /** The process-level totals to diff against; read at `begin()` and at `end()`. */
+    totals: () => RequestTotals;
+}
+/** What `end()` hands the runner so it can write one `request_end`. */
+export interface RequestSettlement {
+    requestId: string;
+    requestSeq?: number;
+    stopReason: ExecRequestStopReason;
+    isError: boolean;
+    turns: number;
+    durationMs: number;
+    usage: ExecUsage;
+    cost: ExecCost;
+    error: ExecRequestError | null;
+}
+export interface RequestScope {
+    /** Start a request: resets everything except the process-level totals. */
+    begin(input: {
+        requestSeq: number;
+        requestId?: string;
+    }): void;
+    requestId(): string | undefined;
+    requestSeq(): number | undefined;
+    /** One turn finished (called from the same place the process counter is bumped). */
+    countTurn(): void;
+    turns(): number;
+    /** Turns exhausted? `false` when there is no ceiling. */
+    turnsExhausted(): boolean;
+    /** Wall clock over budget, checked lazily at turn boundaries. */
+    isOverDurationBudget(now: number): boolean;
+    /** Cancel this request. Idempotent; the first reason wins. */
+    cancel(reason: ExecRequestStopReason): void;
+    cancelledReason(): ExecRequestStopReason | null;
+    /** The I-S8 latch: has this request already been aborted for an accepted result? */
+    acceptanceAborted(): boolean;
+    markAcceptanceAborted(): void;
+    /**
+     * Finish the request and return its account. THROWS on the second call: a repeated
+     * `request_end` would make a caller de-duplicate by id and silently lose the
+     * second account.
+     *
+     * `stopReason` is the PROCESS-LEVEL reason and is used only when this request was
+     * not cancelled on its own terms (section 2.4.2). A process `interrupt`, a spent
+     * `--max-turns` and a `--max-duration` end the run underneath a live request, and
+     * that request still has to say why it ended - `completed` there is a lie a caller
+     * reads as a finished answer.
+     */
+    end(input: {
+        now: number;
+        error?: ExecRequestError | null;
+        stopReason?: ExecRequestStopReason;
+    }): RequestSettlement;
+    /** Differential account: what changed since `begin()`. */
+    usageDelta(): {
+        usage: ExecUsage;
+        cost: ExecCost;
+    };
+    /** Remember a settled request id. Returns `false` when it was already known. */
+    remember(requestId: string): boolean;
+    hasRemembered(requestId: string): boolean;
+    /** Clear the timer; safe to call twice. */
+    detach(): void;
+}
+export declare function createRequestScope(options: RequestScopeOptions): RequestScope;

package/dist/exec/request/scope.js

@@ -0,0 +1,149 @@
+import { REQUEST_LIMITS } from './limits.js';
+const ZERO_TOTALS = {
+    usage: { inputTokens: 0, outputTokens: 0 },
+    cost: { amount: 0, currency: 'USD', known: false },
+};
+export function createRequestScope(options) {
+    let requestSeq;
+    let requestId;
+    let startedAt = 0;
+    let turnCount = 0;
+    let cancelReason = null;
+    let abortedForAcceptance = false;
+    let ended = true;
+    let baseline = ZERO_TOTALS;
+    let generation = 0;
+    let timer = null;
+    let detached = false;
+    /** Bounded FIFO of settled ids: the authority behind "exactly one request_end". */
+    const remembered = new Set();
+    const clearTimer = () => {
+        if (!timer)
+            return;
+        clearTimeout(timer);
+        timer = null;
+    };
+    const readTotals = () => {
+        try {
+            return options.totals();
+        }
+        catch {
+            // A controller that has already been disposed must not turn accounting into an
+            // exception on the way out of a run.
+            return ZERO_TOTALS;
+        }
+    };
+    const scope = {
+        begin(input) {
+            // CLEAR FIRST, THEN BUMP: a callback that is already queued on the event loop
+            // will observe the new generation and refuse to act.
+            clearTimer();
+            generation += 1;
+            requestSeq = input.requestSeq;
+            requestId = input.requestId;
+            startedAt = options.now();
+            turnCount = 0;
+            cancelReason = null;
+            abortedForAcceptance = false;
+            ended = false;
+            baseline = readTotals();
+            if (options.maxDurationMs === undefined)
+                return;
+            const mine = generation;
+            timer = setTimeout(() => {
+                // THE LATCH THAT MAKES THIS SAFE. Without it, a request whose budget expired
+                // while a long synchronous task held the loop would abort whichever request
+                // happened to be running by then.
+                if (detached || mine !== generation || ended)
+                    return;
+                scope.cancel('timeout');
+                options.onDurationExpired(mine);
+            }, options.maxDurationMs);
+            timer.unref?.();
+        },
+        requestId: () => requestId,
+        requestSeq: () => requestSeq,
+        countTurn() {
+            turnCount += 1;
+        },
+        turns: () => turnCount,
+        turnsExhausted() {
+            return options.maxTurns !== undefined && turnCount >= options.maxTurns;
+        },
+        isOverDurationBudget(now) {
+            if (options.maxDurationMs === undefined)
+                return false;
+            return now - startedAt >= options.maxDurationMs;
+        },
+        cancel(reason) {
+            if (cancelReason === null)
+                cancelReason = reason;
+        },
+        cancelledReason: () => cancelReason,
+        acceptanceAborted: () => abortedForAcceptance,
+        markAcceptanceAborted() {
+            abortedForAcceptance = true;
+        },
+        end(input) {
+            if (ended) {
+                throw new Error('RequestScope.end() called twice for one request');
+            }
+            ended = true;
+            clearTimer();
+            const delta = scope.usageDelta();
+            // THE REQUEST'S OWN CANCELLATION WINS; the process-level reason is only a
+            // fallback, so "the caller cancelled this one" is never overwritten by "the run
+            // was interrupted a moment later".
+            const reason = cancelReason ?? input.stopReason ?? 'completed';
+            return {
+                requestId: requestId ?? 'unknown',
+                ...(requestSeq !== undefined ? { requestSeq } : {}),
+                stopReason: reason,
+                isError: input.error !== null && input.error !== undefined,
+                turns: turnCount,
+                durationMs: Math.max(0, input.now - startedAt),
+                usage: delta.usage,
+                cost: delta.cost,
+                error: input.error ?? null,
+            };
+        },
+        usageDelta() {
+            const current = readTotals();
+            return {
+                usage: {
+                    inputTokens: current.usage.inputTokens - baseline.usage.inputTokens,
+                    outputTokens: current.usage.outputTokens - baseline.usage.outputTokens,
+                    totalTokens: current.usage.inputTokens + current.usage.outputTokens -
+                        (baseline.usage.inputTokens + baseline.usage.outputTokens),
+                },
+                // A DIFFERENCE, NOT A COPY. `known` rides along from the current reading: a
+                // model with no price table must report "unknown" for the request exactly as
+                // it does for the process, instead of a confident zero.
+                cost: {
+                    amount: current.cost.amount - baseline.cost.amount,
+                    currency: 'USD',
+                    known: current.cost.known,
+                },
+            };
+        },
+        remember(id) {
+            if (remembered.has(id))
+                return false;
+            remembered.add(id);
+            // A FIFO, because a long-lived process serves an unbounded number of requests
+            // and the set only exists to answer "did this one already settle".
+            if (remembered.size > REQUEST_LIMITS.maxTrackedRequests) {
+                const oldest = remembered.values().next();
+                if (!oldest.done)
+                    remembered.delete(oldest.value);
+            }
+            return true;
+        },
+        hasRemembered: (id) => remembered.has(id),
+        detach() {
+            detached = true;
+            clearTimer();
+        },
+    };
+    return scope;
+}

package/dist/exec/result/limits.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Every ceiling `--result-schema` is held to (headless-request-scope-and-typed-result
+ * section 4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * STRUCTURE, NOT POLICY. These numbers are what a protocol frame and a
+ * model-visible string can PHYSICALLY carry, not a user preference, so they do not
+ * live in `config.json` and are not tunable per run. That is the same split
+ * `exec/bridge/limits.ts` records for the decision channel, and the same one
+ * `CLAUDE.md` states between a subsystem's `limits.ts` and `config/schema.ts`.
+ *
+ * ONE AUTHORITY PER NUMBER. `diagnostics/info.ts` reads this object rather than
+ * restating the numbers, so a caller that asks "how big may my schema be" gets the
+ * number the validator actually enforces.
+ */
+export declare const RESULT_LIMITS: {
+    /**
+     * One schema file.
+     *
+     * WHY 64 KiB AND NOT THE 256 KiB VALUE CAP: a schema is a HUMAN-AUTHORED
+     * contract that a person reads and reviews; a value is a MACHINE PRODUCT a model
+     * emits. The two have no reason to share a ceiling, and the smaller one is what
+     * keeps `--result-schema` from becoming "paste your whole type system here".
+     */
+    readonly maxSchemaBytes: 65536;
+    /**
+     * Nesting depth of the schema itself.
+     *
+     * 12 is deeper than any contract this feature is for (an object of objects of
+     * arrays of objects is depth 6) and shallow enough that the depth walk in
+     * `schema.ts` cannot be turned into a stack overflow by a hostile file.
+     */
+    readonly maxSchemaDepth: 12;
+    /** `$ref` occurrences. A schema that needs more than 64 is a type system. */
+    readonly maxSchemaRefs: 64;
+    /**
+     * Nodes visited by one validation. Exceeding it REJECTS the value.
+     *
+     * WITHOUT THIS, a deep or wildly wide object makes a headless process spin
+     * inside its own validator - a denial of service the model can trigger by
+     * accident and a caller cannot see. 5000 is far above any real contract.
+     */
+    readonly maxValidationNodes: 5000;
+    /** Violations RETURNED TO THE MODEL, and the width of one path. */
+    readonly maxViolations: 12;
+    readonly maxViolationPathChars: 120;
+    /**
+     * Bytes of the accepted value, after canonicalization.
+     *
+     * `result.result` uses this same number when the value is serialized: a second,
+     * differently sized ceiling would only give the next reader a fork in the road
+     * about which one applies.
+     */
+    readonly maxResultValueBytes: 262144;
+    /** The repair loop: default, hard ceiling, and the message it may produce. */
+    readonly defaultRepairTurns: 1;
+    readonly maxRepairTurns: 2;
+    readonly maxRepairPromptChars: 4000;
+};
+/**
+ * The value's own recursion guard.
+ *
+ * IN `RESULT_LIMITS` WITH EVERY OTHER CEILING (implementation note): the design
+ * listed eight numbers and this is the ninth. It belongs here because it bounds
+ * exactly what `maxValidationNodes` bounds - how much work one untrusted value can
+ * cause - and because a second, differently-placed guard is how two limits end up
+ * disagreeing. 64 is far deeper than any contract (a JSON document from a model
+ * that nests 64 levels is pathological) and shallow enough that the recursive walk
+ * cannot exhaust the stack.
+ */
+export declare const RESULT_MAX_VALUE_DEPTH = 64;
+/** The union of every value in `RESULT_LIMITS`; useful for tests and docs. */
+export type ResultLimits = typeof RESULT_LIMITS;

package/dist/exec/result/limits.js

@@ -0,0 +1,72 @@
+/**
+ * Every ceiling `--result-schema` is held to (headless-request-scope-and-typed-result
+ * section 4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * STRUCTURE, NOT POLICY. These numbers are what a protocol frame and a
+ * model-visible string can PHYSICALLY carry, not a user preference, so they do not
+ * live in `config.json` and are not tunable per run. That is the same split
+ * `exec/bridge/limits.ts` records for the decision channel, and the same one
+ * `CLAUDE.md` states between a subsystem's `limits.ts` and `config/schema.ts`.
+ *
+ * ONE AUTHORITY PER NUMBER. `diagnostics/info.ts` reads this object rather than
+ * restating the numbers, so a caller that asks "how big may my schema be" gets the
+ * number the validator actually enforces.
+ */
+export const RESULT_LIMITS = {
+    /**
+     * One schema file.
+     *
+     * WHY 64 KiB AND NOT THE 256 KiB VALUE CAP: a schema is a HUMAN-AUTHORED
+     * contract that a person reads and reviews; a value is a MACHINE PRODUCT a model
+     * emits. The two have no reason to share a ceiling, and the smaller one is what
+     * keeps `--result-schema` from becoming "paste your whole type system here".
+     */
+    maxSchemaBytes: 65_536,
+    /**
+     * Nesting depth of the schema itself.
+     *
+     * 12 is deeper than any contract this feature is for (an object of objects of
+     * arrays of objects is depth 6) and shallow enough that the depth walk in
+     * `schema.ts` cannot be turned into a stack overflow by a hostile file.
+     */
+    maxSchemaDepth: 12,
+    /** `$ref` occurrences. A schema that needs more than 64 is a type system. */
+    maxSchemaRefs: 64,
+    /**
+     * Nodes visited by one validation. Exceeding it REJECTS the value.
+     *
+     * WITHOUT THIS, a deep or wildly wide object makes a headless process spin
+     * inside its own validator - a denial of service the model can trigger by
+     * accident and a caller cannot see. 5000 is far above any real contract.
+     */
+    maxValidationNodes: 5_000,
+    /** Violations RETURNED TO THE MODEL, and the width of one path. */
+    maxViolations: 12,
+    maxViolationPathChars: 120,
+    /**
+     * Bytes of the accepted value, after canonicalization.
+     *
+     * `result.result` uses this same number when the value is serialized: a second,
+     * differently sized ceiling would only give the next reader a fork in the road
+     * about which one applies.
+     */
+    maxResultValueBytes: 262_144,
+    /** The repair loop: default, hard ceiling, and the message it may produce. */
+    defaultRepairTurns: 1,
+    maxRepairTurns: 2,
+    maxRepairPromptChars: 4_000,
+};
+/**
+ * The value's own recursion guard.
+ *
+ * IN `RESULT_LIMITS` WITH EVERY OTHER CEILING (implementation note): the design
+ * listed eight numbers and this is the ninth. It belongs here because it bounds
+ * exactly what `maxValidationNodes` bounds - how much work one untrusted value can
+ * cause - and because a second, differently-placed guard is how two limits end up
+ * disagreeing. 64 is far deeper than any contract (a JSON document from a model
+ * that nests 64 levels is pathological) and shallow enough that the recursive walk
+ * cannot exhaust the stack.
+ */
+export const RESULT_MAX_VALUE_DEPTH = 64;

package/dist/exec/result/prompt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bumped when the block's WORDING changes in a way an evaluation would notice.
+ *
+ * It is stamped into the block itself, so a transcript shows which instructions the
+ * model was actually given - the difference between "the model ignored it" and "the
+ * model was told something else" is otherwise unanswerable after the fact.
+ */
+export declare const STRUCTURED_RESULT_BLOCK_VERSION = "v1-2026-10";
+export interface StructuredResultBlockOptions {
+    /** `'submit_result'`. A parameter rather than a literal so the two cannot drift. */
+    toolName: string;
+    /** `true` when the caller's schema carried `definitions` / `$defs`. */
+    hasDefinitions: boolean;
+    /** `--result-repair-turns`: how many automatic retries the caller allowed. */
+    repairTurns: number;
+}
+/** The block, or `''` when the caller supplied no schema (I-S1: byte-identical). */
+export declare function buildStructuredResultBlock(options: StructuredResultBlockOptions): string;
+/**
+ * The message the CLI sends on the caller's behalf when a request ended without an
+ * accepted result (section 2.3.5).
+ *
+ * IT QUOTES THE FIELD PATHS, not the whole value: the model already has the value in
+ * its own tool call, and what it does not have is which fields failed. Bounded by
+ * `maxRepairPromptChars` for the reason every model-visible string here is bounded -
+ * an unbounded line would ride into every later provider request.
+ */
+export declare function buildResultRepairMessage(violations: string[], attempts: number): string;

package/dist/exec/result/prompt.js

@@ -0,0 +1,74 @@
+/**
+ * The `<structured_result>` prompt block and the repair message
+ * (headless-request-scope-and-typed-result section 2.3.8).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ONE SOURCE FOR BOTH STRINGS, so the block a model reads and the message it gets
+ * when it ignores the block cannot drift apart. The version constant exists for the
+ * reason every other `*_BLOCK_VERSION` in this package does: a wording change becomes
+ * greppable from a behaviour report instead of an argument.
+ */
+import { RESULT_LIMITS } from './limits.js';
+/**
+ * Bumped when the block's WORDING changes in a way an evaluation would notice.
+ *
+ * It is stamped into the block itself, so a transcript shows which instructions the
+ * model was actually given - the difference between "the model ignored it" and "the
+ * model was told something else" is otherwise unanswerable after the fact.
+ */
+export const STRUCTURED_RESULT_BLOCK_VERSION = 'v1-2026-10';
+/** The block, or `''` when the caller supplied no schema (I-S1: byte-identical). */
+export function buildStructuredResultBlock(options) {
+    const lines = [
+        `<structured_result version="${STRUCTURED_RESULT_BLOCK_VERSION}">`,
+        `Your final answer must be submitted with the \`${options.toolName}\` tool, exactly once.`,
+        `The tool's \`result\` parameter is validated against the schema in its definition; a`,
+        `value that does not match is REJECTED and you get the field paths that failed.`,
+        '',
+        'Rules:',
+        `- Do not also print the answer as prose. The submission IS the answer.`,
+        `- Call \`${options.toolName}\` when you are done, then stop.`,
+        `- If it returns an error, fix the fields it names and call it again with the whole object.`,
+        `- A second successful call changes nothing: the first accepted value is kept.`,
+    ];
+    if (options.repairTurns > 0) {
+        lines.push(`- If you never submit, you will be asked at most ${options.repairTurns} more time(s).`);
+    }
+    else {
+        lines.push('- If you never submit, this run fails: there is no automatic retry.');
+    }
+    lines.push('- If the schema genuinely cannot be satisfied, say why and stop. That is a', '  recognisable failure (`result_schema_unsatisfied`) and is better than prose', '  that looks like success.');
+    if (options.hasDefinitions) {
+        // THE ONE THING A CALLER'S `$ref` NEEDS SAID OUT LOUD. The definitions were
+        // lifted to the parameter schema's root so `#/definitions/X` still resolves; a
+        // model that "helpfully" re-inlines them wastes tokens and risks a mismatch.
+        lines.push('', 'The schema uses `$ref` with `#/definitions/...` or `#/$defs/...`. Those resolve', 'inside the tool definition - do not expand or rewrite them.');
+    }
+    lines.push('</structured_result>');
+    return lines.join('\n');
+}
+/**
+ * The message the CLI sends on the caller's behalf when a request ended without an
+ * accepted result (section 2.3.5).
+ *
+ * IT QUOTES THE FIELD PATHS, not the whole value: the model already has the value in
+ * its own tool call, and what it does not have is which fields failed. Bounded by
+ * `maxRepairPromptChars` for the reason every model-visible string here is bounded -
+ * an unbounded line would ride into every later provider request.
+ */
+export function buildResultRepairMessage(violations, attempts) {
+    const listed = violations.length > 0
+        ? violations.join('\n')
+        : 'result: required (nothing was submitted)';
+    const text = [
+        `Your answer was not submitted as a structured result.`,
+        `Attempts so far: ${attempts}.`,
+        `The last rejection named these fields:`,
+        listed,
+        '',
+        `Fix them and call the submit tool again with the WHOLE object, then stop.`,
+    ].join('\n');
+    const max = RESULT_LIMITS.maxRepairPromptChars;
+    return text.length <= max ? text : `${text.slice(0, max)}\n[truncated]`;
+}