@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/agent/compact-envelope.js

@@ -0,0 +1,374 @@
+/**
+ * The compact envelope: what a verdict result carries by default, and what waits behind
+ * `detail: "full"`.
+ *
+ * The rule (plan: "the middle ground — what a result carries"): answer the question, include what
+ * decides the next move, and give a cursor for the rest. A click on a cache-backed page used to
+ * return several thousand tokens, most of it store snapshots and counters, and the verdict was a
+ * field among them. Compaction never touches a decisive key — `verified`, `because`, the verdict's
+ * expected/observed/evidence, contradictions, capture integrity, failed requests, console errors,
+ * the acted element's source — and `compact-envelope.contract.test.ts` fails the build if it ever
+ * does. What it drops is redundant (identity fields the agent sent), restated (counts the `changed`
+ * line already says) or always one `reticle_observe { since }` away.
+ *
+ * It works by DROPPING named keys, never by allow-listing: a field added to a result later survives
+ * compaction until somebody decides it should not. The accurate direction to fail in.
+ *
+ * Applied once, at the dispatch chokepoint, to an agent's own calls. The Harness and the HUD read
+ * the full result; so does telemetry, which runs before this.
+ */
+import { z } from 'zod';
+import { ReticleTool, asRecord, predicateAliasesUsed } from '@reticlehq/core';
+/** The argument that asks for today's full envelope. */
+export const DETAIL_ARG = 'detail';
+export const Detail = { COMPACT: 'compact', FULL: 'full' };
+/**
+ * The A/B control: `RETICLE_RESULT_DETAIL=full` makes every agent call answer as if it had passed
+ * `detail: "full"`, so the agent-loop benchmark can run compact against full on the same build with
+ * nothing else different — the measurement CLAUDE.md requires beside any token optimisation.
+ */
+export const RESULT_DETAIL_ENV = 'RETICLE_RESULT_DETAIL';
+/**
+ * Did this call (or the daemon's environment) ask for the full envelope AND nothing else — no
+ * notices, no re-teach? Only an explicit ask: the A/B control arm, and an agent that said so.
+ */
+export function wantsFull(args) {
+    return Detail.FULL === args[DETAIL_ARG] || Detail.FULL === process.env[RESULT_DETAIL_ENV];
+}
+/**
+ * Did this call (or the daemon) ask for the compact envelope? Compaction is opt-in: in the
+ * agent-loop A/B the compact arm saved little per task and missed one failure the full arm caught,
+ * and a token saving ships only beside a correctness measurement that is at least as good.
+ */
+export function wantsCompact(args) {
+    return Detail.COMPACT === (args[DETAIL_ARG] ?? process.env[RESULT_DETAIL_ENV]);
+}
+/** The tools whose results are compacted. Each one's full shape stays one argument away. */
+export const COMPACTED_TOOLS = new Set([
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.ASSERT,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.ACT_SEQUENCE,
+    // The merged surface's `reticle_act` routes `steps` to the sequence handler.
+    ReticleTool.ACT,
+]);
+/** Short enough for the per-turn surface; the reasoning lives in this file and the instructions. */
+export const DETAIL_ARG_DESCRIPTION = '"compact" keeps only the deciding fields.';
+/** Where the aliases a predicate was normalised from are named. */
+export const NORMALIZED_KEY = 'normalized';
+/**
+ * The aliases the call's predicates were written in (`until`/`predicate`, and each step's `expect`).
+ * The parse accepted them silently; this says so, so the canonical spelling is learned once.
+ */
+function aliasesWritten(args) {
+    const used = [...predicateAliasesUsed(args['until']), ...predicateAliasesUsed(args['predicate'])];
+    const steps = args['steps'];
+    if (Array.isArray(steps)) {
+        steps.forEach((step, i) => {
+            for (const alias of predicateAliasesUsed(asRecord(step)['expect'])) {
+                used.push(`step ${String(i)}: ${alias}`);
+            }
+        });
+    }
+    return used;
+}
+/** The key the one-line "what changed" summary travels under. */
+export const CHANGED_KEY = 'changed';
+/** Effect keys that only repeat what the agent sent, or restate a default. */
+const EFFECT_IDENTITY_KEYS = [
+    'ok',
+    'ref',
+    'action',
+    'testid',
+    'component',
+    'role',
+    'name',
+    'source',
+];
+/** Nested effect keys that describe the motion, not the outcome. */
+const EFFECT_MOTION_KEYS = ['focusMoved'];
+/**
+ * Evidence keys that describe HOW a request travelled, not what decided the verdict. Removed only
+ * from the evidence's own records, wherever they nest; every other key — the method, url, status,
+ * the matched body field — stays.
+ */
+const EVIDENCE_NOISE_KEYS = new Set([
+    'initiatorStack',
+    'initiator',
+    'requestShape',
+    'responseSize',
+    'requestSize',
+    'contentType',
+    'statusText',
+    'headers',
+    'requestHeaders',
+    'responseHeaders',
+    'timing',
+]);
+/** A request slower than this keeps its duration: slowness is then the finding. */
+const SLOW_MS = 1000;
+/** The causal-summary keys that decide something, kept beside the `changed` line. */
+const DECISIVE_SUMMARY_KEYS = [
+    'consoleErrors',
+    'firstConsoleError',
+    'truncated',
+    'stateUnwatched',
+    'elided',
+];
+function isRecord(value) {
+    return 'object' === typeof value && null !== value && !Array.isArray(value);
+}
+function without(record, keys) {
+    const out = { ...record };
+    for (const key of keys)
+        delete out[key];
+    return out;
+}
+/** Evidence with transport detail removed, recursively, keeping every deciding field. */
+export function trimEvidence(value, depth = 0) {
+    if (depth > 4)
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => trimEvidence(item, depth + 1));
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (EVIDENCE_NOISE_KEYS.has(key))
+            continue;
+        if ('durationMs' === key && 'number' === typeof item && item < SLOW_MS)
+            continue;
+        out[key] = trimEvidence(item, depth + 1);
+    }
+    return out;
+}
+/** `src/x.tsx:81` from a `{file,line}` source record, or the string as given. */
+function sourceLabel(source) {
+    if ('string' === typeof source)
+        return source;
+    if (!isRecord(source) || 'string' !== typeof source['file'])
+        return undefined;
+    return 'number' === typeof source['line']
+        ? `${source['file']}:${String(source['line'])}`
+        : source['file'];
+}
+/** The `{effect}` of an act, keeping only what says something the agent did not already know. */
+function compactEffect(effect) {
+    const out = without(effect, EFFECT_IDENTITY_KEYS);
+    if (true === out['dispatched'])
+        delete out['dispatched'];
+    if (true === out['settled'])
+        delete out['settled'];
+    if (null === out['settleReason'] || undefined === out['settleReason'])
+        delete out['settleReason'];
+    const nested = out['effect'];
+    if (isRecord(nested)) {
+        const lean = without(nested, EFFECT_MOTION_KEYS);
+        if (0 === Object.keys(lean).length)
+            delete out['effect'];
+        else
+            out['effect'] = lean;
+    }
+    return out;
+}
+/**
+ * One line naming what moved: the route, the requests, the MEANINGFUL state paths (cache
+ * bookkeeping is already filtered out upstream), storage keys, fields and signals.
+ */
+export function changedLine(summary) {
+    const parts = [];
+    if ('string' === typeof summary['route'])
+        parts.push(`route ${summary['route']}`);
+    const requests = Array.isArray(summary['requests']) ? summary['requests'] : [];
+    if (requests.length > 0)
+        parts.push(requests.map(String).join(', '));
+    const stateDiffs = Array.isArray(summary['stateDiffs'])
+        ? summary['stateDiffs']
+        : [];
+    const statePaths = [...new Set(stateDiffs.map((d) => asRecord(d)['path']).map(String))];
+    if (statePaths.length > 0)
+        parts.push(`state ${statePaths.join(', ')}`);
+    const list = (key, label) => {
+        const items = summary[key];
+        if (Array.isArray(items) && items.length > 0)
+            parts.push(`${label} ${items.map(String).join(', ')}`);
+    };
+    list('storageKeysChanged', 'storage');
+    list('fieldsChanged', 'fields');
+    list('signals', 'signal');
+    return 0 === parts.length ? undefined : parts.join(' · ');
+}
+/** The causal summary reduced to the facts that decide something, or undefined when none did. */
+function decisiveSummary(summary) {
+    const out = {};
+    for (const key of DECISIVE_SUMMARY_KEYS) {
+        const value = summary[key];
+        if (value === undefined || 0 === value)
+            continue;
+        out[key] = value;
+    }
+    const net = asRecord(summary['net']);
+    if ('number' === typeof net['errors'] && net['errors'] > 0) {
+        out['net'] = {
+            errors: net['errors'],
+            ...(net['headline'] === undefined ? {} : { headline: net['headline'] }),
+        };
+    }
+    return 0 === Object.keys(out).length ? undefined : out;
+}
+/** Honesty: the grade, integrity always, the rest only when it says something. */
+function compactHonesty(honesty) {
+    const out = { ...honesty };
+    if ('window' === out['attribution'])
+        delete out['attribution'];
+    const coverage = asRecord(out['coverage']);
+    if (true !== coverage['partial'])
+        delete out['coverage'];
+    if (true === out['settled'])
+        delete out['settled'];
+    return out;
+}
+/** A gap repeated this session carries no remedy and no news — drop it. */
+function freshGaps(gaps) {
+    return Array.isArray(gaps) ? gaps.filter((gap) => true !== asRecord(gap)['repeat']) : [];
+}
+/** The screenshot by path, or the reason there is none. */
+function compactScreenshot(shot) {
+    if (!isRecord(shot) || 'string' !== typeof shot['path'])
+        return shot;
+    return { path: shot['path'] };
+}
+/** One verdict result (act_and_wait, assert, wait_for), compacted. Idempotent. */
+export function compactVerdict(result) {
+    const out = { ...result };
+    delete out['trace'];
+    const effect = out['effect'];
+    if (isRecord(effect)) {
+        if (out['ref'] === undefined && 'string' === typeof effect['ref'])
+            out['ref'] = effect['ref'];
+        const source = sourceLabel(effect['source']);
+        if (out['source'] === undefined && source !== undefined)
+            out['source'] = source;
+        const lean = compactEffect(effect);
+        if (0 === Object.keys(lean).length)
+            delete out['effect'];
+        else
+            out['effect'] = lean;
+    }
+    const verdict = out['verdict'];
+    if (isRecord(verdict) && verdict['evidence'] !== undefined) {
+        out['verdict'] = { ...verdict, evidence: trimEvidence(verdict['evidence']) };
+    }
+    const summary = out['summary'];
+    // A summary carrying `net` as an object is the full causal summary; a compact one never does.
+    if (isRecord(summary) &&
+        isRecord(summary['net']) &&
+        'number' === typeof summary['net']['total']) {
+        const line = changedLine(summary);
+        if (line !== undefined)
+            out[CHANGED_KEY] = line;
+        const decisive = decisiveSummary(summary);
+        if (decisive === undefined)
+            delete out['summary'];
+        else
+            out['summary'] = decisive;
+    }
+    if (isRecord(out['honesty']))
+        out['honesty'] = compactHonesty(out['honesty']);
+    if (out['instrumentationGaps'] !== undefined) {
+        const gaps = freshGaps(out['instrumentationGaps']);
+        if (0 === gaps.length)
+            delete out['instrumentationGaps'];
+        else
+            out['instrumentationGaps'] = gaps;
+    }
+    if (out['screenshot'] !== undefined)
+        out['screenshot'] = compactScreenshot(out['screenshot']);
+    // The blast radius on a green mostly restates the `changed` line. Its undeclared REQUESTS are the
+    // exception — "it worked, and it also fired a DELETE" — so those stay. On a red it lives in the
+    // capsule, which is kept whole.
+    if (out[CHANGED_KEY] !== undefined && Array.isArray(out['blastRadius'])) {
+        const requests = out['blastRadius'].filter((b) => 'string' === typeof b && b.startsWith('net '));
+        if (0 === requests.length)
+            delete out['blastRadius'];
+        else
+            out['blastRadius'] = requests;
+    }
+    return out;
+}
+/** One sequence step, compacted: the outcome, its source, its screenshot, its contradictions. */
+function compactStep(step) {
+    if (!isRecord(step))
+        return step;
+    const out = without(step, ['testid', 'component', 'role', 'name', 'digest']);
+    if (true === out['dispatched'])
+        delete out['dispatched'];
+    if (true === out['settled'])
+        delete out['settled'];
+    if (null === out['settleReason'])
+        delete out['settleReason'];
+    const source = sourceLabel(out['source']);
+    if (source !== undefined)
+        out['source'] = source;
+    if (out['screenshot'] !== undefined)
+        out['screenshot'] = compactScreenshot(out['screenshot']);
+    return out;
+}
+/** A sequence result, compacted per step. Idempotent. */
+export function compactSequence(result) {
+    if (!Array.isArray(result['steps']))
+        return result;
+    return { ...result, steps: result['steps'].map(compactStep) };
+}
+/**
+ * The result as an agent receives it: full unless it asked for `detail: "compact"`.
+ *
+ * `agentCall` is the dispatcher's own judgement (an MCP connection, not the Harness or the HUD).
+ */
+export function shapeForAgent(tool, args, result, agentCall) {
+    if (!agentCall || !COMPACTED_TOOLS.has(tool) || !isRecord(result))
+        return result;
+    const normalized = aliasesWritten(args);
+    const noted = 0 === normalized.length ? result : { ...result, [NORMALIZED_KEY]: normalized };
+    if (!wantsCompact(args))
+        return noted;
+    if (Array.isArray(noted['steps']))
+        return compactSequence(noted);
+    return 'verified' in noted ? compactVerdict(noted) : noted;
+}
+/**
+ * The compacted tools, with `detail` accepted and the compact-only keys declared.
+ *
+ * Declared because a schema-strict client validates `structuredContent` against `outputSchema` and
+ * drops what is not there: `changed`, `ref` and `source` would be built and silently thrown away.
+ */
+export function withCompactEnvelope(tools) {
+    return tools.map((tool) => {
+        if (!COMPACTED_TOOLS.has(tool.name))
+            return tool;
+        const output = tool.outputSchema;
+        return {
+            ...tool,
+            inputSchema: {
+                ...tool.inputSchema,
+                [DETAIL_ARG]: z
+                    .enum([Detail.COMPACT, Detail.FULL])
+                    .optional()
+                    .describe(DETAIL_ARG_DESCRIPTION),
+            },
+            ...(output === undefined
+                ? {}
+                : {
+                    outputSchema: {
+                        [CHANGED_KEY]: z.string().optional(),
+                        ref: z.string().optional(),
+                        source: z.string().optional(),
+                        [NORMALIZED_KEY]: z.array(z.string()).optional(),
+                        caseOnlyMiss: z.boolean().optional(),
+                        wouldHold: z.string().optional(),
+                        ...output,
+                    },
+                }),
+        };
+    });
+}

