@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Supervisor.d.ts.map

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

package/dist/esm/Supervisor.js

@@ -0,0 +1,575 @@
+/**
+ * The reading Jev takes of a run while it is still running.
+ *
+ * Every other control in this package reads a completion, or reads one fact
+ * the harness measured: a tree that never moved, a check that was narrowed, a
+ * frame that repeated itself. Each is exact, each fires late, and each is
+ * silent about the run between its brakes. A run that edits the wrong file
+ * for twenty frames, re-runs one failing check after every edit and never
+ * once claims to be done trips none of them until its budget is gone.
+ *
+ * So this module asks Jev about the run's *shape* rather than its sentence.
+ * One classifier, `supervisor/turn`, over a {@link Snapshot} the controller
+ * assembles from what it already holds: the task, the newest frames, and the
+ * counts the deterministic controls keep — read-only streak, repeat streak,
+ * mutations, checks run and failing, unanswered failures, demands spent. It
+ * re-derives none of them. Beside the run's state it carries the skills it has
+ * not called, the flows it has, and whether it can call `jev`. One Jev call per
+ * snapshot answers every question at once.
+ *
+ * Eleven questions are fixed. Five are about the run: whether it is
+ * thrashing, whether it is still on the task, whether its evidence is
+ * suspect, and whether it carries outdated or irrelevant context. Five are
+ * operational states a person would recognise in a colleague, each scored
+ * `none`, `mild` or `strong` against evidence the snapshot names, and
+ * `needs_help` is the one word a person is shown. The five about the run are
+ * the {@link triggers}: any one past its threshold crosses. Each monitor the
+ * host arms may add one boolean of its own, under {@link monitorPrefix}.
+ *
+ * Rows recalled from {@link Memory} are not asked about here. Beside each
+ * reading, the supervisor asks `Relevance` which of up to
+ * {@link recalledLimit} rows, none already shown to the run, are unnecessary
+ * for the task; the rest are shown at the next boundary as
+ * {@link recalledInsert} renders them, and a row is shown to a run once.
+ *
+ * It is a supervisor and not a brake: nothing here ends a run, refuses a
+ * completion, or decides anything on the cell loop's hot path. `CellTurn`
+ * offers each frame's snapshot to a one-slot sliding queue and continues; a
+ * forked fiber takes the newest snapshot, asks, journals what came back, and
+ * hands the monitors' values and any recalled rows to the *next* turn boundary,
+ * which decides there what the run is told. A reading that arrives after the boundary it was for is
+ * journaled and never delivered, and a snapshot the fiber never reached is
+ * dropped: the run is never told something about a frame two frames gone.
+ *
+ * It never falls back. A snapshot Jev could not read is journaled as
+ * {@link AgentEvent.SupervisorUnjudged} with the transport's own reason; it
+ * nudges nothing, and is never counted as a reading that
+ * found the run calm or on target. A host with no judge (`unconfigured`) is
+ * journaled once per streak rather than every frame; each reading still asks,
+ * so a judge connected mid-run is used at once. Nothing here is a default value: every
+ * level and every word on the settled event came back from the transport.
+ *
+ * What a reading says is delivered wherever the host holds a real judge
+ * (`CellTurn.Input.judged`), and only through a monitor that crossed and
+ * passed its gates; the text of the legacy nudge is {@link nudge}, which the
+ * `supervisor` lint monitor says. The offline replay of archived journals
+ * (`evals/swebench/lib/jev-replay.mjs`, which scores {@link triggers} itself
+ * rather than a copy of it) measures their precision. The verdict is
+ * journaled whenever an `Evaluator` is bound. The supervisor writes no
+ * memory: a run's transcript is mined once, at run end, by `@smthrs/agent`'s
+ * `MemoryMine`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Classifier from "@smthrs/model/Classifier";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as elide from "./internal/elide.js";
+import { NonNegativeSafeInt } from "./internal/nonNegativeSafeInt.js";
+import { untrustedData } from "./internal/untrustedData.js";
+import * as Judgement from "./Judgement.js";
+/**
+ * The most of one frame's cell, prose or prints the snapshot carries, in
+ * UTF-8 bytes. The head of a cell and the tail of its prints: a cell states
+ * its plan first and a runner states its verdict last.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const frameBytes = 1024;
+/**
+ * How many of the newest frames a snapshot carries.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const recentFrames = 3;
+/**
+ * The most rows one reading recalls from {@link Memory}.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const recalledLimit = 6;
+/**
+ * How long a run that ends with a reading in flight waits for it to settle
+ * and journal, in milliseconds. A reading still unanswered then is interrupted
+ * and journaled `supervisor-unjudged` with reason `interrupted`; the run never
+ * waits longer than this for its supervisor.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const closeGraceMs = 1_500;
+/**
+ * At or above this probability of `thrashing`, the reading crosses.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const thrashingAt = 0.5;
+/**
+ * At or below this probability of `on_target`, the reading crosses.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const offTargetAt = 0.5;
+/**
+ * At or above this probability of `suspect`, the reading crosses.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const suspectAt = 0.5;
+/**
+ * At or above this probability of `outdated_context` or
+ * `irrelevant_context`, a judged run compacts at its next frame.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const contextAt = 0.5;
+/**
+ * The three rungs every operational-state question is scored on.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Level = Schema.Literals(["none", "mild", "strong"]);
+/**
+ * The rungs as the score question declares them, in order.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const levels = ["none", "mild", "strong"];
+/**
+ * The one word a person is shown about a run.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Help = Schema.Literals(["none", "clarification", "permission", "stuck", "risky_action"]);
+/**
+ * The five operational states, in the order they are asked and journaled.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const emotions = ["frustrated", "anxious", "scared", "confused", "confident"];
+/**
+ * One recent frame as the snapshot carries it: the cell the model wrote, the
+ * prose around it, what the cell printed, and how it ended.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Frame = Schema.Struct({
+    frame: NonNegativeSafeInt,
+    cell: Schema.String.annotate({ description: "The cell the model wrote, head kept" }),
+    prose: Schema.String.annotate({ description: "What the model wrote outside the cell, head kept" }),
+    printed: Schema.String.annotate({ description: "What the cell printed, newest bytes kept" }),
+    transition: Schema.Literals(["continue", "complete", "park", "raised", "rejected"]),
+    mutated: Schema.Boolean.annotate({ description: "Whether this frame changed the workspace" })
+});
+/**
+ * The counts the deterministic controls keep, handed over as they stand.
+ *
+ * Every field is read off `CellTurn.State` or the frame's accounting and none
+ * is re-derived here: the supervisor is a reader of the harness's evidence,
+ * not a second measurer of it.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Signals = Schema.Struct({
+    frame: NonNegativeSafeInt.annotate({ description: "The frame just closed, counting from zero" }),
+    maxFrames: NonNegativeSafeInt.annotate({ description: "The frame budget; zero is unbounded" }),
+    readOnlyFrames: NonNegativeSafeInt.annotate({ description: "Consecutive frames that changed nothing" }),
+    repeatFrames: NonNegativeSafeInt.annotate({
+        description: "Consecutive frames that issued only calls already issued and changed nothing"
+    }),
+    mutations: NonNegativeSafeInt.annotate({ description: "Frames that changed the workspace" }),
+    remoteMutations: NonNegativeSafeInt.annotate({ description: "Writes recorded on trees the host cannot see" }),
+    treeMoved: Schema.Boolean.annotate({ description: "Whether the workspace differs from the tree the run opened on" }),
+    paths: NonNegativeSafeInt.annotate({
+        description: "Paths the closing workspace measurement covered; zero unmeasured"
+    }),
+    checksRun: NonNegativeSafeInt.annotate({ description: "Distinct checks the run has run" }),
+    checksFailing: NonNegativeSafeInt.annotate({ description: "Of those, how many last reported a failing status" }),
+    failuresUnanswered: NonNegativeSafeInt.annotate({
+        description: "Failing checks no later passing check has answered"
+    }),
+    callsFailed: NonNegativeSafeInt.annotate({ description: "Settled calls in the ledger that failed" }),
+    callsSettled: NonNegativeSafeInt.annotate({ description: "Settled calls in the ledger" }),
+    narrowingDemands: NonNegativeSafeInt.annotate({ description: "Completions bounced for narrowed evidence" }),
+    unmovedDemands: NonNegativeSafeInt.annotate({ description: "Completions bounced for an unmoved tree" }),
+    unresolvedDemands: NonNegativeSafeInt.annotate({ description: "Completions bounced for a stepped-around failure" }),
+    claimDemands: NonNegativeSafeInt.annotate({ description: "Completions bounced for an unsupported claim" }),
+    sufficiencyStated: Schema.Boolean.annotate({ description: "Whether the run was told its evidence is complete" })
+});
+/**
+ * One row recalled from memory.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Recalled = Schema.Struct({
+    key: Schema.String,
+    text: Schema.String
+});
+/**
+ * The most skills one snapshot offers.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const skillLimit = 12;
+/**
+ * The most of one skill's description a snapshot carries, in UTF-8 bytes.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const skillBytes = 256;
+/**
+ * The most distinct flow names {@link Snapshot} `called` carries.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const calledLimit = 64;
+/**
+ * One skill the run could read and has neither called nor read.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Skill = Schema.Struct({
+    name: Schema.String,
+    description: Schema.String.annotate({ description: "The description's head, wrapped as untrusted data" }),
+    path: Schema.String.annotate({ description: "Where the skill's Markdown body is" })
+});
+/**
+ * One skill as a snapshot offers it: its description's head within
+ * {@link skillBytes}, wrapped as untrusted data.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const skill = (name, description, path) => ({
+    name,
+    description: untrustedData(elide.head(description, skillBytes, "clipped"), `description of skill ${name}`),
+    path
+});
+/**
+ * Everything one supervisor reading is a reading of.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Snapshot = Schema.Struct({
+    task: Schema.String.annotate({ description: "The task, as the person stated it" }),
+    frames: Schema.Array(Frame).annotate({ description: "The newest frames, oldest first" }),
+    signals: Signals,
+    skills: Schema.Array(Skill).annotate({
+        description: "Skills the run could read and has neither called nor read, by index"
+    }),
+    called: Schema.Array(Schema.String).annotate({ description: "Distinct flows the run has called" }),
+    jevAvailable: Schema.Boolean.annotate({ description: "Whether the run can call the jev flow" })
+});
+/**
+ * The fixed questions, asked of every snapshot.
+ *
+ * Each criterion names the evidence it reads, so a reading is answerable from
+ * the snapshot and never from what the transport imagines the repository holds.
+ */
+const fixedQuestions = {
+    thrashing: Classifier.boolean({
+        instructions: "Is the run going in circles rather than converging? Compare the newest frames with each other and with signals.checksFailing, signals.failuresUnanswered, signals.readOnlyFrames and signals.repeatFrames. Any one sign below is enough.",
+        criteria: {
+            true: "a check fails again after an edit meant to fix it, an edit is redone or reverted, or the newest frames re-read or re-run what earlier frames already saw without learning anything new",
+            false: "the newest frames learn something new or make progress: a failing check now passes, or a new cause is found and acted on"
+        }
+    }),
+    on_target: Classifier.boolean({
+        instructions: "Is the run still working on the task as stated? Read the task and the newest frames' cells and prose.",
+        criteria: {
+            true: "the newest frames read, edit or check the thing the task names",
+            false: "the newest frames work on something the task does not ask for, or have drifted from it"
+        }
+    }),
+    suspect: Classifier.boolean({
+        instructions: "Is the run's evidence suspect? Read the newest frames for tests edited to pass, edits to a file the task does not concern, or prose claiming a result no printed output shows.",
+        criteria: {
+            true: "a test was changed rather than the code under test, the wrong file was edited, or a claim has no check behind it",
+            false: "edits are to the code the task names and every claim has a printed result behind it"
+        }
+    }),
+    outdated_context: Classifier.boolean({
+        instructions: "Do the newest frames show earlier context that is now factually wrong or stale? Judge only evidence visible in the task and frames; do not assume unseen history is outdated.",
+        criteria: {
+            true: "a later observation explicitly contradicts an earlier assumption or file state in the visible frames",
+            false: "no visible contradiction, or the earlier context is still accurate"
+        }
+    }),
+    irrelevant_context: Classifier.boolean({
+        instructions: "Do the newest frames show earlier context that is accurate but no longer useful for the task? Do not treat the task, a reusable PRD, or decisions still needed as irrelevant.",
+        criteria: {
+            true: "the visible frames explicitly move away from earlier work that will not be needed again",
+            false: "the earlier work may still be needed, or the visible frames do not establish irrelevance"
+        }
+    }),
+    frustrated: Classifier.score({
+        instructions: "How frustrated is the run: the same check failing repeatedly, edits reverted, attempts not converging? Read signals.checksFailing, signals.failuresUnanswered, signals.repeatFrames, signals.readOnlyFrames and the newest frames.",
+        criteria: levels
+    }),
+    anxious: Classifier.score({
+        instructions: "How anxious is the run: its own prose hedges or expresses uncertainty while the evidence is thin? Read the frames' prose against signals.checksRun and signals.callsSettled.",
+        criteria: levels
+    }),
+    scared: Classifier.score({
+        instructions: "How scared should a person be: is the run taking or considering a destructive, irreversible or out-of-scope action, or hitting permission or sandbox refusals? Read the newest frames' cells, prints and failed calls.",
+        criteria: levels
+    }),
+    confused: Classifier.score({
+        instructions: "How confused is the run: the task is ambiguous or contradicted by the repository, and the run keeps switching interpretations or files? Read the task against the newest frames.",
+        criteria: levels
+    }),
+    confident: Classifier.score({
+        instructions: "How confident should a person be that the work converges on the task: checks pass and each frame builds on the last? Read signals.checksRun, signals.checksFailing, signals.mutations and the newest frames.",
+        criteria: levels
+    }),
+    needs_help: Classifier.choice({
+        instructions: "What, if anything, does the run need from a person right now? Read the states above and the newest frames.",
+        criteria: {
+            none: "nothing; the run can carry on",
+            clarification: "the task is ambiguous or contradicted and a person must say which reading is meant",
+            permission: "the run is blocked on a permission or sandbox refusal a person can grant",
+            stuck: "the run is not converging and a person should intervene",
+            risky_action: "the run is about to do something destructive, irreversible or out of scope"
+        }
+    })
+};
+/**
+ * The prefix of every question a monitor adds to a reading; the rest of the
+ * id is the monitor's own.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const monitorPrefix = "monitor_";
+const declare = (extra) => Classifier.make("supervisor/turn", {
+    description: "Read one running agent's newest frames and the counts its harness keeps: whether it is thrashing, on the task and honest; its operational state in five scored words; and what it needs from a person.",
+    state: Snapshot,
+    questions: { ...fixedQuestions, ...extra }
+});
+const cache = new Map();
+/**
+ * The classifier for a snapshot with these monitor questions.
+ *
+ * The fixed questions are the same for every snapshot and the monitors' follow
+ * them, so a snapshot with no monitor questions asks the eleven fixed
+ * questions and no others. Declared once per set of monitor ids, and again
+ * when a monitor id asks a different question, because the digest is the
+ * canonical hash of the questions and the journal names it.
+ *
+ * @category classifiers
+ * @since 1.0.0-rc.0
+ */
+export const classifierFor = (extra) => {
+    const ids = Object.keys(extra).sort();
+    const key = ids.join(",");
+    const held = cache.get(key);
+    if (held !== undefined && ids.every((id) => held.extra[id] === extra[id]))
+        return held.made;
+    const made = declare(extra);
+    cache.set(key, { extra, made });
+    return made;
+};
+/**
+ * The classifier over a bare snapshot: the eleven fixed questions and no
+ * monitor booleans. Its id is the id every shape shares.
+ *
+ * @category classifiers
+ * @since 1.0.0-rc.0
+ */
+export const classifier = classifierFor({});
+/**
+ * Asks Jev about one snapshot, and the monitor questions `extra` adds.
+ *
+ * Fails, typed, whenever an answer could not be obtained: no evaluator bound,
+ * a transport refusal, a deadline, an answer that does not decode. There is
+ * no reading of a snapshot Jev did not read.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const read = (snapshot, extra) => Effect.gen(function* () {
+    const { answers, asked } = yield* Judgement.read(classifierFor(extra), snapshot);
+    const all = answers;
+    // Every declared question is answered or the decode above failed, and a
+    // monitor question is declared exactly for the ids read below.
+    const bool = (id) => all[id].probability;
+    return {
+        thrashing: answers.thrashing.probability,
+        onTarget: answers.on_target.probability,
+        suspect: answers.suspect.probability,
+        outdatedContext: answers.outdated_context.probability,
+        irrelevantContext: answers.irrelevant_context.probability,
+        emotions: {
+            frustrated: answers.frustrated.label,
+            anxious: answers.anxious.label,
+            scared: answers.scared.label,
+            confused: answers.confused.label,
+            confident: answers.confident.label
+        },
+        needsHelp: answers.needs_help.value,
+        monitors: Object.fromEntries(Object.keys(extra).map((id) => [id.slice(monitorPrefix.length), bool(id)])),
+        latencyMs: asked.latencyMs,
+        ...(asked.usage === undefined ? {} : { usage: asked.usage }),
+        asked: { digest: asked.digest, questions: asked.questions, state: asked.state, answers: asked.answers }
+    };
+});
+/**
+ * A memory with nothing behind it.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const memoryNone = {
+    bound: false,
+    recall: () => Effect.succeed([]),
+    remember: () => Effect.void
+};
+/**
+ * The {@link Memory} reference, defaulting to {@link memoryNone}.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export const Memory = Context.Reference("@smthrs/harness/Supervisor/Memory", {
+    defaultValue: () => memoryNone
+});
+/**
+ * The five triggers a reading fires, by name, each with the inequality that
+ * fires it. The one rule: the `supervisor` lint monitor crosses on it,
+ * {@link nudge} names from it, {@link compacting} reads its context triggers,
+ * and the offline replay scores it, so they cannot drift apart.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const triggers = {
+    thrashing: (reading) => reading.thrashing >= thrashingAt,
+    off_target: (reading) => reading.onTarget <= offTargetAt,
+    suspect: (reading) => reading.suspect >= suspectAt,
+    outdated_context: (reading) => reading.outdatedContext >= contextAt,
+    irrelevant_context: (reading) => reading.irrelevantContext >= contextAt
+};
+/**
+ * The triggers one reading fires, in declaration order.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const triggered = (reading) => Object.keys(triggers).filter((name) => triggers[name](reading));
+/**
+ * The triggers that compact the run's context instead of nudging it.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const contextTriggers = ["outdated_context", "irrelevant_context"];
+const isContext = (trigger) => contextTriggers.includes(trigger);
+/**
+ * Whether one reading crosses: any trigger but a context one fires. A context
+ * trigger compacts the run's context at the next frame instead; see
+ * {@link compacting}.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const crosses = (reading) => triggered(reading).some((trigger) => !isContext(trigger));
+/**
+ * The context triggers one reading fires, in declaration order: why a judged
+ * run that is sent this reading compacts at its next frame.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const compacting = (reading) => triggered(reading).filter(isContext);
+/**
+ * The nudge a crossed reading puts in front of the run, naming its evidence.
+ *
+ * Concise on purpose, and built from counts rather than from the model's
+ * prose: what the run is told is what the harness measured, and the reading's
+ * probabilities say only which measurements to name.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const nudge = (snapshot, reading) => {
+    const { signals } = snapshot;
+    const said = {
+        thrashing: `repeating itself (thrashing ${reading.thrashing.toFixed(2)})`,
+        off_target: `drifting from the task (on target ${reading.onTarget.toFixed(2)})`,
+        suspect: `standing on suspect evidence (suspect ${reading.suspect.toFixed(2)})`
+    };
+    const found = triggered(reading).flatMap((name) => isContext(name) ? [] : [said[name]]);
+    const evidence = [];
+    if (signals.checksFailing > 0) {
+        evidence.push(`${signals.checksFailing} check${signals.checksFailing === 1 ? "" : "s"} last reported failing`);
+    }
+    if (signals.failuresUnanswered > 0) {
+        evidence.push(`${signals.failuresUnanswered} failing check${signals.failuresUnanswered === 1 ? "" : "s"} never answered by a pass`);
+    }
+    if (signals.repeatFrames > 0)
+        evidence.push(`${signals.repeatFrames} consecutive frames repeated earlier calls`);
+    if (signals.readOnlyFrames > 0)
+        evidence.push(`${signals.readOnlyFrames} consecutive frames changed nothing`);
+    if (signals.callsFailed > 0)
+        evidence.push(`${signals.callsFailed} of ${signals.callsSettled} calls failed`);
+    evidence.push(`${signals.mutations} frame${signals.mutations === 1 ? "" : "s"} changed the workspace`);
+    // The counts are the ones the run held when frame N closed; by the time the
+    // run reads this it has written at least one frame more, so the frame is named.
+    return `Supervisor: a reading of this run's last ${snapshot.frames.length} frames, through frame ${signals.frame}, finds it ${found.join(", ")}. Evidence at frame ${signals.frame}: ${evidence.join("; ")}. Before the next call, state in one sentence which mechanism you now believe is wrong and which single call would show it; then make that call. Do not re-run a check over an unchanged tree, and do not edit a test to make it pass.`;
+};
+/**
+ * Renders one recalled row as the run reads it.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const recalledInsert = (row) => `From memory of this repository (${row.key}):\n${row.text}`;
+/**
+ * The head of a frame's cell or prose, bounded by {@link frameBytes}.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const head = (text) => elide.head(text.trim(), frameBytes, "clipped");
+/**
+ * The newest {@link frameBytes} of a frame's prints.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const tail = (text) => {
+    const trimmed = text.trim();
+    const kept = elide.tailSlice(trimmed, frameBytes);
+    return kept.length === trimmed.length ? trimmed : `[… older bytes elided]\n${kept}`;
+};
+const fencedCell = /```(?:cell|typescript|ts|javascript|js)[^\n]*\n[\s\S]*?(?:```|$)/g;
+/**
+ * What the model wrote around its cell: the reply with every fenced cell
+ * removed. The anxiety question reads it, and so does the run-end
+ * transcript miner.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const prose = (text) => text.replace(fencedCell, "").trim();
+//# sourceMappingURL=Supervisor.js.map