@gaunt-sloth/core 2.0.0-alpha.26 → 2.0.0-alpha.28

package/dist/runtime/structuredOutput.js

@@ -0,0 +1,393 @@
+/**
+ * @module runtime/structuredOutput
+ *
+ * EXT-88 — the **`withStructuredOutput` boundary**. Every `withStructuredOutput` call in this
+ * project goes through {@link structuredOutputBoundary}: `rateShellCommand` (the approvals rater),
+ * {@link askStructured} (arbitrary caller schemas, including `gth workflow` scripts) and
+ * `@gaunt-sloth/batch`'s eval judge. Review's rating step is deliberately not one of them — it
+ * reaches its schema through a bound TOOL, which is a different path with different rules.
+ *
+ * ## The problem it exists to solve
+ *
+ * A single Zod object normally does two jobs at once — it is converted into the JSON Schema the
+ * provider is sent, and it validates the answer that comes back. Those two jobs want **opposite**
+ * things from an optional field, and Zod has only one knob for both:
+ *
+ * - **On the wire**, OpenAI's strict `json_schema` rule is *"`required` must be supplied and must
+ *   include every key in `properties`"*. A `.optional()` field is left out of `required`, and the
+ *   OpenAI API rejects the whole request with `400 Invalid schema for response_format`. Optionality
+ *   there is spelled as a **nullable type on a required key**, not as an absent key.
+ * - **On the way back**, providers do not agree. Some (ChatGroq) rewrite the schema themselves so
+ *   every property is required-and-nullable, and their models answer `null`. Others (Anthropic,
+ *   Google GenAI, Ollama) leave the field genuinely optional and their models may simply omit it.
+ *   Zod's `.optional()` admits `undefined` and **not** `null`, so the first group's answer is
+ *   rejected by the very schema that asked for it — and the caller sees a parse failure that looks
+ *   like a bad model rather than a self-contradicting request.
+ *
+ * ## The shape that satisfies both
+ *
+ * For every field the caller declared `.optional()`, the boundary sends
+ * `inner.nullable().prefault(null)` instead. That one node is the wire/validation twin:
+ *
+ * - **Wire** — `prefault` does not change the parsed *output* type, so the key lands in `required`
+ *   and its type is `["string","null"]` / `anyOf: [T, null]`. Strict mode is satisfied, and the
+ *   model is given a legal way to say "nothing here". Unlike `.default()`, `prefault` emits **no
+ *   `default` keyword** into the JSON Schema, so nothing extra is added to what the provider sees.
+ * - **Validation** — the same node accepts the value, accepts `null`, and accepts the key being
+ *   **missing** (which is what `prefault` supplies the `null` for). All three arms are needed: the
+ *   third is what keeps the providers that do *not* hoist working.
+ *
+ * The `null` never escapes: {@link StructuredOutputBoundary.safeParse} strips it back to the key
+ * being **absent** and then validates with the caller's **original** schema, so the parsed type is
+ * exactly what the caller declared — an optional string stays `string | undefined` and never
+ * becomes `string | null | undefined`.
+ *
+ * ## Two properties that must not be lost in a "simplification"
+ *
+ * - **Every `.describe()` survives into the emitted JSON Schema.** The descriptions are the only
+ *   place the model is told what the fields mean. Expressing the null-to-absent step with
+ *   `.transform()` on the field is the obvious-looking alternative and it costs the field its
+ *   description — worse, the conversion OpenAI's path uses refuses to represent a transform at all.
+ *   Normalization therefore happens in **code**, after the parse, never in the schema.
+ * - **A genuinely malformed answer still fails.** This boundary removes a *false* parse failure; it
+ *   is not a blanket "accept anything". A wrong type in an optional field is still rejected, because
+ *   the final validation is the caller's own untouched schema. In particular `.catch()` must not be
+ *   used to express any of this — it would swallow real failures.
+ *
+ * ## Coverage, and the deliberate limits
+ *
+ * The rewrite descends through objects, arrays, tuples, records and the single-child wrappers
+ * (`nullable`, `readonly`, `default`, `prefault`, `nonoptional`), so an optional nested inside an
+ * object inside an array is handled.
+ *
+ * It deliberately stops at **unions** (including discriminated unions), **intersections**, `lazy`,
+ * `map`, `set`, `pipe`/`transform` and `custom`, leaving those subtrees exactly as the caller wrote
+ * them, and it leaves a **recursive** schema alone in its entirety. The reason is one rule: the
+ * rewrite and the normalization must cover **precisely the same set**. At a union the incoming value
+ * gives no reliable answer to *which branch was taken*, so a `null` could not be stripped back out;
+ * rewriting there while being unable to normalize would manufacture the very parse failure this
+ * module removes. Recursion is refused for the neighbouring reason — a rewrite that stopped at the
+ * cycle would make a key required at one depth and optional at the next, which satisfies no
+ * provider's strict rule and is harder to reason about than the caller's own schema.
+ *
+ * An optional inside one of those constructs keeps today's behaviour — correct everywhere it is
+ * correct today, and still rejected by OpenAI's strict rule, which is a visible error rather than a
+ * silent one.
+ */
+import * as z from 'zod';
+/**
+ * A normalizer's answer for "this key must not be present at all" — distinct from `undefined`,
+ * because an object key explicitly set to `undefined` is still an own property and `Object.hasOwn`
+ * would report it. Callers must not have to learn a second spelling of "absent".
+ */
+const ABSENT = Symbol('structured-output-absent');
+function defOf(schema) {
+    return schema._zod.def;
+}
+/**
+ * Rebuild `schema` with part of its definition replaced, keeping everything else — the checks
+ * (`minItems`, `minimum`, …) and the registered `.describe()` metadata. Built from Zod's own clone
+ * rather than by calling `z.object(...)` / `z.array(...)` afresh, because re-constructing would
+ * silently drop those constraints from the schema the provider is sent.
+ *
+ * The metadata is copied through the registry rather than by cloning with Zod's `parent` option.
+ * A parent link is how Zod represents "the same schema, re-described", and its JSON-Schema emitter
+ * honours that by emitting a **`$ref` to the parent** with the differences as sibling keys. For a
+ * rewritten object that is actively wrong: the `$ref` would point at a definition still carrying the
+ * ORIGINAL `required` list — the one missing exactly the optional key this module exists to hoist —
+ * and `$ref`-with-siblings is not accepted by every provider's strict mode. Copying the metadata
+ * leaves the clone an independent schema, which is what it actually is.
+ */
+function cloneWith(schema, patch) {
+    const next = { ...defOf(schema), ...patch };
+    const cloned = z.core.clone(schema, next);
+    const meta = z.globalRegistry.get(schema);
+    if (meta)
+        z.globalRegistry.add(cloned, meta);
+    return cloned;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * `.optional()` → `inner.nullable().prefault(null)`, plus the normalizer that puts it back.
+ *
+ * The description is re-stated on the nullable wrapper so it lands at **field level** in the emitted
+ * JSON Schema whichever way the caller spelled it (`z.string().describe(D).optional()` carries it on
+ * the inner type, `z.string().optional().describe(D)` on the wrapper).
+ *
+ * `null` is only stripped where the caller's own declaration gives it no meaning. A field written
+ * `z.string().nullable().optional()` asked for `null` to be a value in its own right, so it keeps
+ * it; only a plain `.optional()`, for which `null` was never a legal answer and can only have come
+ * from the required-and-nullable rewrite, collapses to the key being absent.
+ */
+function walkOptional(schema, def) {
+    const inner = def.innerType;
+    const innerWalk = walk(inner);
+    const description = schema.description ?? inner.description;
+    const nullIsMeaningful = inner.safeParse(null).success;
+    // A field that already admits `null` needs no second nullable wrapper — one would emit a nested
+    // `anyOf` inside an `anyOf` that says nothing the inner one does not.
+    let nullable = nullIsMeaningful ? innerWalk.schema : innerWalk.schema.nullable();
+    if (description !== undefined)
+        nullable = nullable.describe(description);
+    const wireSchema = nullable.prefault(null);
+    const innerNormalize = innerWalk.normalize;
+    const normalize = (value) => {
+        if (value === undefined)
+            return ABSENT;
+        if (value === null)
+            return nullIsMeaningful ? null : ABSENT;
+        return innerNormalize ? innerNormalize(value) : value;
+    };
+    return { schema: wireSchema, normalize };
+}
+function walkObject(schema, def) {
+    const shape = def.shape ?? {};
+    const nextShape = {};
+    const normalizers = [];
+    let changed = false;
+    for (const [key, field] of Object.entries(shape)) {
+        const result = walk(field);
+        nextShape[key] = result.schema;
+        if (result.schema !== field)
+            changed = true;
+        if (result.normalize)
+            normalizers.push([key, result.normalize]);
+    }
+    if (!changed && normalizers.length === 0)
+        return { schema };
+    const normalize = (value) => {
+        if (!isRecord(value))
+            return value;
+        const out = { ...value };
+        for (const [key, normalizeField] of normalizers) {
+            if (!Object.hasOwn(out, key))
+                continue;
+            const normalized = normalizeField(out[key]);
+            if (normalized === ABSENT)
+                delete out[key];
+            else
+                out[key] = normalized;
+        }
+        return out;
+    };
+    return { schema: changed ? cloneWith(schema, { shape: nextShape }) : schema, normalize };
+}
+function walkArray(schema, def) {
+    const element = def.element;
+    const result = walk(element);
+    if (result.schema === element && !result.normalize)
+        return { schema };
+    const normalizeElement = result.normalize;
+    const normalize = normalizeElement
+        ? (value) => {
+            if (!Array.isArray(value))
+                return value;
+            return value.map((item) => {
+                const normalized = normalizeElement(item);
+                // An element position has no key to remove, so "absent" degrades to `undefined` — which
+                // is what an optional element schema accepts anyway.
+                return normalized === ABSENT ? undefined : normalized;
+            });
+        }
+        : undefined;
+    return {
+        schema: result.schema === element ? schema : cloneWith(schema, { element: result.schema }),
+        normalize,
+    };
+}
+function walkTuple(schema, def) {
+    const items = def.items ?? [];
+    const rest = def.rest ?? null;
+    const itemResults = items.map((item) => walk(item));
+    const restResult = rest ? walk(rest) : undefined;
+    const changed = itemResults.some((result, index) => result.schema !== items[index]) ||
+        (restResult !== undefined && rest !== null && restResult.schema !== rest);
+    const needsNormalize = itemResults.some((result) => result.normalize) || restResult?.normalize !== undefined;
+    if (!changed && !needsNormalize)
+        return { schema };
+    const normalize = needsNormalize
+        ? (value) => {
+            if (!Array.isArray(value))
+                return value;
+            return value.map((item, index) => {
+                // Gate on POSITION: a prefix item is normalized by its own item schema and never by the
+                // rest schema, which describes a different position entirely.
+                const normalizeItem = index < items.length ? itemResults[index]?.normalize : restResult?.normalize;
+                if (!normalizeItem)
+                    return item;
+                const normalized = normalizeItem(item);
+                return normalized === ABSENT ? undefined : normalized;
+            });
+        }
+        : undefined;
+    return {
+        schema: changed
+            ? cloneWith(schema, {
+                items: itemResults.map((result) => result.schema),
+                rest: restResult ? restResult.schema : rest,
+            })
+            : schema,
+        normalize,
+    };
+}
+function walkRecord(schema, def) {
+    const valueType = def.valueType;
+    const result = walk(valueType);
+    if (result.schema === valueType && !result.normalize)
+        return { schema };
+    const normalizeValue = result.normalize;
+    const normalize = normalizeValue
+        ? (value) => {
+            if (!isRecord(value))
+                return value;
+            const out = {};
+            for (const [key, item] of Object.entries(value)) {
+                const normalized = normalizeValue(item);
+                if (normalized !== ABSENT)
+                    out[key] = normalized;
+            }
+            return out;
+        }
+        : undefined;
+    return {
+        schema: result.schema === valueType ? schema : cloneWith(schema, { valueType: result.schema }),
+        normalize,
+    };
+}
+/**
+ * The single-child wrappers: `nullable`, `readonly`, `default`, `prefault`, `nonoptional`.
+ *
+ * A wrapper is **transparent to optionality**. `z.string().optional().default('foo')` is still sent
+ * as a required key typed `anyOf: [T, null]`, so a `null` arriving here is the wire's "nothing here"
+ * and must reach the inner normalizer that knows how to remove it. Passing every `null` straight
+ * through instead would advertise `null` to the provider and then reject the one it sends — the same
+ * self-contradiction this module exists to remove, one wrapper deep. What "absent" then means is the
+ * caller's own business, because the final validation is the caller's untouched schema: under
+ * `.default('foo')` it resolves to `'foo'`, under `.readonly()` the key simply stays absent.
+ *
+ * The exception is a wrapper that makes `null` a value in its own right — the caller wrote
+ * `.nullable()` **outside** the optional. That is the question {@link walkOptional} asks of its own
+ * inner type, asked one level up, and it is what keeps the two spellings of nullable-and-optional
+ * from disagreeing about the same field.
+ *
+ * `undefined` is passed through rather than being given a second meaning here: the wire never
+ * produces one (`prefault` supplies `null` for a missing key), and a genuinely missing object key
+ * never reaches a field normalizer at all — {@link walkObject} skips it.
+ */
+function walkWrapper(schema, def) {
+    const inner = def.innerType;
+    const result = walk(inner);
+    if (result.schema === inner && !result.normalize)
+        return { schema };
+    const innerNormalize = result.normalize;
+    const nullIsMeaningful = innerNormalize !== undefined && schema.safeParse(null).success;
+    const normalize = innerNormalize
+        ? (value) => {
+            if (value === undefined)
+                return value;
+            if (value === null && nullIsMeaningful)
+                return null;
+            return innerNormalize(value);
+        }
+        : undefined;
+    return {
+        schema: result.schema === inner ? schema : cloneWith(schema, { innerType: result.schema }),
+        normalize,
+    };
+}
+/**
+ * Thrown when the walk re-enters a schema it is already inside, i.e. the caller's schema is
+ * recursive. Caught in {@link structuredOutputBoundary}, which then leaves the whole schema alone —
+ * see the module doc's limits.
+ */
+const CYCLIC = Symbol('structured-output-cyclic');
+/** The schemas the current walk is inside. A node reached twice on one path is a cycle. */
+const inProgress = new WeakSet();
+/**
+ * Rewrite one node. Every branch here has a matching arm in the normalizer it returns — the two
+ * halves are produced by the **same** walk precisely so their coverage cannot drift apart. Anything
+ * not listed is returned untouched, with no normalizer.
+ *
+ * A **recursive** schema aborts the whole walk rather than being partly rewritten. Zod spells
+ * recursion as a getter in an object's shape, which reads as an ordinary `object` here and would
+ * otherwise descend for ever. Rewriting only the levels reached before the cycle would put an
+ * optional key in `required` at one depth and leave it out at the next — an inconsistency that
+ * satisfies no provider's strict rule while making the emitted schema harder to reason about than
+ * the caller's own.
+ */
+function walk(schema) {
+    if (inProgress.has(schema))
+        throw CYCLIC;
+    inProgress.add(schema);
+    try {
+        return walkNode(schema);
+    }
+    finally {
+        inProgress.delete(schema);
+    }
+}
+function walkNode(schema) {
+    const def = defOf(schema);
+    switch (def.type) {
+        case 'optional':
+            return walkOptional(schema, def);
+        case 'object':
+            return walkObject(schema, def);
+        case 'array':
+            return walkArray(schema, def);
+        case 'tuple':
+            return walkTuple(schema, def);
+        case 'record':
+            return walkRecord(schema, def);
+        case 'nullable':
+        case 'readonly':
+        case 'default':
+        case 'prefault':
+        case 'nonoptional':
+            return walkWrapper(schema, def);
+        default:
+            return { schema };
+    }
+}
+/**
+ * Memoized per schema instance. Repeated calls with the same schema — the common case, since call
+ * sites hold a module-level schema constant — return the same `wireSchema` reference, which is what
+ * LangChain's own JSON-Schema conversion cache is keyed on.
+ */
+const boundaries = new WeakMap();
+/**
+ * Build the {@link StructuredOutputBoundary} for a schema — the one entry point every
+ * `withStructuredOutput` call in this project goes through. See the module doc for what it does and
+ * why.
+ *
+ * @param schema The caller's schema, used unchanged for the final validation.
+ */
+export function structuredOutputBoundary(schema) {
+    const cached = boundaries.get(schema);
+    if (cached)
+        return cached;
+    let walked;
+    try {
+        walked = walk(schema);
+    }
+    catch (error) {
+        // A recursive schema is left exactly as the caller wrote it — the same answer this module gives
+        // for a union, and for the same reason: it will not rewrite what it cannot also normalize.
+        if (error !== CYCLIC)
+            throw error;
+        walked = { schema: schema };
+    }
+    const normalize = walked.normalize;
+    const boundary = {
+        wireSchema: walked.schema,
+        safeParse(raw) {
+            const normalized = normalize ? normalize(raw) : raw;
+            return schema.safeParse(normalized === ABSENT ? undefined : normalized);
+        },
+    };
+    boundaries.set(schema, boundary);
+    return boundary;
+}
+//# sourceMappingURL=structuredOutput.js.map

package/dist/runtime/structuredOutput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredOutput.js","sourceRoot":"","sources":["../../src/runtime/structuredOutput.ts"],"names":[],"mappings":"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"}

package/dist/utils/displayWidth.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Terminal columns `text` occupies. Zero-width clusters (combining marks, default-ignorables)
+ * count 0, wide clusters (CJK, emoji, fullwidth forms) count 2, everything else 1. ANSI escape
+ * sequences are not counted, so a pre-coloured string measures as what the user sees — but the
+ * slices below do not share that awareness, so do not read this as a licence to feed them one.
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * The longest LEADING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
+ * the head, lose the tail. Total (never throws): a non-positive `maxWidth` yields `''`.
+ *
+ * A cluster is kept only if it fits ENTIRELY, so the result can come back one column short of
+ * `maxWidth` when the next cluster is two columns wide. That is the point: half a wide glyph
+ * cannot be drawn, and spending the column anyway is how text over-runs its budget.
+ *
+ * The clusters are produced one at a time and the walk stops at the budget, so the cost is the
+ * length of the RESULT rather than the length of the input — the input here is a whole tool-output
+ * line, which is unbounded.
+ */
+export declare function sliceToWidth(text: string, maxWidth: number): string;
+/**
+ * The longest TRAILING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
+ * the tail, lose the head. The mirror of {@link sliceToWidth}, for values whose end is the
+ * informative part (a path's leaf directory).
+ *
+ * This one materialises the clusters: it walks backwards, and cluster boundaries are only
+ * derivable from the front. Its callers pass a path or a model id, so the input is a line rather
+ * than a file.
+ */
+export declare function sliceEndToWidth(text: string, maxWidth: number): string;

package/dist/utils/displayWidth.js

@@ -0,0 +1,140 @@
+/**
+ * @module displayWidth
+ * The one place this repo answers "how many terminal COLUMNS does this string occupy, and where
+ * may I cut it". Everything that fits text to a terminal — the launch banner's field budgets, the
+ * tool-display caps — measures and slices through here.
+ *
+ * ## Why a code-point count is not a width
+ *
+ * `[...text].length` counts code points, which is right for UTF-16 safety and wrong for layout: a
+ * CJK ideograph or an emoji is ONE code point occupying TWO columns. Text measured that way reads
+ * as shorter than it renders, escapes whatever budget it was given, and wraps — and a wrapped
+ * continuation line starts back at column 0, which is precisely the failure the budgets exist to
+ * prevent. So the rule is: a value destined for a fixed column budget is measured with
+ * {@link displayWidth} and cut with {@link sliceToWidth} / {@link sliceEndToWidth}, never with
+ * `.length`, a spread, or `String.prototype.slice`.
+ *
+ * ## Why grapheme clusters are the cutting unit
+ *
+ * Slicing by code point is safe against halving a surrogate pair but not against halving a
+ * CLUSTER: a flag, a skin-toned or ZWJ-joined emoji, or a base letter plus its combining mark are
+ * several code points that a terminal draws as one glyph, and cutting between them produces
+ * mojibake or an orphaned mark. `Intl.Segmenter` gives the same cluster boundaries the width
+ * rules below are defined over, so the two agree by construction and a sliced string's width is
+ * exactly the sum of the widths of the clusters kept.
+ *
+ * ## What the slices expect: PLAIN text
+ *
+ * {@link displayWidth} is ANSI-aware and the slices are NOT, and that asymmetry is a contract
+ * rather than an oversight. An escape sequence is not one cluster — the terminal swallows it
+ * whole, but `ESC`, `[`, `3`, `5`, `m` segment as five, four of them printable — so the two
+ * disagree on an escape-bearing string and a slice can both under-fill its budget and cut inside
+ * a sequence. Feed the slices the text a user will read, and colour it afterwards; that is what
+ * every caller here does, since both render surfaces map a style tag to their own escapes at the
+ * very end. Making the slices ANSI-aware would change what a coloured preview line renders as,
+ * which is a decision for whoever needs it and not a silent detail of this module.
+ *
+ * That asymmetry is also why a slice decides "does the whole string fit?" two different ways. For
+ * plain text the cluster walk decides it: the widths of the clusters sum to the width of the
+ * string, so walking until the budget is blown answers the question and answers it WITHOUT
+ * touching the rest of the input — which is what keeps a megabyte-long preview line from being
+ * measured end to end before it is cut at column 200. Only escape-bearing text is measured whole
+ * first, because there the two rulers disagree and a coloured string that MEASURES as fitting must
+ * be handed back whole rather than cut short by the bytes of its own escapes.
+ *
+ * ## Why ambiguous-width characters stay NARROW
+ *
+ * `string-width` defaults to treating East-Asian "Ambiguous" characters as one column, and that
+ * default is load-bearing here rather than incidental: the sloth face is block elements, the
+ * wordmark is box-drawing, and `…` is U+2026 — all Ambiguous. Counting them as two columns would
+ * measure the 16-column face at 32 and shatter the layout it anchors. Do not pass
+ * `ambiguousIsNarrow: false`; the specs pin the face at 16 and the wordmark at 19 so a change of
+ * that policy fails loudly instead of quietly doubling the art.
+ */
+import stringWidth from 'string-width';
+/**
+ * Grapheme-cluster boundaries, i.e. what a terminal draws as one glyph. Built once: constructing
+ * an `Intl.Segmenter` is expensive relative to the short strings this module handles.
+ */
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/**
+ * Terminal columns `text` occupies. Zero-width clusters (combining marks, default-ignorables)
+ * count 0, wide clusters (CJK, emoji, fullwidth forms) count 2, everything else 1. ANSI escape
+ * sequences are not counted, so a pre-coloured string measures as what the user sees — but the
+ * slices below do not share that awareness, so do not read this as a licence to feed them one.
+ */
+export function displayWidth(text) {
+    return stringWidth(text);
+}
+/** The clusters of `text`, in order — the only unit either slice is allowed to cut between. */
+function clusters(text) {
+    const out = [];
+    for (const { segment } of GRAPHEME_SEGMENTER.segment(text))
+        out.push(segment);
+    return out;
+}
+/**
+ * Whether the whole-string measurement is the only ruler that can answer "does this fit" for
+ * `text` — true exactly when it carries an escape introducer (`ESC`, or the one-byte `CSI`), the
+ * two characters `string-width` itself strips on. On anything else the cluster widths sum to the
+ * whole-string width, so the walk decides the same question incrementally and a pre-measurement
+ * would be a second full pass over the input for nothing.
+ */
+function needsWholeStringMeasure(text) {
+    return text.includes('\u001B') || text.includes('\u009B');
+}
+/**
+ * The longest LEADING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
+ * the head, lose the tail. Total (never throws): a non-positive `maxWidth` yields `''`.
+ *
+ * A cluster is kept only if it fits ENTIRELY, so the result can come back one column short of
+ * `maxWidth` when the next cluster is two columns wide. That is the point: half a wide glyph
+ * cannot be drawn, and spending the column anyway is how text over-runs its budget.
+ *
+ * The clusters are produced one at a time and the walk stops at the budget, so the cost is the
+ * length of the RESULT rather than the length of the input — the input here is a whole tool-output
+ * line, which is unbounded.
+ */
+export function sliceToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return '';
+    if (needsWholeStringMeasure(text) && displayWidth(text) <= maxWidth)
+        return text;
+    let width = 0;
+    let kept = '';
+    for (const { segment } of GRAPHEME_SEGMENTER.segment(text)) {
+        const clusterWidth = displayWidth(segment);
+        if (width + clusterWidth > maxWidth)
+            break;
+        width += clusterWidth;
+        kept += segment;
+    }
+    return kept;
+}
+/**
+ * The longest TRAILING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
+ * the tail, lose the head. The mirror of {@link sliceToWidth}, for values whose end is the
+ * informative part (a path's leaf directory).
+ *
+ * This one materialises the clusters: it walks backwards, and cluster boundaries are only
+ * derivable from the front. Its callers pass a path or a model id, so the input is a line rather
+ * than a file.
+ */
+export function sliceEndToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return '';
+    if (needsWholeStringMeasure(text) && displayWidth(text) <= maxWidth)
+        return text;
+    const all = clusters(text);
+    let width = 0;
+    let kept = '';
+    for (let index = all.length - 1; index >= 0; index--) {
+        const clusterWidth = displayWidth(all[index]);
+        if (width + clusterWidth > maxWidth)
+            break;
+        width += clusterWidth;
+        kept = all[index] + kept;
+    }
+    return kept;
+}
+//# sourceMappingURL=displayWidth.js.map