package/dist/surface/tools/agent/for-the-agent.d.ts

@@ -0,0 +1,12 @@
+import { type NoticeFold } from './notices.js';
+export interface AgentAnswer {
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+    /** The agent session; undefined for every caller that is not an agent's own connection. */
+    attach: string | undefined;
+    /** The project's `.reticle` root, when one resolves. */
+    root: string | undefined;
+    fold: NoticeFold;
+}
+export declare function forTheAgent(answer: AgentAnswer): unknown;

package/dist/surface/tools/agent/for-the-agent.js

@@ -0,0 +1,44 @@
+/**
+ * What an agent's own call (an MCP connection, not the Harness or the HUD) receives: compacted, its
+ * advisories folded into once-per-session notices, the rule it just broke re-taught once, and — on
+ * its first answer — the pointer to the primer and this app's notes.
+ *
+ * `detail: "full"` keeps today's envelope. `reticle_run` passes its inner call's answer through,
+ * which was already shaped. Everything here runs AFTER the verdict was decided and after telemetry
+ * read the full result; none of it can change a verdict.
+ */
+import { ReticleTool } from '@reticlehq/core';
+import { addAppNote, readAppNotes } from './app-notes.js';
+import { shapeForAgent, wantsFull } from './compact-envelope.js';
+import { learnFromVerdict } from './app-notes-learning.js';
+import { reteachFor } from './reteach.js';
+import { staleBuildNotice } from './build-staleness.js';
+import { PRIMER_POINTER, foldNotices } from './notices.js';
+import { dirname } from 'node:path';
+import { keychainNoticeOnce, projectReader } from '../../../command/cli/doctor/doctor-signing-line.js';
+const isRecord = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+export function forTheAgent(answer) {
+    const { name, args, attach, root } = answer;
+    const shaped = shapeForAgent(name, args, answer.result, attach !== undefined);
+    if (attach === undefined || ReticleTool.RUN === name || !isRecord(shaped))
+        return shaped;
+    // A corrected failure that just passed becomes an app note: a hint for the next session.
+    const learned = learnFromVerdict(attach, args, shaped);
+    if (learned !== undefined && root !== undefined)
+        addAppNote(root, learned);
+    if (wantsFull(args))
+        return shaped;
+    const notes = root === undefined ? [] : readAppNotes(root).map((note) => `App note: ${note}`);
+    const stale = staleBuildNotice();
+    const project = root === undefined ? undefined : dirname(root);
+    const keychain = project === undefined
+        ? undefined
+        : keychainNoticeOnce(attach, { read: projectReader(project), dir: project });
+    return foldNotices(shaped, attach, answer.fold, [
+        ...(stale === undefined ? [] : [stale]),
+        ...(keychain === undefined ? [] : [keychain]),
+        PRIMER_POINTER,
+        ...notes,
+        ...reteachFor(attach, name, args, shaped),
+    ]);
+}

