@jitsusama/agentic-harness.core 0.1.0

package/dist/ui/path.js

@@ -0,0 +1,40 @@
+/**
+ * Writing a path the way a person would say it.
+ *
+ * Absolute paths under a home directory carry a prefix that is the same on every
+ * line and tells the reader nothing. A tree listing is the worst case: two lines
+ * where the interesting halves are a key and a provider, and the widest thing on
+ * screen is a directory nobody has to type.
+ */
+import { homedir } from "node:os";
+import { sep } from "node:path";
+/**
+ * A path with the home directory written as `~`.
+ *
+ * **For display only.** The result is not a path any tool can open: `~` is a
+ * shell courtesy, not a filesystem entry, and expanding it is the shell's job.
+ * So this belongs in the text a person reads and never in the `details` of a
+ * tool answer, where a caller may reasonably feed a path straight back into
+ * another call. When both are wanted, abbreviate the view and keep the absolute
+ * path in the details.
+ *
+ * Rewrites a leading home prefix and nothing else. A relative path is returned
+ * as it came, which is what makes this safe to apply to a list that mixes the
+ * two: a repo-relative `lib/work/tree.ts` has no prefix to lose. A path that
+ * merely mentions the home directory somewhere in the middle is also left alone,
+ * since only the prefix is a home directory rather than a coincidence.
+ */
+export function displayPath(path, home = homedir()) {
+    // An empty home would turn every path into a tilde, which is the sort of
+    // thing that happens on a machine with no HOME set rather than never.
+    if (home.length === 0)
+        return path;
+    const bare = home.endsWith(sep) ? home.slice(0, -sep.length) : home;
+    if (path === bare)
+        return "~";
+    // The separator is required, so a sibling directory whose name merely starts
+    // with the home directory's name keeps its own name. Without it,
+    // `/Users/joel.gerber.backup` reads as `~.backup`, which looks like a file
+    // inside home and is a different place entirely.
+    return path.startsWith(bare + sep) ? `~${path.slice(bare.length)}` : path;
+}

package/dist/verify/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public API for the `verify` domain: run the project's check
+ * command and report whether it still builds and passes.
+ *
+ * This is the "on request" layer only. pi also has a fast,
+ * turn-boundary auto-verify layer backed by a resident LSP client
+ * it keeps running; that has no equivalent adapter-side resource
+ * here (a hook process has no shared LSP session to query), so it
+ * stays pi-only rather than being approximated into something
+ * slower and heavier than what it replaces.
+ */
+export type { ProjectInfo } from "./project.js";
+export { detectPackageManager, findProject } from "./project.js";
+export type { CheckCommandSources, ResolvedCheck } from "./resolve.js";
+export { resolveCheckCommand } from "./resolve.js";
+export type { RunVerifyOptions, VerifyOutcome } from "./run.js";
+export { runVerify, stripAnsi, truncate } from "./run.js";

package/dist/verify/index.js

@@ -0,0 +1,14 @@
+/**
+ * Public API for the `verify` domain: run the project's check
+ * command and report whether it still builds and passes.
+ *
+ * This is the "on request" layer only. pi also has a fast,
+ * turn-boundary auto-verify layer backed by a resident LSP client
+ * it keeps running; that has no equivalent adapter-side resource
+ * here (a hook process has no shared LSP session to query), so it
+ * stays pi-only rather than being approximated into something
+ * slower and heavier than what it replaces.
+ */
+export { detectPackageManager, findProject } from "./project.js";
+export { resolveCheckCommand } from "./resolve.js";
+export { runVerify, stripAnsi, truncate } from "./run.js";

package/dist/verify/project.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Project detection for the verify domain: walk up to the nearest
+ * package.json and read its scripts, so the check command can be
+ * resolved without the caller having to name a project directory.
+ */
+export interface ProjectInfo {
+    readonly dir: string;
+    readonly scripts: Readonly<Record<string, string>>;
+    readonly packageManager: string;
+}
+/** Walk up from startDir to the nearest package.json, reading its scripts. */
+export declare function findProject(startDir: string): ProjectInfo | null;
+/**
+ * Infer the package manager: an explicit Corepack `packageManager`
+ * field wins, then the lockfile present in dir. Falls back to npm,
+ * not pnpm, when neither is present: npm ships with Node itself, so
+ * it is the one manager guaranteed to exist, unlike a guess that
+ * turns "no lockfile yet" (a freshly scaffolded project, before the
+ * first install) into a false "command not found" failure.
+ */
+export declare function detectPackageManager(dir: string, declared?: string): string;

