@aragon-agent/cli 0.6.37 → 0.6.39

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

@@ -0,0 +1,99 @@
+/**
+ * The stable `code` values preflight can return (section 2.3.3).
+ *
+ * STABLE BECAUSE A CALLER SWITCHES ON THEM. Renaming one is a breaking change for
+ * every wrapper that gave a different remedy per cause, which is the whole reason
+ * the design split the two that used to share a code.
+ */
+export declare const RESULT_SCHEMA_CODES: {
+    readonly tooLarge: "result_schema_too_large";
+    readonly invalidJson: "result_schema_invalid_json";
+    readonly notObject: "result_schema_not_object";
+    readonly tooDeep: "result_schema_too_deep";
+    readonly unsupportedRef: "result_schema_unsupported_ref";
+    readonly wrapperConflict: "result_schema_wrapper_conflict";
+    readonly compositeRoot: "result_schema_composite_root";
+};
+export type ResultSchemaCode = (typeof RESULT_SCHEMA_CODES)[keyof typeof RESULT_SCHEMA_CODES];
+/** A schema that passed preflight, plus the wrapper it is injected into. */
+export interface ResultSchemaSpec {
+    /** The caller's own schema. Treated as immutable after this point. */
+    schema: Record<string, unknown>;
+    /** `{ type:'object', properties:{ result: schema }, ... }` - what the executor sees. */
+    wrapper: Record<string, unknown>;
+    /** The file name, for echoing back in errors and in `result.structured`. */
+    name: string;
+    bytes: number;
+    /** `true` when the root carried `definitions` / `$defs` that were lifted. */
+    hasDefinitions: boolean;
+}
+export type ResultSchemaParse = {
+    ok: true;
+    spec: ResultSchemaSpec;
+} | {
+    ok: false;
+    code: ResultSchemaCode;
+    message: string;
+};
+/**
+ * Preflight one schema file.
+ *
+ * SIX USAGE ERRORS, ALL OF THEM BEFORE ANY WORK HAPPENS, because a schema that
+ * cannot be honoured must not produce a run that half-honours it. Returns rather
+ * than throws, for the reason `exec/options.ts` states about flags: the caller is a
+ * process that must exit 2 with nothing on stdout.
+ */
+export declare function parseResultSchema(text: string, name: string): ResultSchemaParse;
+/**
+ * The one place the caller's schema becomes a tool parameter schema.
+ *
+ * `definitions` / `$defs` ARE LIFTED TO THE WRAPPER ROOT (section 2.3.2). A
+ * `$ref: "#/definitions/Item"` resolves from the DOCUMENT root, and injecting the
+ * schema under `properties.result` makes the document root the wrapper. Copying the
+ * two containers up leaves every existing `$ref` string resolving to the same
+ * definition - the only option that does not rewrite the caller's text.
+ */
+export declare function buildResultWrapper(schema: Record<string, unknown>): Record<string, unknown>;
+/** One validation run's bounds. Defaults come from `RESULT_LIMITS`, never a literal. */
+export interface CheckLimits {
+    maxNodes: number;
+    maxViolations: number;
+    maxPathChars: number;
+}
+/**
+ * Validate a submitted value against the caller's schema.
+ *
+ * RETURNS VIOLATIONS; AN EMPTY ARRAY MEANS "ACCEPTED". Each string has the stable
+ * shape `result.<path>: <what is wrong>`, because that is what the model has to act
+ * on and what a test can assert without pinning prose.
+ */
+export declare function checkResultValue(schema: Record<string, unknown>, value: unknown, limits?: CheckLimits): string[];
+/**
+ * The one place a violation list becomes model-visible text: one per line.
+ *
+ * ONE PER LINE BECAUSE THAT IS HOW A MODEL READS A LIST OF FIXES, and one function
+ * because the tool's error message and the repair prompt must quote the same shape -
+ * two formatters is how a model ends up being told two different paths for one field.
+ * The list is already bounded by `maxViolations` and each path by `maxPathChars`.
+ */
+export declare function formatResultViolations(violations: string[]): string;
+/**
+ * Round-trip through JSON so the accepted value is exactly what a consumer will
+ * read back (`result.structured.value`) and exactly what gets size-checked.
+ *
+ * `undefined` cannot survive that trip; it is returned as `undefined` rather than
+ * silently becoming `null`, so the caller's own `required` check reports it.
+ */
+export declare function canonicalizeResult(value: unknown): unknown;
+/** Canonicalized byte size, or `Infinity` for a value JSON cannot serialize. */
+export declare function resultValueBytes(value: unknown): number;
+/**
+ * Accept a stringified object when the schema asks for an object (section 9.1).
+ *
+ * A MODEL COMMONLY WRITES THE JSON AS A STRING, and refusing it teaches nothing that
+ * the retry could not teach faster: the alternative is a round trip whose only
+ * content is "unquote it". The tolerance is bounded to a single parse of a value no
+ * larger than the accepted-value ceiling, and it is one-way - a string is only
+ * reinterpreted when the schema says `object` and the parse yields an object.
+ */
+export declare function coerceStringifiedObject(schema: Record<string, unknown>, value: unknown): unknown;