package/dist/surface/tools/agent/notices.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One `notices` field, each notice at most once per agent session.
+ *
+ * Advisories used to arrive as their own keys — `feedback_prompt`, `talk_to_us`, `platform`,
+ * `update_available`, `session_lease`… — each with its own paragraph, and the ones that were not
+ * one-shot at the source repeated on every call. An agent reads a result to find the verdict; every
+ * advisory beside it is something it has to read past, and the same one twice is pure cost.
+ *
+ * So, for an agent's own call: each advisory becomes ONE line in `notices`, said once per agent
+ * session (one MCP connection); `next` is said only when it says something new; the throttled-tab
+ * paragraph is said once (the `session.throttled` flag still rides on every result — the FACT is
+ * never deduplicated, only its explanation). Telemetry already counted every advisory when it was
+ * taken, before this runs.
+ *
+ * `detail: "full"` callers and the Harness/HUD get the result untouched.
+ */
+/** Which result keys fold into notices, and where the folded lines go. Supplied by the dispatcher. */
+export interface NoticeFold {
+    /** Advisory keys whose value becomes one notice line. */
+    readonly advisories: readonly string[];
+    /** Where the lines go. */
+    readonly notices: string;
+    /** The one-line "do this next" key: kept only when its text is new this session. */
+    readonly next: string;
+    /** The key the session-health warning travels under. */
+    readonly warning: string;
+    /**
+     * Warnings that are paragraphs about the TAB (throttled, version skew): said in full once per
+     * session, then replaced by their short form (`undefined` drops it — used only where the fact
+     * itself still rides on every result, as `session.throttled` does).
+     */
+    readonly onceWarnings: ReadonlyMap<string, string | undefined>;
+}
+/**
+ * The one-line pointer an agent session's first answer carries. The primer itself lives in the
+ * agent's rules file (written by `reticle init`), which survives a compaction; a tool result does not.
+ */
+export declare const PRIMER_POINTER = "Reticle's rules are in the Reticle section of your CLAUDE.md / AGENTS.md. Context compacted? reticle_run { tool: \"reticle_context\", args: { compact: true } } first.";
+/** Tests only. */
+export declare function resetNotices(): void;
+/** One line from an advisory's value: a string as-is, an object by its sentence field. */
+export declare function noticeLine(value: unknown): string | undefined;
+/** The first sentence of a paragraph (a full stop followed by a space or the end). */
+export declare function firstSentenceOf(text: string): string;
+/** Fold a result's advisories into once-per-session notices. Never touches any other key. */
+export declare function foldNotices(result: Record<string, unknown>, session: string, fold: NoticeFold, extra?: readonly string[]): Record<string, unknown>;
+/** Has this agent session already been asked for feedback? Undefined session: never gated. */
+export declare function feedbackAlreadyAsked(session: string | undefined): boolean;
+/** Record that this session was asked. */
+export declare function noteFeedbackAsked(session: string | undefined): void;