package/dist/verify/project.js

@@ -0,0 +1,49 @@
+/**
+ * Project detection for the verify domain: walk up to the nearest
+ * package.json and read its scripts, so the check command can be
+ * resolved without the caller having to name a project directory.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Walk up from startDir to the nearest package.json, reading its scripts. */
+export function findProject(startDir) {
+    let dir = startDir;
+    while (true) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                return {
+                    dir,
+                    scripts: pkg.scripts ?? {},
+                    packageManager: detectPackageManager(dir, pkg.packageManager),
+                };
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Infer the package manager: an explicit Corepack `packageManager`
+ * field wins, then the lockfile present in dir. Falls back to npm,
+ * not pnpm, when neither is present: npm ships with Node itself, so
+ * it is the one manager guaranteed to exist, unlike a guess that
+ * turns "no lockfile yet" (a freshly scaffolded project, before the
+ * first install) into a false "command not found" failure.
+ */
+export function detectPackageManager(dir, declared) {
+    const fromField = declared?.split("@")[0]?.trim();
+    if (fromField)
+        return fromField;
+    if (existsSync(join(dir, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(dir, "yarn.lock")))
+        return "yarn";
+    return "npm";
+}

package/dist/verify/resolve.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Check-command resolution: pick the command the verify layer
+ * runs, by precedence. An explicit quest-verify field wins because
+ * it is the most specific to the work in hand; then an explicit
+ * verify script; then detection of the conventional lint,
+ * typecheck and test scripts, joined so all run.
+ */
+/** Where a check command could come from. */
+export interface CheckCommandSources {
+    /** A verify command declared in the caller's own project convention (e.g. a loaded quest's frontmatter). */
+    readonly questVerify?: string;
+    /** The scripts block from the project's package.json. */
+    readonly packageScripts?: Readonly<Record<string, string>>;
+    /** The package manager to invoke scripts with. Defaults to pnpm. */
+    readonly packageManager?: string;
+}
+/** The resolved command and where it came from. */
+export interface ResolvedCheck {
+    readonly command: string;
+    readonly source: "quest" | "script" | "detected";
+}
+/**
+ * Resolve the check command, or null when nothing is available
+ * and the caller has nothing to run.
+ */
+export declare function resolveCheckCommand(sources: CheckCommandSources): ResolvedCheck | null;

package/dist/verify/resolve.js

@@ -0,0 +1,27 @@
+/**
+ * Check-command resolution: pick the command the verify layer
+ * runs, by precedence. An explicit quest-verify field wins because
+ * it is the most specific to the work in hand; then an explicit
+ * verify script; then detection of the conventional lint,
+ * typecheck and test scripts, joined so all run.
+ */
+/** Scripts probed for detection, in the order they run. */
+const DETECTED_SCRIPTS = ["lint", "typecheck", "test"];
+/**
+ * Resolve the check command, or null when nothing is available
+ * and the caller has nothing to run.
+ */
+export function resolveCheckCommand(sources) {
+    const quest = sources.questVerify?.trim();
+    if (quest)
+        return { command: quest, source: "quest" };
+    const pm = sources.packageManager ?? "pnpm";
+    const scripts = sources.packageScripts ?? {};
+    if (scripts.verify) {
+        return { command: `${pm} run verify`, source: "script" };
+    }
+    const detected = DETECTED_SCRIPTS.filter((name) => scripts[name]).map((name) => `${pm} run ${name}`);
+    if (detected.length === 0)
+        return null;
+    return { command: detected.join(" && "), source: "detected" };
+}

package/dist/verify/run.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Running the resolved check command and shaping its output for an
+ * agent to read: strip terminal control sequences, cap a runaway
+ * tail, and report pass/fail. This is the "on request" layer only
+ * (a `verify` tool a skill or CLI subcommand exposes) — the fast,
+ * turn-boundary auto-verify layer pi also has depends on a resident
+ * LSP backend pi keeps running, which has no equivalent here, so
+ * it stays pi-only rather than being approximated badly.
+ */
+export declare function stripAnsi(text: string): string;
+/** Cap the captured output so a noisy suite does not flood the reply. */
+export declare function truncate(output: string, maxLines?: number): string;
+export interface RunVerifyOptions {
+    /** Where to look for the nearest package.json and run the command. */
+    readonly cwd: string;
+    /** A verify command from the caller's own project convention, if any. */
+    readonly questVerify?: string;
+    readonly signal?: AbortSignal;
+}
+export interface VerifyOutcome {
+    readonly ok: boolean;
+    readonly command?: string;
+    /** Human-readable summary: what ran, and its tail (pass) or full output (fail). */
+    readonly output: string;
+}
+/**
+ * Resolve and run the project's check command, and shape the
+ * result for an agent to read directly. The one entry point an
+ * adapter needs.
+ */
+export declare function runVerify(options: RunVerifyOptions): Promise<VerifyOutcome>;

package/dist/verify/run.js

@@ -0,0 +1,145 @@
+/**
+ * Running the resolved check command and shaping its output for an
+ * agent to read: strip terminal control sequences, cap a runaway
+ * tail, and report pass/fail. This is the "on request" layer only
+ * (a `verify` tool a skill or CLI subcommand exposes) — the fast,
+ * turn-boundary auto-verify layer pi also has depends on a resident
+ * LSP backend pi keeps running, which has no equivalent here, so
+ * it stays pi-only rather than being approximated badly.
+ */
+import { spawn } from "node:child_process";
+import { findProject } from "./project.js";
+import { resolveCheckCommand } from "./resolve.js";
+/** How long a check command may run. */
+const CHECK_TIMEOUT_MS = 300_000;
+/** Cap on captured check output held in memory (a rolling tail). */
+const MAX_CAPTURE_BYTES = 512 * 1024;
+/**
+ * Strip ANSI escape sequences (colour and cursor control) from
+ * captured output. A test runner emits these even into a pipe, and
+ * left in returned text they smear a plain-text reader.
+ */
+// ESC[ control sequences (colour, cursor) with the full 0x30-0x3F
+// parameter class so `:<=>?` are covered, and ESC] OSC sequences
+// terminated by either BEL or ST (ESC backslash). Built from a
+// string so the source carries no literal control bytes.
+// biome-ignore lint/complexity/useRegexLiterals: a literal would embed control bytes the linter rejects.
+const ANSI_PATTERN = new RegExp("\\u001b\\[[0-9:;<=>?]*[ -/]*[@-~]|\\u001b\\][\\s\\S]*?(?:\\u0007|\\u001b\\\\)", "g");
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+/** Cap the captured output so a noisy suite does not flood the reply. */
+export function truncate(output, maxLines = 200) {
+    const lines = output.split("\n");
+    if (lines.length <= maxLines)
+        return output.trim();
+    return [
+        `... (${lines.length - maxLines} earlier lines omitted)`,
+        ...lines.slice(lines.length - maxLines),
+    ]
+        .join("\n")
+        .trim();
+}
+function runCommand(command, cwd, signal) {
+    return new Promise((resolvePromise) => {
+        // The child runs in its own session (detached) with no stdin
+        // and piped output. Detaching removes the controlling terminal,
+        // so a test-runner descendant cannot write progress straight to
+        // the caller's screen. The environment forces plain,
+        // non-interactive output so nothing tries cursor control in the
+        // first place.
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                CI: "true",
+                NO_COLOR: "1",
+                FORCE_COLOR: "0",
+                TERM: "dumb",
+            },
+        });
+        // Kill the whole process group, not just the shell, so detached
+        // test workers do not outlive an abort or a timeout.
+        const killGroup = () => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                // Already gone, or never grouped; nothing to reap.
+            }
+        };
+        const timer = setTimeout(killGroup, CHECK_TIMEOUT_MS);
+        const onAbort = () => killGroup();
+        // addEventListener does not fire for a signal that is already
+        // aborted, so kill up front in that case; otherwise the
+        // detached suite would run to the timeout after an abort.
+        if (signal?.aborted)
+            killGroup();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        // Keep a rolling tail rather than the whole stream, so a
+        // runaway command cannot grow the buffer without bound for the
+        // whole timeout window; the tail is what the summary keeps.
+        let output = "";
+        const onData = (chunk) => {
+            output += chunk.toString();
+            if (output.length > MAX_CAPTURE_BYTES) {
+                output = output.slice(output.length - MAX_CAPTURE_BYTES);
+            }
+        };
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.on("error", (err) => {
+            cleanup();
+            resolvePromise({
+                code: 1,
+                output: stripAnsi(`${output}\n${err.message}`).trim(),
+            });
+        });
+        child.on("close", (code) => {
+            cleanup();
+            resolvePromise({ code: code ?? 1, output: truncate(stripAnsi(output)) });
+        });
+    });
+}
+/**
+ * Resolve and run the project's check command, and shape the
+ * result for an agent to read directly. The one entry point an
+ * adapter needs.
+ */
+export async function runVerify(options) {
+    const project = findProject(options.cwd);
+    const resolved = resolveCheckCommand({
+        ...(options.questVerify ? { questVerify: options.questVerify } : {}),
+        packageScripts: project?.scripts ?? {},
+        packageManager: project?.packageManager ?? "pnpm",
+    });
+    if (!resolved) {
+        return {
+            ok: false,
+            output: "No verification command found (no lint, typecheck, test or verify script).",
+        };
+    }
+    const run = await runCommand(resolved.command, project?.dir ?? options.cwd, options.signal);
+    if (run.code === 0) {
+        const tail = run.output.split("\n").slice(-12).join("\n").trim();
+        return {
+            ok: true,
+            command: resolved.command,
+            output: `Passed: ${resolved.command}\n\n${tail}`.trim(),
+        };
+    }
+    return {
+        ok: false,
+        command: resolved.command,
+        output: `Failed (exit ${run.code}): ${resolved.command}\n\n${run.output}`.trim(),
+    };
+}