package/dist/utils/displayWidth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"displayWidth.js","sourceRoot":"","sources":["../../src/utils/displayWidth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,WAAW,MAAM,cAAc,CAAC;AAEvC;;;GAGG;AACH,MAAM,kBAAkB,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,+FAA+F;AAC/F,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9E,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAS,uBAAuB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAAgB;IACzD,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7B,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,KAAK,GAAG,YAAY,GAAG,QAAQ;YAAE,MAAM;QAC3C,KAAK,IAAI,YAAY,CAAC;QACtB,IAAI,IAAI,OAAO,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,QAAgB;IAC5D,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7B,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,YAAY,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,IAAI,KAAK,GAAG,YAAY,GAAG,QAAQ;YAAE,MAAM;QAC3C,KAAK,IAAI,YAAY,CAAC;QACtB,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/systemPromptNotes.d.ts

@@ -61,26 +61,46 @@ export interface CommitCoAuthor {
     email?: string;
 }
 /**
- * GS2-35: append the commit co-authoring rule to the composed code-mode system prompt.
+ * GS2-35/EXT-83: append the commit-writing rules to the composed code-mode system prompt.
  *
  * Gaunt Sloth has **no dedicated git-commit tool** — the agent commits by calling
- * `run_shell_command` with `git commit`, composing the message (including any trailer) itself. Left
- * unguided, models emit `Co-Authored-By: <their own model name>` (e.g. `Claude`, `GPT`, `Gemini`)
- * from trained habit, which is **factually wrong**: the commit was produced by *Gaunt Sloth*, not by
- * the model. This note is the fix at the correct layer — first-party prompt guidance that (a) states
- * the exact trailer to emit and (b) forbids a model-name co-author.
+ * `run_shell_command` with `git commit`, composing the message (including any trailer) itself. That
+ * leaves two things it must be told, and both live here because both are about committing:
+ *
+ * 1. **WHO the co-author is.** Left unguided, models emit their own model name from trained habit,
+ *    which is factually wrong: the commit was produced by *Gaunt Sloth*, not by the model. The note
+ *    states the exact trailer to emit. EXT-83 — rather than enumerate model names not to write (a
+ *    denylist is stale the day a new vendor ships, and an enumeration beside a catch-all teaches the
+ *    model that the list is the rule), the correct name is SUPPLIED: the resolved
+ *    {@link ResolvedModelIdentity} decorates the DEFAULT name as `Gaunt Sloth (provider:model)`, so
+ *    the real model is named while the authorship stays Gaunt Sloth's.
+ * 2. **HOW the message reaches git.** A commit message passed inline in a double-quoted shell
+ *    argument is EXPANDED BY THE SHELL before git runs, so a message that quotes code the way
+ *    ordinary technical prose does is executed as a command. The note states that mechanism rather
+ *    than merely forbidding the construct — naming a construct without its mechanism has been
+ *    measured not to work. A file path carries no shell metacharacters, so the file form removes the
+ *    failure mode instead of asking the model to avoid it.
+ *
+ * The note's prose carries **no backtick and no other markup** — including no angle-bracket
+ * placeholder: it is the one piece of guidance whose subject is how to write a commit message, so
+ * quoting its own examples in backticks would demonstrate the exact style rule 2 exists to stop, and
+ * an angle-bracket placeholder copied literally is itself a shell input redirect. The `<email>` of
+ * the trailer line is the exception the RFC form requires, and is scoped out of the scan.
  *
  * The identity is config-driven (`commit.coAuthor` in {@link import('#src/config/types.js').GthConfig}).
  * Each field falls back INDEPENDENTLY to the Gaunt Sloth account
  * ({@link DEFAULT_COMMIT_CO_AUTHOR_NAME} / {@link DEFAULT_COMMIT_CO_AUTHOR_EMAIL}) — so a partial
  * override (name only, or a config that bypassed the loader) still yields a complete trailer, and a
- * fully-absent config yields the default account. Blank/whitespace values are treated as unset.
+ * fully-absent config yields the default account. Blank/whitespace values are treated as unset. An
+ * EXPLICITLY CONFIGURED name is emitted verbatim, with no identity spliced in — the user asked for
+ * that string; the identity decorates only the default. An unresolvable identity (`undefined`) falls
+ * back to the plain default name, never to a placeholder.
  *
  * Backend-agnostic: composed through the shared code path so BOTH the lean `GthLangChainAgent` and
  * the deep `GthDeepAgent` inject it (the git-commit capability rides on `run_shell_command`, which
  * both backends expose in code mode). Returns the note alone when there is no base prompt.
  */
-export declare function appendCommitCoAuthorNote(systemPrompt: string | undefined, coAuthor?: CommitCoAuthor): string;
+export declare function appendCommitCoAuthorNote(systemPrompt: string | undefined, coAuthor?: CommitCoAuthor, modelIdentity?: ResolvedModelIdentity): string;
 /**
  * GS2-34/GS2-53 — the resolved active-model identity, as a STRUCTURED value.
  *