package/dist/exec/result/schema.js

@@ -0,0 +1,464 @@
+/**
+ * `--result-schema`: the preflight, the wrapper, and the belt validator
+ * (headless-request-scope-and-typed-result section 2.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE. No I/O, no timers, no streams: text in, a discriminated result or a list of
+ * readable violations out. Everything that needs the filesystem lives in
+ * `exec/index.ts`, and everything that needs the model lives in `exec/result/tool.ts`.
+ *
+ * ## Why there are two validators, and why this one is not redundant
+ *
+ * `ajv` is an OPTIONAL dependency of Core. `ToolParamValidator` uses it when it can
+ * be imported and otherwise falls back to a strategy that checks `type` at the top
+ * level, checks top-level `required`, and NEVER looks at `properties`, `items`,
+ * `enum`, `const`, the numeric/length bounds, or `additionalProperties:false`
+ * (`packages/core/src/tools/validator.ts`). So on a machine without `ajv`, a schema
+ * pushed into a tool's `parameters` is close to decoration - which is exactly the
+ * machine an embedder is least likely to inspect.
+ *
+ * `checkResultValue` below is therefore the BELT, and the four keywords Core stops
+ * checking are MANDATORY here rather than best-effort: `required`, recursive
+ * `properties`, `items`, and `additionalProperties:false`. The rest it covers where
+ * covering them is cheap. What it does not cover (`pattern`, `format`,
+ * `multipleOf`, ...) is honestly documented as "checked only when `ajv` is present",
+ * and `aragon doctor` reports which machine you are on.
+ *
+ * IT IS ALSO BOUNDED (section 2.3.4): a node budget, a violation cap and a path
+ * width. An unbounded validator inside a headless process is a denial of service
+ * the model can trigger by accident.
+ */
+import { RESULT_LIMITS, RESULT_MAX_VALUE_DEPTH } from './limits.js';
+/**
+ * The stable `code` values preflight can return (section 2.3.3).
+ *
+ * STABLE BECAUSE A CALLER SWITCHES ON THEM. Renaming one is a breaking change for
+ * every wrapper that gave a different remedy per cause, which is the whole reason
+ * the design split the two that used to share a code.
+ */
+export const RESULT_SCHEMA_CODES = {
+    tooLarge: 'result_schema_too_large',
+    invalidJson: 'result_schema_invalid_json',
+    notObject: 'result_schema_not_object',
+    tooDeep: 'result_schema_too_deep',
+    unsupportedRef: 'result_schema_unsupported_ref',
+    wrapperConflict: 'result_schema_wrapper_conflict',
+    compositeRoot: 'result_schema_composite_root',
+};
+/**
+ * Preflight one schema file.
+ *
+ * SIX USAGE ERRORS, ALL OF THEM BEFORE ANY WORK HAPPENS, because a schema that
+ * cannot be honoured must not produce a run that half-honours it. Returns rather
+ * than throws, for the reason `exec/options.ts` states about flags: the caller is a
+ * process that must exit 2 with nothing on stdout.
+ */
+export function parseResultSchema(text, name) {
+    const bytes = Buffer.byteLength(text, 'utf-8');
+    if (bytes > RESULT_LIMITS.maxSchemaBytes) {
+        return fail(RESULT_SCHEMA_CODES.tooLarge, `${name} is ${bytes} bytes; a result schema may be at most ${RESULT_LIMITS.maxSchemaBytes}.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return fail(RESULT_SCHEMA_CODES.invalidJson, `${name} is not JSON: ${firstLine(err.message)}`);
+    }
+    if (!isPlainObject(parsed)) {
+        return fail(RESULT_SCHEMA_CODES.notObject, `${name} must contain a JSON object at the root; found ${describeType(parsed)}.`);
+    }
+    const schema = parsed;
+    const depth = schemaDepth(schema);
+    if (depth > RESULT_LIMITS.maxSchemaDepth) {
+        return fail(RESULT_SCHEMA_CODES.tooDeep, `${name} nests ${depth} levels deep; the limit is ${RESULT_LIMITS.maxSchemaDepth}.`);
+    }
+    const ref = findUnsupportedRef(schema);
+    if (ref !== null)
+        return fail(RESULT_SCHEMA_CODES.unsupportedRef, `${name}: ${ref}`);
+    const properties = isPlainObject(schema.properties) ? schema.properties : {};
+    if (Object.prototype.hasOwnProperty.call(properties, 'result')) {
+        // THE WRAPPER AND THE CALLER WANT THE SAME KEY. Our wrapper puts the whole
+        // schema under `properties.result`, so a root that already declares a `result`
+        // property would be silently nested one level deeper than the caller wrote it.
+        // Renaming it for them would change their contract; refusing is the honest
+        // answer, and the remedy is one edit away (`items`, or another key name).
+        return fail(RESULT_SCHEMA_CODES.wrapperConflict, `${name}: the root already declares a "result" property (at /properties/result). ` +
+            'Rename it, or wrap the object in an "items" array.');
+    }
+    const composite = ['oneOf', 'anyOf', 'allOf'].find((key) => key in schema);
+    if (composite !== undefined) {
+        // INLINING A COMPOSED ROOT IS NOT SAFE HERE: `properties.result` would hold a
+        // schema whose own combinators no longer mean what they meant at the document
+        // root (sibling keywords interact differently). A caller that needs a union can
+        // put it under a property, where it is preserved verbatim.
+        return fail(RESULT_SCHEMA_CODES.compositeRoot, `${name}: the root uses "${composite}", which cannot be inlined safely. ` +
+            'Move the composition under a property.');
+    }
+    const hasDefinitions = 'definitions' in schema || '$defs' in schema;
+    return {
+        ok: true,
+        spec: { schema, wrapper: buildResultWrapper(schema), name, bytes, hasDefinitions },
+    };
+}
+/**
+ * The one place the caller's schema becomes a tool parameter schema.
+ *
+ * `definitions` / `$defs` ARE LIFTED TO THE WRAPPER ROOT (section 2.3.2). A
+ * `$ref: "#/definitions/Item"` resolves from the DOCUMENT root, and injecting the
+ * schema under `properties.result` makes the document root the wrapper. Copying the
+ * two containers up leaves every existing `$ref` string resolving to the same
+ * definition - the only option that does not rewrite the caller's text.
+ */
+export function buildResultWrapper(schema) {
+    const wrapper = {
+        type: 'object',
+        properties: { result: schema },
+        required: ['result'],
+        // THE WRAPPER LAYER ONLY. "The model sent an extra key" should be refused rather
+        // than ignored, and our own belt enforces this even where Core's fallback does
+        // not (see the file header).
+        additionalProperties: false,
+    };
+    if (isPlainObject(schema.definitions))
+        wrapper.definitions = schema.definitions;
+    if (isPlainObject(schema.$defs))
+        wrapper.$defs = schema.$defs;
+    return wrapper;
+}
+const DEFAULT_CHECK_LIMITS = {
+    maxNodes: RESULT_LIMITS.maxValidationNodes,
+    maxViolations: RESULT_LIMITS.maxViolations,
+    maxPathChars: RESULT_LIMITS.maxViolationPathChars,
+};
+/**
+ * Validate a submitted value against the caller's schema.
+ *
+ * RETURNS VIOLATIONS; AN EMPTY ARRAY MEANS "ACCEPTED". Each string has the stable
+ * shape `result.<path>: <what is wrong>`, because that is what the model has to act
+ * on and what a test can assert without pinning prose.
+ */
+export function checkResultValue(schema, value, limits = DEFAULT_CHECK_LIMITS) {
+    const ctx = { ...limits, nodes: 0, violations: [], overflowed: false };
+    checkNode(schema, value, 'result', ctx, 0);
+    return ctx.violations;
+}
+/**
+ * The one place a violation list becomes model-visible text: one per line.
+ *
+ * ONE PER LINE BECAUSE THAT IS HOW A MODEL READS A LIST OF FIXES, and one function
+ * because the tool's error message and the repair prompt must quote the same shape -
+ * two formatters is how a model ends up being told two different paths for one field.
+ * The list is already bounded by `maxViolations` and each path by `maxPathChars`.
+ */
+export function formatResultViolations(violations) {
+    return violations.join('\n');
+}
+/**
+ * Round-trip through JSON so the accepted value is exactly what a consumer will
+ * read back (`result.structured.value`) and exactly what gets size-checked.
+ *
+ * `undefined` cannot survive that trip; it is returned as `undefined` rather than
+ * silently becoming `null`, so the caller's own `required` check reports it.
+ */
+export function canonicalizeResult(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return value;
+    }
+}
+/** Canonicalized byte size, or `Infinity` for a value JSON cannot serialize. */
+export function resultValueBytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf-8');
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/**
+ * Accept a stringified object when the schema asks for an object (section 9.1).
+ *
+ * A MODEL COMMONLY WRITES THE JSON AS A STRING, and refusing it teaches nothing that
+ * the retry could not teach faster: the alternative is a round trip whose only
+ * content is "unquote it". The tolerance is bounded to a single parse of a value no
+ * larger than the accepted-value ceiling, and it is one-way - a string is only
+ * reinterpreted when the schema says `object` and the parse yields an object.
+ */
+export function coerceStringifiedObject(schema, value) {
+    if (typeof value !== 'string' || schemaWants(schema, 'object') !== true)
+        return value;
+    if (Buffer.byteLength(value, 'utf-8') > RESULT_LIMITS.maxResultValueBytes)
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{'))
+        return value;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isPlainObject(parsed) ? parsed : value;
+    }
+    catch {
+        return value;
+    }
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function fail(code, message) {
+    return { ok: false, code, message };
+}
+function firstLine(message) {
+    const line = message.split('\n')[0] ?? message;
+    return line.length <= 160 ? line : `${line.slice(0, 157)}...`;
+}
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Nesting depth of a schema document; a scalar is depth 1. */
+function schemaDepth(value, depth = 1) {
+    if (depth > RESULT_LIMITS.maxSchemaDepth + 1)
+        return depth;
+    if (Array.isArray(value)) {
+        let deepest = depth;
+        for (const item of value)
+            deepest = Math.max(deepest, schemaDepth(item, depth + 1));
+        return deepest;
+    }
+    if (!isPlainObject(value))
+        return depth;
+    let deepest = depth;
+    for (const key of Object.keys(value)) {
+        deepest = Math.max(deepest, schemaDepth(value[key], depth + 1));
+    }
+    return deepest;
+}
+/**
+ * Walk every string in the document looking for `$ref` values (and counting them).
+ *
+ * Returns a readable complaint, or `null`. Only local pointer prefixes are allowed,
+ * because a remote `$ref` would make a schema silently depend on the network - and a
+ * headless run must never fetch a contract it was handed.
+ */
+function findUnsupportedRef(schema) {
+    const refs = [];
+    collectRefs(schema, refs);
+    if (refs.length > RESULT_LIMITS.maxSchemaRefs) {
+        return `${refs.length} "$ref" values; the limit is ${RESULT_LIMITS.maxSchemaRefs}.`;
+    }
+    for (const ref of refs) {
+        const local = ref.startsWith('#/definitions/') || ref.startsWith('#/$defs/');
+        if (!local) {
+            return `"$ref": "${clipText(ref, 120)}" must start with "#/definitions/" or "#/$defs/".`;
+        }
+    }
+    return null;
+}
+function collectRefs(value, out, depth = 0) {
+    if (depth > RESULT_LIMITS.maxSchemaDepth + 1)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefs(item, out, depth + 1);
+        return;
+    }
+    if (!isPlainObject(value))
+        return;
+    const ref = value.$ref;
+    if (typeof ref === 'string')
+        out.push(ref);
+    for (const key of Object.keys(value))
+        collectRefs(value[key], out, depth + 1);
+}
+function clipText(text, max) {
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+/** Does a `type` keyword (string or array) name `wanted`? */
+function schemaWants(schema, wanted) {
+    const type = schema.type;
+    if (typeof type === 'string')
+        return type === wanted;
+    if (Array.isArray(type))
+        return type.includes(wanted);
+    return undefined;
+}
+function checkNode(schema, value, path, ctx, depth) {
+    if (!isPlainObject(schema))
+        return;
+    ctx.nodes += 1;
+    if (ctx.nodes > ctx.maxNodes) {
+        // ONE VIOLATION, THEN SILENCE. The point is a readable refusal, not a list of
+        // five thousand copies of it.
+        if (!ctx.overflowed) {
+            ctx.overflowed = true;
+            push(ctx, `${clipPath('result', ctx)}: the submitted value is too complex to validate`);
+        }
+        return;
+    }
+    // A STACK GUARD, NOT A RULE.
+    // It is unreachable for any schema that passes preflight - the walk descends only
+    // through `properties` and `items`, so value depth is bounded by schema depth (12)
+    // long before 64 - and it exists so that a future keyword which recurses WITHOUT
+    // a matching schema level cannot turn one hostile value into a stack overflow.
+    if (depth > RESULT_MAX_VALUE_DEPTH)
+        return;
+    if (ctx.violations.length >= ctx.maxViolations)
+        return;
+    if (!matchesType(schema, value)) {
+        push(ctx, `${clipPath(path, ctx)}: expected ${describeSchemaTypes(schema)}, got ${describeType(value)}`);
+        return;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((allowed) => deepEqual(allowed, value))) {
+        push(ctx, `${clipPath(path, ctx)}: must be one of ${describeEnum(schema.enum)}`);
+    }
+    if ('const' in schema && !deepEqual(schema.const, value)) {
+        push(ctx, `${clipPath(path, ctx)}: must equal ${describeEnum([schema.const])}`);
+    }
+    checkStringBounds(schema, value, path, ctx);
+    checkNumberBounds(schema, value, path, ctx);
+    checkObjectShape(schema, value, path, ctx, depth);
+    checkArrayShape(schema, value, path, ctx, depth);
+}
+function matchesType(schema, value) {
+    const type = schema.type;
+    if (type === undefined)
+        return true;
+    const names = Array.isArray(type) ? type : [type];
+    // `some`, never `every`: `type: ['string', 'null']` is a union, which is how every
+    // schema author reads it. An unknown type name matches nothing, so a future
+    // keyword this build does not know cannot silently accept everything.
+    return names.some((name) => matchesOneType(name, value));
+}
+function matchesOneType(name, value) {
+    if (name === 'object')
+        return isPlainObject(value);
+    if (name === 'array')
+        return Array.isArray(value);
+    if (name === 'null')
+        return value === null;
+    if (name === 'integer')
+        return typeof value === 'number' && Number.isInteger(value);
+    if (name === 'number')
+        return typeof value === 'number' && Number.isFinite(value);
+    if (name === 'string')
+        return typeof value === 'string';
+    if (name === 'boolean')
+        return typeof value === 'boolean';
+    return false;
+}
+function describeSchemaTypes(schema) {
+    const type = schema.type;
+    if (typeof type === 'string')
+        return type;
+    if (Array.isArray(type))
+        return type.map((item) => String(item)).join(' | ');
+    return 'any';
+}
+function describeEnum(values) {
+    const shown = values.slice(0, 6).map((item) => clipText(JSON.stringify(item) ?? 'null', 40));
+    return shown.join(', ') + (values.length > 6 ? ', ...' : '');
+}
+function checkStringBounds(schema, value, path, ctx) {
+    if (typeof value !== 'string')
+        return;
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+        push(ctx, `${clipPath(path, ctx)}: length ${value.length} is below minLength ${schema.minLength}`);
+    }
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+        push(ctx, `${clipPath(path, ctx)}: length ${value.length} is above maxLength ${schema.maxLength}`);
+    }
+}
+function checkNumberBounds(schema, value, path, ctx) {
+    if (typeof value !== 'number')
+        return;
+    if (typeof schema.minimum === 'number' && value < schema.minimum) {
+        push(ctx, `${clipPath(path, ctx)}: ${value} is below minimum ${schema.minimum}`);
+    }
+    if (typeof schema.maximum === 'number' && value > schema.maximum) {
+        push(ctx, `${clipPath(path, ctx)}: ${value} is above maximum ${schema.maximum}`);
+    }
+}
+function checkObjectShape(schema, value, path, ctx, depth) {
+    if (!isPlainObject(value))
+        return;
+    const properties = isPlainObject(schema.properties) ? schema.properties : {};
+    if (Array.isArray(schema.required)) {
+        for (const key of schema.required) {
+            if (typeof key !== 'string')
+                continue;
+            if (value[key] === undefined)
+                push(ctx, `${clipPath(`${path}.${key}`, ctx)}: required`);
+        }
+    }
+    for (const key of Object.keys(properties)) {
+        if (value[key] === undefined)
+            continue;
+        checkNode(properties[key], value[key], `${path}.${key}`, ctx, depth + 1);
+    }
+    if (schema.additionalProperties === false) {
+        for (const key of Object.keys(value)) {
+            if (Object.prototype.hasOwnProperty.call(properties, key))
+                continue;
+            push(ctx, `${clipPath(`${path}.${key}`, ctx)}: not allowed (additionalProperties is false)`);
+        }
+    }
+}
+function checkArrayShape(schema, value, path, ctx, depth) {
+    if (!Array.isArray(value))
+        return;
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+        push(ctx, `${clipPath(path, ctx)}: ${value.length} items is below minItems ${schema.minItems}`);
+    }
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+        push(ctx, `${clipPath(path, ctx)}: ${value.length} items is above maxItems ${schema.maxItems}`);
+    }
+    // The single-schema form only. A tuple (`items: [...]`) is checked by `ajv` when it
+    // is present; implementing it here would be a second dialect, not a safety net.
+    if (!isPlainObject(schema.items))
+        return;
+    const itemsSchema = schema.items;
+    for (let index = 0; index < value.length; index += 1) {
+        if (ctx.violations.length >= ctx.maxViolations)
+            return;
+        checkNode(itemsSchema, value[index], `${path}[${index}]`, ctx, depth + 1);
+    }
+}
+function push(ctx, violation) {
+    if (ctx.violations.length >= ctx.maxViolations)
+        return;
+    ctx.violations.push(violation);
+}
+function clipPath(path, ctx) {
+    return clipText(path, ctx.maxPathChars);
+}
+/** Structural equality for `enum` / `const`, ordered keys included. */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const left = Object.keys(a);
+        const right = Object.keys(b);
+        if (left.length !== right.length)
+            return false;
+        return left.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * The result box: one value, written by the tool, read by the runner
+ * (headless-request-scope-and-typed-result section 2.3.5 / 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ONE WRITER, ONE READER, ONE RESET POINT. `submit_result.execute` is the only
+ * writer, `ExecRunner.checkResultComplete` and the `result` event are the readers,
+ * and `runner.run()`'s request loop calls `reset()` between `scope.begin()` and
+ * `controller.prompt()`. That last sentence is the important one: resetting at the
+ * END of a request instead would let a tool call that settles one tick late land its
+ * value in the NEXT request, which is a defect that costs a day to find and two
+ * lines to prevent.
+ *
+ * SINGLE ASSIGNMENT (I-S3). A later `accept` is IGNORED, never an overwrite: the
+ * model calling `submit_result` twice is doing what the prompt told it not to, and
+ * the accepted answer must be the one the caller is entitled to - the first.
+ */
+/** What was accepted, and enough provenance to explain it afterwards. */
+export interface ResultAcceptance {
+    value: unknown;
+    /** `submit_result` calls that preceded acceptance, including the accepted one. */
+    attempts: number;
+    /** Core's tool-call id, so a transcript can be joined to the event stream. */
+    callId: string;
+    acceptedAt: number;
+}
+export interface ResultSink {
+    /**
+     * Record the accepted value. Ignored when one is already accepted, and the caller
+     * must NOT treat that as a failure: a second call is answered with a success
+     * result precisely so the model stops instead of retrying (I-S3).
+     */
+    accept(value: unknown, meta: {
+        attempts: number;
+        callId: string;
+    }): void;
+    /** The accepted value, or `null` while nothing has been accepted. */
+    accepted(): ResultAcceptance | null;
+    /** Count one attempt and return the running total. */
+    noteAttempt(): number;
+    /** Remember the last rejection so the repair message can quote it. */
+    noteViolations(violations: string[]): void;
+    lastViolations(): string[];
+    /** Attempts in the current request. */
+    attempts(): number;
+    /** THE ONLY RESET POINT - see the file header. */
+    reset(): void;
+}
+export interface ResultSinkOptions {
+    /** Injected so a test never touches the real clock. */
+    now: () => number;
+}
+export declare function createResultSink(options: ResultSinkOptions): ResultSink;
+/** The members the runner depends on; a narrower type keeps the port honest. */
+export type ResultSinkReader = Pick<ResultSink, 'accepted' | 'lastViolations' | 'attempts' | 'reset'>;

package/dist/exec/result/sink.js

@@ -0,0 +1,50 @@
+/**
+ * The result box: one value, written by the tool, read by the runner
+ * (headless-request-scope-and-typed-result section 2.3.5 / 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ONE WRITER, ONE READER, ONE RESET POINT. `submit_result.execute` is the only
+ * writer, `ExecRunner.checkResultComplete` and the `result` event are the readers,
+ * and `runner.run()`'s request loop calls `reset()` between `scope.begin()` and
+ * `controller.prompt()`. That last sentence is the important one: resetting at the
+ * END of a request instead would let a tool call that settles one tick late land its
+ * value in the NEXT request, which is a defect that costs a day to find and two
+ * lines to prevent.
+ *
+ * SINGLE ASSIGNMENT (I-S3). A later `accept` is IGNORED, never an overwrite: the
+ * model calling `submit_result` twice is doing what the prompt told it not to, and
+ * the accepted answer must be the one the caller is entitled to - the first.
+ */
+export function createResultSink(options) {
+    let accepted = null;
+    let attempts = 0;
+    let violations = [];
+    return {
+        accept(value, meta) {
+            if (accepted)
+                return;
+            accepted = {
+                value,
+                attempts: meta.attempts,
+                callId: meta.callId,
+                acceptedAt: options.now(),
+            };
+        },
+        accepted: () => accepted,
+        noteAttempt() {
+            attempts += 1;
+            return attempts;
+        },
+        noteViolations(next) {
+            violations = [...next];
+        },
+        lastViolations: () => [...violations],
+        attempts: () => attempts,
+        reset() {
+            accepted = null;
+            attempts = 0;
+            violations = [];
+        },
+    };
+}