package/dist/web/a11y/announcements.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What a screen reader would have said out loud.
+ *
+ * A sighted reviewer sees a banner appear. A screen reader user
+ * hears something, or hears nothing at all, and nothing is the
+ * bug worth catching. Live regions are the mechanism a page
+ * uses to speak, so watching them answers "what did a screen
+ * reader user hear when I pressed save".
+ */
+import type { Recorded } from "../telemetry/buffer.js";
+/** Something the page announced through a live region. */
+export interface Announcement {
+    readonly politeness: "polite" | "assertive";
+    readonly text: string;
+    /** When it was announced, as epoch milliseconds. */
+    readonly at: number;
+}
+/** Lay out what was announced, in the order it was said. */
+export declare function renderAnnouncements(entries: readonly Recorded<Announcement>[], dropped?: number): string;
+/** The binding an injected observer reports through. */
+export declare const ANNOUNCE_BINDING = "__piAnnounce";
+/** The page-side array of regions the observer has nominated. */
+export declare const CANDIDATE_REGISTRY = "__piLiveCandidates";
+/**
+ * A change the page made somewhere that might be announced.
+ *
+ * The observer decides nothing about whether this is a live
+ * region. It reports where the change happened and lets the
+ * browser rule on it.
+ */
+export interface AnnouncementCandidate {
+    /** Identifies the document; a navigation starts a new one. */
+    readonly epoch: string;
+    /** Position in the page-side registry of nominated regions. */
+    readonly index: number;
+    readonly text: string;
+    readonly at: number;
+}
+/**
+ * Watch the page for anything that might be spoken.
+ *
+ * This is plain JavaScript source rather than a function, on
+ * purpose. Injecting a function serializes whatever the
+ * compiler made of it, and esbuild's keepNames wraps every
+ * named inner binding in a call to a __name helper. The page
+ * has never heard of __name, so the script throws before it
+ * registers, and nothing says so. A lone inline arrow is safe,
+ * which is why the simple evaluate callbacks elsewhere in this
+ * library are still written as functions; anything declaring
+ * helpers of its own is not. Source text survives untouched.
+ *
+ * It runs before the page's own scripts, so changes made during
+ * load are caught too. It reports through a binding the session
+ * installs; with no binding it does nothing rather than throwing
+ * inside the page under inspection.
+ *
+ * It deliberately does not decide politeness. Chrome exposes no
+ * way for page script to ask what the browser computed, and
+ * reimplementing the rules here means missing whatever the
+ * browser knows that this code does not: role=log is live,
+ * aria-live=off is not, and the mapping changes as the ARIA
+ * spec grows. So the observer nominates any region that could
+ * plausibly carry live semantics and the browser rules on it.
+ * Over-nominating costs one lookup; under-nominating loses an
+ * announcement silently, which is the failure that matters.
+ */
+export declare const ANNOUNCEMENT_OBSERVER: string;