package/dist/surface/tools/agent/notices.js

@@ -0,0 +1,152 @@
+/**
+ * One `notices` field, each notice at most once per agent session.
+ *
+ * Advisories used to arrive as their own keys — `feedback_prompt`, `talk_to_us`, `platform`,
+ * `update_available`, `session_lease`… — each with its own paragraph, and the ones that were not
+ * one-shot at the source repeated on every call. An agent reads a result to find the verdict; every
+ * advisory beside it is something it has to read past, and the same one twice is pure cost.
+ *
+ * So, for an agent's own call: each advisory becomes ONE line in `notices`, said once per agent
+ * session (one MCP connection); `next` is said only when it says something new; the throttled-tab
+ * paragraph is said once (the `session.throttled` flag still rides on every result — the FACT is
+ * never deduplicated, only its explanation). Telemetry already counted every advisory when it was
+ * taken, before this runs.
+ *
+ * `detail: "full"` callers and the Harness/HUD get the result untouched.
+ */
+/**
+ * The one-line pointer an agent session's first answer carries. The primer itself lives in the
+ * agent's rules file (written by `reticle init`), which survives a compaction; a tool result does not.
+ */
+export const PRIMER_POINTER = 'Reticle\'s rules are in the Reticle section of your CLAUDE.md / AGENTS.md. Context compacted? reticle_run { tool: "reticle_context", args: { compact: true } } first.';
+/** An empty session list keeps its first sentence; the executable `next_action` carries the rest. */
+const WHY_KEY = 'why';
+const SESSIONS_KEY = 'sessions';
+/** Fields of an advisory object that hold its sentence, in the order they are tried. */
+const SENTENCE_FIELDS = [
+    'ask',
+    'message',
+    'text',
+    'line',
+    'reason',
+    'IMPORTANT',
+];
+/** Bound on remembered lines per session, and on remembered sessions: a daemon outlives both. */
+const MAX_LINES = 200;
+const MAX_SESSIONS = 500;
+const seenBySession = new Map();
+/** Tests only. */
+export function resetNotices() {
+    seenBySession.clear();
+    feedbackAsked.clear();
+}
+function seenFor(session) {
+    let seen = seenBySession.get(session);
+    if (seen === undefined) {
+        if (seenBySession.size >= MAX_SESSIONS) {
+            const oldest = seenBySession.keys().next().value;
+            if (oldest !== undefined)
+                seenBySession.delete(oldest);
+        }
+        seen = new Set();
+        seenBySession.set(session, seen);
+    }
+    return seen;
+}
+/** First time this session sees `line`? Records it either way. */
+function firstTime(seen, line) {
+    if (seen.has(line))
+        return false;
+    if (seen.size < MAX_LINES)
+        seen.add(line);
+    return true;
+}
+/** One line from an advisory's value: a string as-is, an object by its sentence field. */
+export function noticeLine(value) {
+    if ('string' === typeof value)
+        return 0 === value.trim().length ? undefined : value.trim();
+    if ('object' !== typeof value || null === value)
+        return undefined;
+    const record = value;
+    for (const field of SENTENCE_FIELDS) {
+        const text = record[field];
+        if ('string' === typeof text && text.trim().length > 0) {
+            const command = record['command'];
+            return 'string' === typeof command ? `${text.trim()} (${command})` : text.trim();
+        }
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The first sentence of a paragraph (a full stop followed by a space or the end). */
+export function firstSentenceOf(text) {
+    const match = /^[\s\S]*?[.!?](?=\s|$)/.exec(text);
+    return (match?.[0] ?? text).trim();
+}
+/** Fold a result's advisories into once-per-session notices. Never touches any other key. */
+export function foldNotices(result, session, fold, extra = []) {
+    const seen = seenFor(session);
+    const out = { ...result };
+    const lines = Array.isArray(out[fold.notices])
+        ? out[fold.notices].filter((l) => 'string' === typeof l)
+        : [];
+    for (const key of fold.advisories) {
+        if (!(key in out))
+            continue;
+        const line = noticeLine(out[key]);
+        delete out[key];
+        if (line !== undefined && firstTime(seen, `${key}\u0000${line}`))
+            lines.push(line);
+    }
+    for (const line of extra)
+        if (firstTime(seen, `\u0000${line}`))
+            lines.push(line);
+    const next = out[fold.next];
+    if ('string' === typeof next && !firstTime(seen, `${fold.next}\u0000${next}`)) {
+        delete out[fold.next];
+    }
+    const warning = out[fold.warning];
+    if ('string' === typeof warning &&
+        fold.onceWarnings.has(warning) &&
+        !firstTime(seen, `${fold.warning}\u0000${warning}`)) {
+        const short = fold.onceWarnings.get(warning);
+        if (short === undefined)
+            delete out[fold.warning];
+        else
+            out[fold.warning] = short;
+    }
+    const sessions = out[SESSIONS_KEY];
+    const why = out[WHY_KEY];
+    if (Array.isArray(sessions) && 0 === sessions.length && 'string' === typeof why) {
+        out[WHY_KEY] = firstSentenceOf(why);
+    }
+    if (lines.length > 0)
+        out[fold.notices] = lines;
+    else
+        delete out[fold.notices];
+    return out;
+}
+/**
+ * The feedback reflex, at most once per agent session.
+ *
+ * The ask (`feedback_prompt`), the friction invitation (`feedback_invite` + `talk_to_us`) and their
+ * kin are one family: an agent asked twice in a session hears noise. Gated where they are TAKEN
+ * rather than hidden after, so the `feedbackPrompted` denominator counts only asks an agent saw.
+ */
+const feedbackAsked = new Set();
+/** Has this agent session already been asked for feedback? Undefined session: never gated. */
+export function feedbackAlreadyAsked(session) {
+    return session !== undefined && feedbackAsked.has(session);
+}
+/** Record that this session was asked. */
+export function noteFeedbackAsked(session) {
+    if (session === undefined)
+        return;
+    if (feedbackAsked.size >= MAX_SESSIONS)
+        feedbackAsked.clear();
+    feedbackAsked.add(session);
+}

package/dist/surface/tools/agent/reteach.d.ts

@@ -0,0 +1,11 @@
+export declare const ReteachLine: {
+    readonly NO_UNTIL: "Rule: name the consequence in `until` BEFORE acting — without it the result is \"no-fault\", which proves nothing.";
+    readonly ALIAS: "Rule: write predicates in their canonical spelling (see `normalized`); aliases are a courtesy, not the API.";
+    readonly CASE: "Rule: text checks are exact-case — use ignoreCase: true only when the case truly does not matter.";
+    readonly RELIST: "Rule: you already have this tab — reuse its sessionId (or omit it) instead of listing sessions again.";
+    readonly COMPACTED: "Lost track (context compacted)? reticle_run { tool: \"reticle_context\", args: { compact: true } } returns what this session proved, failed and still owes.";
+};
+/** Tests only. */
+export declare function resetReteach(): void;
+/** The rule this call broke, if any. */
+export declare function reteachFor(session: string, tool: string, args: Record<string, unknown>, result: Record<string, unknown>): string[];