package/dist/web/a11y/announcements.js

@@ -0,0 +1,116 @@
+/**
+ * What a screen reader would have said out loud.
+ *
+ * A sighted reviewer sees a banner appear. A screen reader user
+ * hears something, or hears nothing at all, and nothing is the
+ * bug worth catching. Live regions are the mechanism a page
+ * uses to speak, so watching them answers "what did a screen
+ * reader user hear when I pressed save".
+ */
+/** Lay out what was announced, in the order it was said. */
+export function renderAnnouncements(entries, dropped = 0) {
+    if (entries.length === 0)
+        return "Nothing was announced.";
+    const lines = entries.map(({ item }) => `${item.politeness}: ${flatten(item.text)}`);
+    if (dropped > 0) {
+        // First, where the missing ones would have been: the buffer
+        // drops the oldest, so the gap is at the top. It used to go last,
+        // which put the one line saying announcements were lost at the
+        // end of the longest possible view, where a budget removes it. A
+        // reader was then told nothing at all about the gap, which is
+        // worse than a long answer.
+        lines.unshift(`${dropped} earlier announcements were dropped.`, "");
+    }
+    return lines.join("\n");
+}
+/** Put an announcement on one line, the way it is heard. */
+function flatten(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** The binding an injected observer reports through. */
+export const ANNOUNCE_BINDING = "__piAnnounce";
+/** The page-side array of regions the observer has nominated. */
+export const CANDIDATE_REGISTRY = "__piLiveCandidates";
+/**
+ * Watch the page for anything that might be spoken.
+ *
+ * This is plain JavaScript source rather than a function, on
+ * purpose. Injecting a function serializes whatever the
+ * compiler made of it, and esbuild's keepNames wraps every
+ * named inner binding in a call to a __name helper. The page
+ * has never heard of __name, so the script throws before it
+ * registers, and nothing says so. A lone inline arrow is safe,
+ * which is why the simple evaluate callbacks elsewhere in this
+ * library are still written as functions; anything declaring
+ * helpers of its own is not. Source text survives untouched.
+ *
+ * It runs before the page's own scripts, so changes made during
+ * load are caught too. It reports through a binding the session
+ * installs; with no binding it does nothing rather than throwing
+ * inside the page under inspection.
+ *
+ * It deliberately does not decide politeness. Chrome exposes no
+ * way for page script to ask what the browser computed, and
+ * reimplementing the rules here means missing whatever the
+ * browser knows that this code does not: role=log is live,
+ * aria-live=off is not, and the mapping changes as the ARIA
+ * spec grows. So the observer nominates any region that could
+ * plausibly carry live semantics and the browser rules on it.
+ * Over-nominating costs one lookup; under-nominating loses an
+ * announcement silently, which is the failure that matters.
+ */
+export const ANNOUNCEMENT_OBSERVER = `(() => {
+  var BINDING = ${JSON.stringify(ANNOUNCE_BINDING)};
+  var REGISTRY = ${JSON.stringify(CANDIDATE_REGISTRY)};
+  var CANDIDATE_SELECTOR = "[aria-live], [role], output";
+  var epoch = String(Date.now()) + "-" + String(Math.random()).slice(2, 8);
+
+  globalThis[REGISTRY] = [];
+  var indexByElement = new WeakMap();
+
+  function indexOf(element) {
+    var known = indexByElement.get(element);
+    if (known !== undefined) return known;
+    var index = globalThis[REGISTRY].length;
+    globalThis[REGISTRY].push(element);
+    indexByElement.set(element, index);
+    return index;
+  }
+
+  function nominate(index, text) {
+    var sink = globalThis[BINDING];
+    if (sink) {
+      sink({ epoch: epoch, index: index, text: text, at: Date.now() });
+    }
+  }
+
+  function watch() {
+    var observer = new MutationObserver(function (records) {
+      var seen = {};
+      for (var i = 0; i < records.length; i++) {
+        var node = records[i].target;
+        var element = node.nodeType === 1 ? node : node.parentElement;
+        if (!element) continue;
+        var region = element.closest(CANDIDATE_SELECTOR);
+        if (!region) continue;
+        var text = (region.textContent || "").trim();
+        if (!text) continue;
+        var index = indexOf(region);
+        // One edit can raise several records against the same
+        // region; a listener hears it once.
+        var key = String(index) + "\\u0000" + text;
+        if (seen[key]) continue;
+        seen[key] = true;
+        nominate(index, text);
+      }
+    });
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+  }
+
+  if (document.body) watch();
+  else document.addEventListener("DOMContentLoaded", watch);
+})();`;

package/dist/web/a11y/budget.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Keeping a page outline inside a response.
+ *
+ * The outline is the most-returned payload in the whole family:
+ * every read of a page answers with one, and so does every
+ * navigation and every action, because the page after the fact is
+ * how a caller knows what their click did. Lists have been
+ * budgeted since the beginning. The outline was not, and a page
+ * whose outline is small is only the common case, not the rule:
+ * one source file of eighteen thousand lines, each line a
+ * listitem with a button and a text node, renders two and a half
+ * megabytes of perfectly good outline. A wheel scroll returned
+ * all of it.
+ *
+ * So the same rule as everywhere else. The limit is a
+ * presentation default rather than a ceiling, whole lines survive
+ * rather than bytes, and anything cut says so and says how to go
+ * and get it. The page is not the answer's size: narrowing the
+ * view is always available, and it is cheaper than reading the
+ * whole thing and discarding it.
+ */
+import { type BudgetedView } from "@jitsusama/agentic-harness.core/result";
+/**
+ * What an explicit read of a page spends on the outline.
+ *
+ * Generous, because somebody who asked to see the page wants the
+ * page: this fits a normal application view whole and only bites
+ * on the pathological ones.
+ */
+export declare const OUTLINE_BUDGET_BYTES = 16384;
+/**
+ * What the page view after an action spends.
+ *
+ * Tighter, because this outline was not asked for. It is
+ * confirmation of what just happened, and the caller who wants
+ * the page in full can read it in full.
+ */
+export declare const ACTION_VIEW_BUDGET_BYTES = 4096;
+/**
+ * The most an outline will spend, however large a budget is asked
+ * for.
+ *
+ * Every other limit here is a presentation default that a caller
+ * can raise, because nothing should cap what this package can
+ * find out. A budget is different: it is not a limit on the
+ * finding, it is a limit on what gets pasted into a context
+ * window, and the whole point of storing the remainder is that
+ * raising it is never the way to see more. Left open, one call
+ * asking for a hundred megabytes undoes the entire mechanism, and
+ * the model choosing the number is the one party with no idea
+ * what it costs. Four times the generous default, which no real
+ * page reaches.
+ */
+export declare const MAX_OUTLINE_BUDGET_BYTES: number;
+/**
+ * The budget to actually spend, given what was asked for.
+ *
+ * Refuses nothing: a caller who asks for more than the ceiling
+ * gets the ceiling, and the citation then tells them the rest is
+ * queryable, which is what they wanted in the first place.
+ */
+export declare function outlineBudget(asked: number | undefined): number;
+/** An outline cut to fit, and what fitting it cost. */
+export interface BudgetedOutline extends BudgetedView {
+    /** What was cut and how to read it, when anything was. */
+    readonly elided?: string;
+}
+/**
+ * As much of an outline as the budget affords, and never none.
+ *
+ * The cutting is the general rule from agentic-harness.core's result
+ * module; what belongs to the page is the advice about what to do
+ * next, since narrowing a page read has its own vocabulary.
+ */
+export declare function withinOutlineBudget(rendered: string, budget: number): BudgetedOutline;