@iowarp/clio-coder 0.4.6 → 0.4.8

package/dist/chunk-526ABLHD.js

@@ -0,0 +1,1219 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  formatSize,
+  truncateHead,
+  truncateTail
+} from "./chunk-KECNXMDE.js";
+import {
+  INSTRUCTION_SHAPED_WARNING
+} from "./chunk-WXA2CFJO.js";
+import {
+  createSafetyPolicyEngine
+} from "./chunk-RAUOKUZV.js";
+import {
+  byteLength,
+  truncateUtf8
+} from "./chunk-MYI32N4R.js";
+import {
+  GUARDRAIL_DEFAULTS,
+  resolveGuardrail
+} from "./chunk-C27U2TYG.js";
+import {
+  createRedactionTally,
+  redactSecretsText
+} from "./chunk-O3VV6IVK.js";
+import {
+  clioStateDir
+} from "./chunk-CTTI7G3T.js";
+import {
+  init_esm_shims
+} from "./chunk-ECBHH7LU.js";
+
+// src/tools/truncate.ts
+init_esm_shims();
+var DEFAULT_MAX_LINES = 2e3;
+var DEFAULT_MAX_BYTES = 64 * 1024;
+function splitLinesForCounting(content) {
+  if (content.length === 0) return [];
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines;
+}
+function withClioDefaults(options) {
+  return {
+    maxLines: options.maxLines ?? DEFAULT_MAX_LINES,
+    maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES
+  };
+}
+function truncateHead2(content, options = {}) {
+  return truncateHead(content, withClioDefaults(options));
+}
+function truncateTail2(content, options = {}) {
+  return truncateTail(content, withClioDefaults(options));
+}
+
+// src/tools/result-shaping.ts
+init_esm_shims();
+import { createHash as createHash2 } from "node:crypto";
+import { mkdirSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+// src/tools/result-disposition.ts
+init_esm_shims();
+import { createHash } from "node:crypto";
+var TOOL_RESULT_DIGEST_MAX_BYTES = 240;
+var ESSENTIAL_DETAIL_KEYS = /* @__PURE__ */ new Set([
+  "aborted",
+  "continuation",
+  "continuationHint",
+  "decision",
+  "error",
+  "errors",
+  "evidence",
+  "exitCode",
+  "exitStatus",
+  "outputBytes",
+  "outputCapped",
+  "next",
+  "outcome",
+  "safety",
+  "safetyDecision",
+  "status",
+  "signal",
+  "terminate",
+  "timedOut",
+  "retainedBytes",
+  "stderrBytes",
+  "stdoutBytes"
+]);
+function positiveByteCap(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function normalizeToolResultDisposition(spec, hardMaxBytes, requested = spec.metadata?.resultDisposition) {
+  const declared = requested;
+  if (declared === void 0) return null;
+  const hardCap = positiveByteCap(hardMaxBytes, 1);
+  const presentationCap = Math.min(positiveByteCap(declared.presentation.maxBytes, hardCap), hardCap);
+  const contextCap = Math.min(positiveByteCap(declared.context.maxBytes, hardCap), hardCap);
+  return {
+    presentation: {
+      foldDefault: declared.presentation.foldDefault,
+      showDiffWhenFolded: declared.presentation.showDiffWhenFolded,
+      failureExcerpt: declared.presentation.failureExcerpt,
+      maxBytes: presentationCap,
+      ...declared.presentation.overflow === void 0 ? {} : { overflow: declared.presentation.overflow }
+    },
+    context: { ...declared.context, maxBytes: contextCap },
+    ...declared.fallback === void 0 ? {} : { fallback: declared.fallback }
+  };
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stableValue(value, seen) {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return "[circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const items = value.map((item) => stableValue(item, seen));
+    seen.delete(value);
+    return items;
+  }
+  const record = value;
+  const out = {};
+  for (const key of Object.keys(record).sort()) out[key] = stableValue(record[key], seen);
+  seen.delete(value);
+  return out;
+}
+function stableJson(value) {
+  try {
+    return JSON.stringify(stableValue(value, /* @__PURE__ */ new Set())) ?? "null";
+  } catch {
+    return JSON.stringify(String(value));
+  }
+}
+function essentialFacts(details) {
+  if (details === void 0) return null;
+  const facts = {};
+  for (const key of Object.keys(details).sort()) {
+    if (ESSENTIAL_DETAIL_KEYS.has(key)) facts[key] = details[key];
+  }
+  const observation = isRecord(details.observation) ? details.observation : null;
+  if (observation !== null && observation.next !== void 0) facts.next = observation.next;
+  return Object.keys(facts).length > 0 ? facts : null;
+}
+function utf8Prefix(text, maxBytes) {
+  if (maxBytes <= 0) return "";
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= maxBytes) return text;
+  let end = Math.min(maxBytes, buffer.byteLength);
+  while (end > 0 && end < buffer.byteLength && (buffer[end] ?? 0) >>> 6 === 2) end -= 1;
+  return buffer.subarray(0, end).toString("utf8");
+}
+function utf8Suffix(text, maxBytes) {
+  if (maxBytes <= 0) return "";
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= maxBytes) return text;
+  let start = Math.max(0, buffer.byteLength - maxBytes);
+  while (start < buffer.byteLength && (buffer[start] ?? 0) >>> 6 === 2) start += 1;
+  return buffer.subarray(start).toString("utf8");
+}
+function capUtf8(text, maxBytes) {
+  return byteLength(text) <= maxBytes ? text : utf8Prefix(text, maxBytes);
+}
+function capDigestUtf8(text, maxBytes) {
+  if (byteLength(text) <= maxBytes) return text;
+  const marker = "\u2026";
+  const markerBytes = byteLength(marker);
+  if (markerBytes >= maxBytes) return utf8Prefix(text, maxBytes);
+  return `${utf8Prefix(text, maxBytes - markerBytes).trimEnd()}${marker}`;
+}
+function boundedToolResultExcerpt(text, maxBytes, bias = "head-tail") {
+  if (maxBytes <= 0) return "";
+  if (byteLength(text) <= maxBytes) return text;
+  if (bias === "tail") return utf8Suffix(text, maxBytes);
+  const marker = "\n[\u2026 omitted \u2026]\n";
+  const markerBytes = byteLength(marker);
+  if (markerBytes >= maxBytes) return utf8Prefix(text, maxBytes);
+  const bodyBudget = maxBytes - markerBytes;
+  const headBudget = Math.floor(bodyBudget / 2);
+  const tailBudget = bodyBudget - headBudget;
+  return `${utf8Prefix(text, headBudget)}${marker}${utf8Suffix(text, tailBudget)}`;
+}
+function sourceLineCount(text) {
+  if (text.length === 0) return 0;
+  return text.replace(/\r\n/gu, "\n").replace(/\r/gu, "\n").split("\n").length;
+}
+function summaryProvenance(text, algorithm = "sha256-head-tail-v1", redactions = 0) {
+  return {
+    producer: "code",
+    algorithm,
+    sourceSha256: createHash("sha256").update(text).digest("hex"),
+    sourceLines: sourceLineCount(text),
+    ...redactions > 0 ? { redactions } : {}
+  };
+}
+var ERROR_LIKE_LINE = /(?:\b(?:abort(?:ed)?|assert(?:ion)?|error|exception|fail(?:ed|ure)?|fatal|killed|panic|signal|timed?\s*out|timeout)\b|\bnot ok\b|\bERR!\b)/iu;
+var SUMMARY_LINE_MAX_BYTES = 768;
+function summaryLine(line) {
+  return boundedToolResultExcerpt(line, SUMMARY_LINE_MAX_BYTES);
+}
+function normalizeNewlines(text) {
+  return text.replace(/\r\n/gu, "\n").replace(/\r/gu, "\n");
+}
+function contentLines(text) {
+  return normalizeNewlines(text).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+}
+function deterministicHeadTailSummary(text, redact = true) {
+  const tally = createRedactionTally();
+  const safeText = redact ? redactSecretsText(text, tally) : text;
+  return { text: contentLines(safeText).join("\n"), redactions: tally.count, complete: tally.count === 0 };
+}
+function renderSummarySection(label, lines) {
+  return lines.length === 0 ? "" : `[${label}]
+${lines.map(summaryLine).join("\n")}`;
+}
+function deterministicDiagnosticSummary(text, maxBytes, redact = true) {
+  if (maxBytes <= 0 || text.length === 0) return { text: "", redactions: 0, complete: text.length === 0 };
+  const tally = createRedactionTally();
+  const safeText = redact ? redactSecretsText(text, tally) : text;
+  const lines = normalizeNewlines(safeText).split("\n");
+  const nonempty = lines.map((line, index) => ({ line: line.trim(), index })).filter((entry) => entry.line.length > 0);
+  if (nonempty.length === 0) return { text: "", redactions: tally.count, complete: tally.count === 0 };
+  if (nonempty.length === 1) {
+    const only = nonempty[0]?.line ?? "";
+    return {
+      text: boundedToolResultExcerpt(only, maxBytes),
+      redactions: tally.count,
+      complete: tally.count === 0 && byteLength(only) <= maxBytes
+    };
+  }
+  const head = nonempty.slice(0, 4);
+  const tail = nonempty.slice(Math.max(head.length, nonempty.length - 6));
+  const edgeIndexes = new Set([...head, ...tail].map((entry) => entry.index));
+  const diagnostics = nonempty.filter((entry) => !edgeIndexes.has(entry.index) && ERROR_LIKE_LINE.test(entry.line));
+  const sections = [
+    renderSummarySection(
+      "diagnostic head",
+      head.map((entry) => entry.line)
+    ),
+    renderSummarySection(
+      "error-like lines",
+      diagnostics.map((entry) => entry.line)
+    ),
+    renderSummarySection(
+      "diagnostic tail",
+      tail.map((entry) => entry.line)
+    )
+  ].filter((section) => section.length > 0);
+  const selected = [...head, ...diagnostics, ...tail];
+  const keepsEveryLine = selected.length === nonempty.length && selected.every((entry) => byteLength(entry.line) <= SUMMARY_LINE_MAX_BYTES);
+  const rendered = keepsEveryLine ? selected.map((entry) => summaryLine(entry.line)).join("\n") : sections.join("\n");
+  if (byteLength(rendered) <= maxBytes) {
+    return { text: rendered, redactions: tally.count, complete: keepsEveryLine && tally.count === 0 };
+  }
+  const weights = diagnostics.length > 0 ? [0.25, 0.45, 0.3] : [0.4, 0, 0.6];
+  const boundedSections = [];
+  for (const [index, section] of sections.entries()) {
+    const weight = diagnostics.length > 0 ? weights[index] ?? 0 : index === 0 ? 0.4 : 0.6;
+    const budget = Math.floor(maxBytes * weight);
+    if (budget > 0) boundedSections.push(boundedToolResultExcerpt(section ?? "", budget));
+  }
+  return { text: capUtf8(boundedSections.join("\n"), maxBytes), redactions: tally.count, complete: false };
+}
+function retrievalLine(offloadPath, followUpHint2) {
+  return offloadPath === null ? `retrieve=${JSON.stringify(followUpHint2)}` : `retrieve=${JSON.stringify(`read ${offloadPath} with offset and limit`)}`;
+}
+function contextHeader(input, appliedMode, truncated, provenance) {
+  const lines = [
+    `[tool-result ${appliedMode}]`,
+    `kind=${input.kind} capturedBytes=${input.capturedBytes} displayedBytes=${input.displayedBytes} truncated=${String(truncated)}`,
+    retrievalLine(input.offloadPath, input.followUpHint),
+    `followUp=${JSON.stringify(input.followUpHint)}`
+  ];
+  if (provenance !== void 0) {
+    lines.push(`summary=code/${provenance.algorithm} sha256=${provenance.sourceSha256} lines=${provenance.sourceLines}`);
+  }
+  if (input.disposition.fallback !== void 0) {
+    lines.push(`fallback=${input.disposition.fallback.reason} ${JSON.stringify(input.disposition.fallback.message)}`);
+  }
+  const facts = essentialFacts(input.details);
+  if (facts !== null) lines.push(`facts=${stableJson(facts)}`);
+  return lines.join("\n");
+}
+function joinHeaderAndBody(header, body, maxBytes, bias = "head-tail") {
+  if (body.length === 0) return capUtf8(header, maxBytes);
+  const separator = "\n";
+  const headerBytes = byteLength(header);
+  const separatorBytes = byteLength(separator);
+  if (headerBytes + separatorBytes >= maxBytes) return capUtf8(header, maxBytes);
+  const bodyBudget = maxBytes - headerBytes - separatorBytes;
+  return `${header}${separator}${boundedToolResultExcerpt(body, bodyBudget, bias)}`;
+}
+function fullTrailer(input) {
+  const facts = essentialFacts(input.details);
+  const lines = [];
+  if (facts !== null) lines.push(`facts=${stableJson(facts)}`);
+  if (input.followUpHint.length > 0) lines.push(`followUp=${JSON.stringify(input.followUpHint)}`);
+  return lines.length === 0 ? "" : `[tool-result metadata]
+${lines.join("\n")}`;
+}
+var NUL = "\0";
+function stripNulForContext(text) {
+  const parts = text.split(NUL);
+  return parts.length === 1 ? { text, stripped: 0 } : { text: parts.join(""), stripped: parts.length - 1 };
+}
+function projectToolResultContext(input) {
+  const requestedMode = input.disposition.context.mode;
+  const maxBytes = input.disposition.context.maxBytes;
+  const sanitized = stripNulForContext(input.text);
+  const body = sanitized.text;
+  const capturedTextIsComplete = input.capturedBytes <= byteLength(input.text) && sanitized.stripped === 0;
+  if (requestedMode === "full") {
+    const trailer = fullTrailer(input);
+    const candidate = trailer.length === 0 ? body : `${body}
+
+${trailer}`;
+    if (capturedTextIsComplete && byteLength(candidate) <= maxBytes) {
+      return { text: candidate, appliedMode: "full", truncated: false };
+    }
+    const header2 = contextHeader(input, "bounded", true);
+    return {
+      text: joinHeaderAndBody(header2, body, maxBytes, input.disposition.context.downgradeExcerpt),
+      appliedMode: "bounded",
+      truncated: true,
+      downgrade: { from: "full", to: "bounded", reason: "hard-budget" }
+    };
+  }
+  if (requestedMode === "metadata-only") {
+    return {
+      text: capUtf8(contextHeader(input, "metadata-only", input.capturedBytes > 0), maxBytes),
+      appliedMode: "metadata-only",
+      truncated: input.capturedBytes > 0
+    };
+  }
+  if (requestedMode === "summary") {
+    const diagnostic = input.disposition.context.strategy === "diagnostic";
+    const algorithm = diagnostic ? "sha256-diagnostic-v1" : "sha256-head-tail-v1";
+    const redact = input.disposition.context.redact !== false;
+    const budgetHeader = contextHeader(input, "summary", true, summaryProvenance(input.text, algorithm));
+    const bodyBudget = Math.max(0, maxBytes - byteLength(budgetHeader) - 1);
+    const selected = diagnostic ? deterministicDiagnosticSummary(body, bodyBudget, redact) : deterministicHeadTailSummary(body, redact);
+    const provenance = summaryProvenance(input.text, algorithm, selected.redactions);
+    const completeHeader = contextHeader(input, "summary", false, provenance);
+    const fits = byteLength(completeHeader) + 1 + byteLength(selected.text) <= maxBytes;
+    const truncated = input.capturedBytes > 0 && !(capturedTextIsComplete && selected.complete && fits);
+    const header2 = contextHeader(input, "summary", truncated, provenance);
+    return {
+      text: joinHeaderAndBody(header2, selected.text, maxBytes),
+      appliedMode: "summary",
+      truncated,
+      summaryProvenance: provenance
+    };
+  }
+  const header = contextHeader(input, "bounded", input.capturedBytes > maxBytes);
+  const text = joinHeaderAndBody(header, body, maxBytes, input.disposition.context.excerpt);
+  return {
+    text,
+    appliedMode: "bounded",
+    truncated: byteLength(header) + 1 + byteLength(body) > maxBytes || !capturedTextIsComplete
+  };
+}
+var DIGEST_FACT_KEYS = [
+  "outcome",
+  "exitCode",
+  "timedOut",
+  "aborted",
+  "outputCapped",
+  "signal",
+  "status",
+  "error",
+  "decision",
+  "next"
+];
+function digestFactText(details) {
+  if (details === void 0) return "";
+  const facts = [];
+  for (const key of DIGEST_FACT_KEYS) {
+    if (details[key] !== void 0) facts.push(`${key}=${stableJson(details[key])}`);
+  }
+  return facts.join(" ");
+}
+function projectionBody(input, projection) {
+  if (projection.appliedMode === "metadata-only") return "";
+  if (projection.appliedMode === "full") {
+    const trailer = fullTrailer(input);
+    return trailer.length > 0 && projection.text.endsWith(`
+
+${trailer}`) ? projection.text.slice(0, -(trailer.length + 2)) : projection.text;
+  }
+  const header = contextHeader(input, projection.appliedMode, projection.truncated, projection.summaryProvenance);
+  const prefix = `${header}
+`;
+  return projection.text.startsWith(prefix) ? projection.text.slice(prefix.length) : "";
+}
+function digestText(status, facts, body, redactions, maxBytes) {
+  const tally = createRedactionTally();
+  const safeStatus = redactSecretsText(status, tally);
+  const safeFacts = redactSecretsText(facts, tally);
+  const statusAndFacts = [safeStatus, safeFacts].filter((value) => value.length > 0).join(" ");
+  const bodyBudget = Math.max(0, maxBytes - byteLength(statusAndFacts) - 2);
+  const selected = deterministicDiagnosticSummary(body, bodyBudget, true);
+  const candidate = [statusAndFacts, selected.text.replace(/\s+/gu, " ").trim()].filter((value) => value.length > 0).join("; ");
+  return {
+    text: capDigestUtf8(candidate, maxBytes),
+    redactions: redactions + tally.count + selected.redactions
+  };
+}
+function deterministicToolResultDigest(input, maxBytes = TOOL_RESULT_DIGEST_MAX_BYTES) {
+  const projection = projectToolResultContext(input);
+  const status = [
+    `kind=${input.kind}`,
+    `mode=${projection.appliedMode}`,
+    `truncated=${String(projection.truncated)}`,
+    ...projection.appliedMode === "metadata-only" || projection.truncated ? [`capturedBytes=${input.capturedBytes}`] : []
+  ].join(" ");
+  const digest = digestText(
+    status,
+    digestFactText(input.details),
+    projectionBody(input, projection),
+    projection.summaryProvenance?.redactions ?? 0,
+    Math.max(1, Math.floor(maxBytes))
+  );
+  return {
+    text: digest.text,
+    provenance: {
+      producer: "code",
+      source: "canonical-result-disposition",
+      algorithm: "redacted-context-digest-v1",
+      contextMode: projection.appliedMode,
+      ...projection.summaryProvenance === void 0 ? {} : { summaryAlgorithm: projection.summaryProvenance.algorithm },
+      ...digest.redactions > 0 ? { redactions: digest.redactions } : {}
+    }
+  };
+}
+function legacyToolResultDigest(text, options) {
+  const maxBytes = Math.max(1, Math.floor(options.maxBytes ?? TOOL_RESULT_DIGEST_MAX_BYTES));
+  const fallback = options.outcome === "error" && text.trim().length === 0 ? "an unknown tool error" : text;
+  const digest = digestText("", "", fallback, 0, maxBytes);
+  return {
+    text: digest.text,
+    provenance: {
+      producer: "code",
+      source: "legacy-fallback",
+      algorithm: "redacted-legacy-digest-v1",
+      ...digest.redactions > 0 ? { redactions: digest.redactions } : {}
+    }
+  };
+}
+function sanitizeToolResultDigest(digest, maxBytes = TOOL_RESULT_DIGEST_MAX_BYTES) {
+  const tally = createRedactionTally();
+  const safe = redactSecretsText(digest.text, tally).replace(/\s+/gu, " ").trim();
+  const redactions = (digest.provenance.redactions ?? 0) + tally.count;
+  return {
+    text: capDigestUtf8(safe, Math.max(1, Math.floor(maxBytes))),
+    provenance: {
+      ...digest.provenance,
+      ...redactions > 0 ? { redactions } : {}
+    }
+  };
+}
+function toolResultContextText(result) {
+  if (result.modelContext !== void 0) return result.modelContext;
+  return result.kind === "ok" ? result.output : result.message;
+}
+function isDispositionedToolResultError(result) {
+  if (!isRecord(result)) return false;
+  const details = isRecord(result.details) ? result.details : null;
+  const metadata = details !== null && isRecord(details.resultDisposition) ? details.resultDisposition : null;
+  const kind = result.kind ?? details?.kind;
+  return kind === "error" && metadata?.version === 1 && metadata.applications === 1;
+}
+function toolResultPresentationText(result) {
+  if (!isRecord(result)) return null;
+  const details = isRecord(result.details) ? result.details : null;
+  const metadata = details !== null && isRecord(details.resultDisposition) ? details.resultDisposition : null;
+  const presentation = metadata !== null && isRecord(metadata.presentation) ? metadata.presentation : null;
+  return presentation !== null && typeof presentation.content === "string" ? presentation.content : null;
+}
+function toolResultPresentationPolicy(result) {
+  if (!isRecord(result)) return null;
+  const details = isRecord(result.details) ? result.details : null;
+  const metadata = details !== null && isRecord(details.resultDisposition) ? details.resultDisposition : null;
+  const presentation = metadata !== null && isRecord(metadata.presentation) ? metadata.presentation : null;
+  if (presentation === null || presentation.foldDefault !== "folded" && presentation.foldDefault !== "expanded" || typeof presentation.showDiffWhenFolded !== "boolean" || typeof presentation.failureExcerpt !== "boolean") {
+    return null;
+  }
+  return {
+    foldDefault: presentation.foldDefault,
+    showDiffWhenFolded: presentation.showDiffWhenFolded,
+    failureExcerpt: presentation.failureExcerpt
+  };
+}
+
+// src/tools/result-shaping.ts
+var DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES;
+var RESULT_TRUNCATION_MARKER = "\n[tool result truncated]";
+var RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
+var TAIL_NOTICE_RESERVE_BYTES = 512;
+var TOOL_OFFLOAD_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1e3;
+function mergeDetails(details, resultSize) {
+  return { ...details ?? {}, resultSize };
+}
+function maxBytesFor(spec, context) {
+  const configured = spec.metadata?.resultSizePolicy?.maxBytes;
+  const policyMax = typeof configured === "number" && Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : DEFAULT_TOOL_RESULT_MAX_BYTES;
+  const sessionMax = context?.toolResultMaxBytes;
+  return typeof sessionMax === "number" && Number.isFinite(sessionMax) && sessionMax > 0 ? Math.min(policyMax, Math.floor(sessionMax)) : policyMax;
+}
+function followUpHint(spec) {
+  return spec.metadata?.resultSizePolicy?.followUpHint ?? "Use a narrower query, offset/limit arguments, or a more specific tool call to inspect the omitted content.";
+}
+function offloadMaxBytesFor(spec) {
+  const configured = spec.metadata?.resultSizePolicy?.offloadMaxBytes;
+  return typeof configured === "number" && Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : RESULT_OFFLOAD_MAX_BYTES;
+}
+function toolResultDigestFor(spec, result, requestedDisposition, context) {
+  const text = resultText(result);
+  const disposition = normalizeToolResultDisposition(spec, maxBytesFor(spec, context), requestedDisposition);
+  if (disposition === null) {
+    const projected = shapeLegacyToolResult(spec, result, context);
+    return legacyToolResultDigest(resultText(projected), { outcome: result.kind });
+  }
+  const capturedBytes = capturedBytesFor(result, text);
+  return deterministicToolResultDigest({
+    text,
+    kind: result.kind,
+    details: result.details,
+    disposition,
+    capturedBytes,
+    displayedBytes: Math.min(capturedBytes, disposition.presentation.maxBytes),
+    offloadPath: existingOffloadPath(result.details),
+    followUpHint: followUpHint(spec)
+  });
+}
+function detailsRecord(details, key) {
+  const candidate = details?.[key];
+  return candidate !== null && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
+}
+function existingOffloadPath(details) {
+  const fromResultSize = detailsRecord(details, "resultSize")?.offloadPath;
+  if (typeof fromResultSize === "string" && fromResultSize.length > 0) return fromResultSize;
+  const fromObservation = detailsRecord(details, "observation")?.offloadPath;
+  return typeof fromObservation === "string" && fromObservation.length > 0 ? fromObservation : null;
+}
+function existingDisposition(details) {
+  const disposition = detailsRecord(details, "resultDisposition");
+  return disposition?.version === 1 && disposition.applications === 1 ? disposition : null;
+}
+function safePathSegment(value) {
+  const safe = value.trim().replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 128);
+  return safe.length > 0 ? safe : "unnamed";
+}
+function offloadBody(text, bytes, maxBytes) {
+  if (bytes <= maxBytes) return text;
+  const notice = `
+[clio-coder scratch output truncated at ${maxBytes} bytes; original size ${bytes} bytes]`;
+  const prefixBudget = maxBytes - byteLength(notice);
+  return `${truncateUtf8(text, Math.max(0, prefixBudget), "")}${notice}`;
+}
+function sweepExpiredToolOffloads(now = Date.now()) {
+  const root = join(clioStateDir(), "scratch");
+  const cutoff = now - TOOL_OFFLOAD_MAX_AGE_MS;
+  let removed = 0;
+  let skipped = 0;
+  try {
+    for (const session of readdirSync(root, { withFileTypes: true })) {
+      if (!session.isDirectory()) continue;
+      const sessionDir = join(root, session.name);
+      for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
+        if (!entry.isFile()) continue;
+        const path = join(sessionDir, entry.name);
+        try {
+          if (statSync(path).mtimeMs >= cutoff) continue;
+          rmSync(path, { force: true });
+          removed += 1;
+        } catch (error) {
+          if (error?.code !== "ENOENT") skipped += 1;
+        }
+      }
+      try {
+        if (readdirSync(sessionDir).length === 0) rmdirSync(sessionDir);
+      } catch (error) {
+        if (error?.code !== "ENOENT") skipped += 1;
+      }
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") skipped += 1;
+  }
+  return { removed, skipped };
+}
+function writeToolOffload(text, context, maxBytes = RESULT_OFFLOAD_MAX_BYTES, digest = createHash2("sha256").update(text).digest("hex")) {
+  try {
+    const bytes = byteLength(text);
+    const sessionId = safePathSegment(context?.sessionId ?? "no-session");
+    const dir = join(clioStateDir(), "scratch", sessionId);
+    const path = join(dir, `${digest}.txt`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, offloadBody(text, bytes, maxBytes), "utf8");
+    return path;
+  } catch {
+    return null;
+  }
+}
+var OFFLOAD_POINTER_NOTE = "overflow copy, read-only; not the workspace";
+function offloadPointer(offloadPath) {
+  return `full: ${offloadPath} (${OFFLOAD_POINTER_NOTE})`;
+}
+function isSessionOffloadPath(filePath, sessionId) {
+  const dir = join(clioStateDir(), "scratch", safePathSegment(sessionId ?? "no-session"));
+  const rel = relative(dir, resolve(filePath));
+  return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function bracketedHint(spec, offloadPath) {
+  const hint = followUpHint(spec);
+  if (offloadPath === null) return hint;
+  return `${hint} ${offloadPointer(offloadPath)}; read it with offset and limit to inspect the rest.`;
+}
+function shapeJsonOverflow(spec, result, text, bytes, maxBytes, context, offloadMaxBytes) {
+  const observation = detailsRecord(result.details, "observation");
+  const offloadPath = writeToolOffload(text, context, offloadMaxBytes);
+  const next = typeof observation?.next === "string" && observation.next.length > 0 ? observation.next : followUpHint(spec);
+  const stub = JSON.stringify({
+    error: `result exceeded ${maxBytes} bytes`,
+    ...offloadPath !== null ? { offloadPath, offloadPathNote: OFFLOAD_POINTER_NOTE } : {},
+    next
+  });
+  const resultSize = {
+    bytes,
+    shownBytes: byteLength(stub),
+    maxBytes,
+    truncated: true,
+    policy: spec.metadata?.resultSizePolicy?.kind ?? "truncate",
+    followUpHint: followUpHint(spec),
+    ...offloadPath !== null ? { offloadPath } : {}
+  };
+  if (result.kind === "ok") {
+    return { ...result, output: stub, details: mergeDetails(result.details, resultSize) };
+  }
+  return { ...result, message: stub, details: mergeDetails(result.details, resultSize) };
+}
+function shapeTailOverflow(spec, result, text, bytes, maxBytes, context, offloadMaxBytes) {
+  const truncation = truncateTail2(text, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: Math.max(1, maxBytes - TAIL_NOTICE_RESERVE_BYTES)
+  });
+  const offloadPath = writeToolOffload(text, context, offloadMaxBytes);
+  const startLine = truncation.totalLines - truncation.outputLines + 1;
+  const scope = truncation.lastLinePartial ? `last ${formatSize(truncation.outputBytes)} of line ${truncation.totalLines} (line is large)` : `lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines}`;
+  const location = offloadPath === null ? "" : ` Full output saved to ${offloadPath}; ${OFFLOAD_POINTER_NOTE}; read it with offset/limit.`;
+  const note = `[Output tail-truncated: showing ${scope} (${formatSize(maxBytes)} display limit).${location}]`;
+  const resultSize = {
+    bytes,
+    shownBytes: truncation.outputBytes,
+    maxBytes,
+    truncated: true,
+    policy: "tail",
+    followUpHint: followUpHint(spec),
+    ...offloadPath === null ? {} : { offloadPath }
+  };
+  const displayed = `${truncation.content}
+
+${note}`;
+  if (result.kind === "ok") return { ...result, output: displayed, details: mergeDetails(result.details, resultSize) };
+  return { ...result, message: displayed, details: mergeDetails(result.details, resultSize) };
+}
+function shapeLegacyToolResult(spec, result, context, overflow = "head") {
+  if (existingOffloadPath(result.details) !== null) return result;
+  const maxBytes = maxBytesFor(spec, context);
+  const offloadMaxBytes = offloadMaxBytesFor(spec);
+  const text = result.kind === "ok" ? result.output : result.message;
+  const bytes = byteLength(text);
+  if (bytes <= maxBytes) return result;
+  const observation = detailsRecord(result.details, "observation");
+  if (observation?.format === "json") {
+    return shapeJsonOverflow(spec, result, text, bytes, maxBytes, context, offloadMaxBytes);
+  }
+  if (overflow === "tail") {
+    return shapeTailOverflow(spec, result, text, bytes, maxBytes, context, offloadMaxBytes);
+  }
+  const truncated = truncateUtf8(text, maxBytes, RESULT_TRUNCATION_MARKER);
+  const offloadPath = writeToolOffload(text, context, offloadMaxBytes);
+  const resultSize = {
+    bytes,
+    shownBytes: byteLength(truncated),
+    maxBytes,
+    truncated: true,
+    policy: spec.metadata?.resultSizePolicy?.kind ?? "truncate",
+    followUpHint: followUpHint(spec),
+    ...offloadPath !== null ? { offloadPath } : {}
+  };
+  if (result.kind === "ok") {
+    return {
+      ...result,
+      output: `${truncated}
+
+[${bracketedHint(spec, offloadPath)}]`,
+      details: mergeDetails(result.details, resultSize)
+    };
+  }
+  return {
+    ...result,
+    message: `${truncated}
+
+[${bracketedHint(spec, offloadPath)}]`,
+    details: mergeDetails(result.details, resultSize)
+  };
+}
+function specWithDisplayCap(spec, maxBytes) {
+  const metadata = spec.metadata;
+  if (metadata === void 0) return spec;
+  return {
+    ...spec,
+    metadata: {
+      ...metadata,
+      resultSizePolicy: { ...metadata.resultSizePolicy, maxBytes }
+    }
+  };
+}
+function resultText(result) {
+  return result.kind === "ok" ? result.output : result.message;
+}
+function withFallbackNotice(result, fallback) {
+  const note = `
+
+[result disposition fell back to metadata-only: ${fallback.reason} (${fallback.message}); the model received facts and retrieval only]`;
+  return result.kind === "ok" ? { ...result, output: `${result.output}${note}` } : { ...result, message: `${result.message}${note}` };
+}
+function numberField(record, key) {
+  const value = record?.[key];
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function capturedBytesFor(result, text) {
+  const declared = numberField(detailsRecord(result.details, "resultSize"), "bytes");
+  return Math.max(byteLength(text), declared ?? 0);
+}
+function resultWasTruncated(result) {
+  return detailsRecord(result.details, "resultSize")?.truncated === true;
+}
+function withOffloadMetadata(result, offloadPath, capturedBytes, displayedBytes, maxBytes, hint) {
+  const current = detailsRecord(result.details, "resultSize") ?? {};
+  const resultSize = {
+    bytes: numberField(current, "bytes") ?? capturedBytes,
+    shownBytes: numberField(current, "shownBytes") ?? displayedBytes,
+    maxBytes: numberField(current, "maxBytes") ?? maxBytes,
+    truncated: current.truncated === true,
+    policy: typeof current.policy === "string" ? current.policy : "disposition",
+    followUpHint: typeof current.followUpHint === "string" ? current.followUpHint : hint,
+    ...current,
+    offloadPath
+  };
+  return { ...result, details: mergeDetails(result.details, resultSize) };
+}
+function shapeTextToolResultBody(spec, result, context, requestedDisposition) {
+  if (existingDisposition(result.details) !== null) return result;
+  const hardMaxBytes = maxBytesFor(spec, context);
+  const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+  if (disposition === null) return shapeLegacyToolResult(spec, result, context);
+  const capturedText = resultText(result);
+  const capturedBytes = capturedBytesFor(result, capturedText);
+  let displayed = shapeLegacyToolResult(
+    specWithDisplayCap(spec, disposition.presentation.maxBytes),
+    result,
+    context,
+    disposition.presentation.overflow
+  );
+  if (disposition.fallback !== void 0) displayed = withFallbackNotice(displayed, disposition.fallback);
+  let displayedText = resultText(displayed);
+  let displayedBytes = byteLength(displayedText);
+  let offloadPath = existingOffloadPath(displayed.details);
+  const projectionInput = {
+    text: capturedText,
+    kind: result.kind,
+    details: displayed.details,
+    disposition,
+    capturedBytes,
+    displayedBytes,
+    offloadPath,
+    followUpHint: followUpHint(spec)
+  };
+  let projection = projectToolResultContext(projectionInput);
+  if (offloadPath === null && projection.truncated) {
+    offloadPath = writeToolOffload(
+      capturedText,
+      context,
+      offloadMaxBytesFor(spec),
+      projection.summaryProvenance?.sourceSha256
+    );
+    if (offloadPath !== null) {
+      displayed = withOffloadMetadata(
+        displayed,
+        offloadPath,
+        capturedBytes,
+        displayedBytes,
+        disposition.presentation.maxBytes,
+        followUpHint(spec)
+      );
+      displayedText = resultText(displayed);
+      displayedBytes = byteLength(displayedText);
+      projection = projectToolResultContext({
+        ...projectionInput,
+        details: displayed.details,
+        displayedBytes,
+        offloadPath
+      });
+    }
+  }
+  const metadata = {
+    version: 1,
+    applications: 1,
+    presentation: { ...disposition.presentation, content: displayedText },
+    context: {
+      requestedMode: disposition.context.mode,
+      appliedMode: projection.appliedMode,
+      maxBytes: disposition.context.maxBytes,
+      ...disposition.context.mode === "bounded" && disposition.context.excerpt !== void 0 ? { excerpt: disposition.context.excerpt } : {},
+      ...disposition.context.mode === "full" && disposition.context.downgradeExcerpt !== void 0 ? { excerpt: disposition.context.downgradeExcerpt } : {},
+      ...disposition.context.mode === "summary" && disposition.context.strategy !== void 0 ? { summaryStrategy: disposition.context.strategy } : {}
+    },
+    capturedBytes,
+    displayedBytes,
+    contextBytes: byteLength(projection.text),
+    presentationTruncated: resultWasTruncated(displayed),
+    contextTruncated: projection.truncated,
+    ...projection.downgrade === void 0 ? {} : { downgrade: projection.downgrade },
+    ...offloadPath === null ? {} : { offloadPath },
+    retrieval: offloadPath === null ? followUpHint(spec) : `read ${offloadPath} with offset and limit to retrieve omitted content`,
+    ...projection.summaryProvenance === void 0 ? {} : { summaryProvenance: projection.summaryProvenance },
+    ...disposition.fallback === void 0 ? {} : { fallback: disposition.fallback }
+  };
+  return {
+    ...displayed,
+    details: { ...displayed.details ?? {}, resultDisposition: metadata },
+    modelContext: projection.text
+  };
+}
+function shapeTextToolResult(spec, result, context, requestedDisposition) {
+  const shaped = shapeTextToolResultBody(spec, result, context, requestedDisposition);
+  const warning = `[middleware:warn] ${INSTRUCTION_SHAPED_WARNING}`;
+  if (!resultText(result).includes(warning)) return shaped;
+  const hardMaxBytes = maxBytesFor(spec, context);
+  const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+  const preserve = (text, cap, tail) => {
+    if (text.startsWith(warning) && byteLength(text) <= cap) return text;
+    const prefix = `${warning}
+
+`;
+    const remainder = text.split(warning).join("").trimStart();
+    const allowance = Math.max(0, cap - byteLength(prefix));
+    if (allowance === 0) return truncateUtf8(warning, cap, "");
+    const body = tail ? truncateTail2(remainder, { maxBytes: allowance, maxLines: Number.MAX_SAFE_INTEGER }).content : truncateUtf8(remainder, allowance, "");
+    return prefix + body;
+  };
+  const output = preserve(
+    resultText(shaped),
+    Math.min(hardMaxBytes, disposition?.presentation.maxBytes ?? hardMaxBytes),
+    disposition?.presentation.overflow === "tail"
+  );
+  const modelContext = shaped.modelContext === void 0 ? void 0 : preserve(
+    shaped.modelContext,
+    Math.min(hardMaxBytes, disposition?.context.maxBytes ?? hardMaxBytes),
+    disposition?.context.mode === "bounded" && disposition.context.excerpt === "tail"
+  );
+  const previous = existingDisposition(shaped.details);
+  const details = { ...shaped.details };
+  if (previous !== null)
+    details.resultDisposition = {
+      ...previous,
+      presentation: { ...previous.presentation, content: output },
+      displayedBytes: byteLength(output),
+      contextBytes: byteLength(modelContext ?? output),
+      presentationTruncated: previous.presentationTruncated || byteLength(resultText(shaped)) > byteLength(output),
+      contextTruncated: previous.contextTruncated || byteLength(shaped.modelContext ?? "") > byteLength(modelContext ?? "")
+    };
+  const size = detailsRecord(shaped.details, "resultSize");
+  if (size !== null) details.resultSize = { ...size, shownBytes: byteLength(output) };
+  return {
+    ...shaped,
+    ...shaped.kind === "ok" ? { output } : { message: output },
+    ...modelContext === void 0 ? {} : { modelContext },
+    details
+  };
+}
+function shapeToolResult(spec, result, context, requestedDisposition) {
+  if (result.kind !== "ok" || !result.images?.length)
+    return shapeTextToolResult(spec, result, context, requestedDisposition);
+  const hardMaxBytes = maxBytesFor(spec, context);
+  const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+  const maxBytes = Math.min(hardMaxBytes, disposition?.context.maxBytes ?? hardMaxBytes);
+  const images = [];
+  let imageBytes = 0;
+  for (const image of result.images) {
+    const bytes = byteLength(image.data);
+    if (context?.supportsImages === true && disposition?.context.mode !== "metadata-only" && bytes + imageBytes < maxBytes - 512) {
+      images.push(image);
+      imageBytes += bytes;
+    }
+  }
+  const omitted = result.images.length - images.length;
+  const notice = omitted > 0 ? `[${omitted} image(s) omitted: model capability, context policy, or tool result byte cap.]
+` : "";
+  const remaining = Math.max(1, maxBytes - imageBytes);
+  const shaped = shapeTextToolResult(
+    spec,
+    { ...result, output: notice + result.output, images },
+    { ...context, toolResultMaxBytes: remaining },
+    requestedDisposition
+  );
+  if (shaped.kind !== "ok") return shaped;
+  return {
+    ...shaped,
+    images,
+    output: truncateUtf8(shaped.output, remaining, ""),
+    ...shaped.modelContext === void 0 ? {} : { modelContext: truncateUtf8(shaped.modelContext, remaining, "") }
+  };
+}
+
+// src/tools/observation.ts
+init_esm_shims();
+var OBSERVATION_POLICY_SLACK_BYTES = 2 * 1024;
+var OBSERVE_SELF_CAPS = {
+  grepContent: 16 * 1024,
+  grepFilesCount: 8 * 1024,
+  find: 8 * 1024,
+  ls: 8 * 1024,
+  codeNav: 16 * 1024,
+  contextDocs: 16 * 1024,
+  contextSkills: 50 * 1024,
+  contextWorkspace: 50 * 1024,
+  // Library rows are metadata: name, owner, origin, availability, invocation.
+  // A full page of 50 stays well inside this, and a smaller cap than the
+  // skills catalog is what keeps a catalog read from crowding out the turn.
+  contextLibrary: 16 * 1024
+};
+var DEFAULT_OBSERVATION_TURN_BUDGET_BYTES = GUARDRAIL_DEFAULTS.observationTurnBudgetBytes;
+var MIN_BUDGET_SLICE_BYTES = 1024;
+var BUDGET_TRACK_LIMIT = 256;
+var MAX_EXHAUSTED_NOTICES_PER_TURN = 3;
+var turnBudgets = /* @__PURE__ */ new Map();
+var MAX_CONTINUATION_CHARS = 200;
+function boundContinuation(next) {
+  if (next === void 0 || next.length <= MAX_CONTINUATION_CHARS) return next;
+  return `${Array.from(next).slice(0, MAX_CONTINUATION_CHARS).join("")}\u2026`;
+}
+function observationTurnBudgetLimit() {
+  return Math.max(MIN_BUDGET_SLICE_BYTES, resolveGuardrail("observationTurnBudgetBytes"));
+}
+function budgetKey(options) {
+  const turnId = options?.turnId?.trim();
+  if (!turnId) return null;
+  const sessionId = options?.sessionId?.trim() || "no-session";
+  return `${sessionId}:${turnId}`;
+}
+function pruneBudgetMap() {
+  while (turnBudgets.size > BUDGET_TRACK_LIMIT) {
+    let oldestKey = null;
+    let oldestSeen = Number.POSITIVE_INFINITY;
+    for (const [key, state] of turnBudgets) {
+      if (state.lastSeenAt >= oldestSeen) continue;
+      oldestKey = key;
+      oldestSeen = state.lastSeenAt;
+    }
+    if (oldestKey === null) break;
+    turnBudgets.delete(oldestKey);
+  }
+}
+function reserveObservation(selfCapBytes, options) {
+  const key = budgetKey(options);
+  if (key === null) {
+    return {
+      key,
+      limitBytes: observationTurnBudgetLimit(),
+      usedBeforeBytes: 0,
+      selfCapBytes,
+      callCapBytes: selfCapBytes,
+      limited: false,
+      exhausted: false,
+      committed: false,
+      settled: false
+    };
+  }
+  const limitBytes = observationTurnBudgetLimit();
+  const state = turnBudgets.get(key) ?? { usedBytes: 0, lastSeenAt: Date.now(), exhaustedStreak: 0 };
+  state.lastSeenAt = Date.now();
+  turnBudgets.set(key, state);
+  pruneBudgetMap();
+  const remaining = Math.max(0, limitBytes - state.usedBytes);
+  if (remaining < MIN_BUDGET_SLICE_BYTES) {
+    return {
+      key,
+      limitBytes,
+      usedBeforeBytes: state.usedBytes,
+      selfCapBytes,
+      callCapBytes: 0,
+      limited: true,
+      exhausted: true,
+      committed: false,
+      settled: false
+    };
+  }
+  state.exhaustedStreak = 0;
+  const callCapBytes = Math.min(selfCapBytes, remaining);
+  return {
+    key,
+    limitBytes,
+    usedBeforeBytes: state.usedBytes,
+    selfCapBytes,
+    callCapBytes,
+    limited: callCapBytes < selfCapBytes,
+    exhausted: false,
+    committed: false,
+    settled: false
+  };
+}
+function commitObservationReservation(reservation) {
+  if (reservation.key === null || reservation.committed || reservation.settled) return;
+  if (reservation.callCapBytes <= 0) return;
+  reservation.committed = true;
+  const state = turnBudgets.get(reservation.key) ?? {
+    usedBytes: reservation.usedBeforeBytes,
+    lastSeenAt: Date.now(),
+    exhaustedStreak: 0
+  };
+  state.usedBytes += reservation.callCapBytes;
+  state.lastSeenAt = Date.now();
+  turnBudgets.set(reservation.key, state);
+}
+function releaseObservation(reservation) {
+  if (reservation.key === null || reservation.settled) return;
+  reservation.settled = true;
+  if (!reservation.committed) return;
+  const state = turnBudgets.get(reservation.key);
+  if (state === void 0) return;
+  state.usedBytes = Math.max(0, state.usedBytes - reservation.callCapBytes);
+  state.lastSeenAt = Date.now();
+  turnBudgets.set(reservation.key, state);
+}
+function recordSpentBytes(reservation, bytes) {
+  if (reservation.key === null || reservation.settled) return;
+  reservation.settled = true;
+  const committedBytes = reservation.committed ? reservation.callCapBytes : 0;
+  const state = turnBudgets.get(reservation.key) ?? {
+    usedBytes: reservation.usedBeforeBytes + committedBytes,
+    lastSeenAt: Date.now(),
+    exhaustedStreak: 0
+  };
+  state.usedBytes = Math.max(0, state.usedBytes + bytes - committedBytes);
+  state.lastSeenAt = Date.now();
+  turnBudgets.set(reservation.key, state);
+}
+function budgetDetails(reservation) {
+  if (reservation.key === null) return null;
+  return {
+    limitBytes: reservation.limitBytes,
+    usedBeforeBytes: reservation.usedBeforeBytes,
+    exhausted: reservation.exhausted
+  };
+}
+function bumpExhaustedStreak(key) {
+  if (key === null) return 1;
+  const state = turnBudgets.get(key);
+  if (state === void 0) return 1;
+  state.exhaustedStreak += 1;
+  state.lastSeenAt = Date.now();
+  turnBudgets.set(key, state);
+  return state.exhaustedStreak;
+}
+function observationBudgetExhausted(input) {
+  const { tool, unit, reservation, subject, hint } = input;
+  const streak = bumpExhaustedStreak(reservation.key);
+  const spent = `${formatSize(reservation.usedBeforeBytes)} already returned of ${formatSize(reservation.limitBytes)}`;
+  if (streak > MAX_EXHAUSTED_NOTICES_PER_TURN) {
+    const message = `observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. This is the ${streak}th call to hit it, so no observation tool can return content until the next turn. Do not retry this call and do not substitute another one. Re-plan with what you already have: say what you found, name what is still unread, and propose the next step.`;
+    recordSpentBytes(reservation, byteLength(message));
+    return { kind: "error", message };
+  }
+  const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}]`;
+  const shownBytes = byteLength(output);
+  recordSpentBytes(reservation, shownBytes);
+  const budget = budgetDetails(reservation);
+  const observation = {
+    tool,
+    unit,
+    shownCount: 0,
+    totalCount: null,
+    shownBytes,
+    // The notice message is the whole rendering here (the search never ran), so
+    // the full size is the message itself; keep totalBytes >= shownBytes.
+    totalBytes: shownBytes,
+    truncated: true,
+    format: "text",
+    ...budget !== null ? { budget } : {}
+  };
+  return { kind: "ok", output, details: { observation } };
+}
+function noticeLine(input, bodyBytes, totalBytes, offloadPath, next) {
+  const totalSegment = input.totalCount === null ? `${input.shownCount}+` : String(input.totalCount);
+  const parts = [
+    `${input.tool}: ${input.shownCount}/${totalSegment} ${input.unit} shown (${formatSize(bodyBytes)} of ${formatSize(totalBytes)})`
+  ];
+  if (offloadPath !== null) parts.push(offloadPointer(offloadPath));
+  if (next !== void 0 && next.length > 0) parts.push(`next: ${next}`);
+  return `[${parts.join(" | ")}]`;
+}
+function limitedBudgetNote(reservation) {
+  return `[Per-turn observation budget: ${formatSize(reservation.usedBeforeBytes)} already returned of ${formatSize(
+    reservation.limitBytes
+  )} before this call. Use narrower arguments or continue in a follow-up turn for more content.]`;
+}
+function jsonStubBudgetNote(reservation) {
+  return `per-turn observation budget nearly exhausted: ${formatSize(reservation.usedBeforeBytes)} of ${formatSize(reservation.limitBytes)} already returned this turn. Do not retry this call; answer from what you have gathered, or continue in a follow-up turn.`;
+}
+function finalizeObservation(input) {
+  const format = input.format ?? "text";
+  let output = input.output;
+  let truncated = input.truncated;
+  let shownCount = input.shownCount;
+  let offloadPath = null;
+  const bodyBytes = byteLength(output);
+  const totalBytes = input.totalBytes ?? byteLength(input.fullOutput ?? input.output);
+  const next = boundContinuation(input.next);
+  if (format === "json" && bodyBytes > input.reservation.callCapBytes) {
+    truncated = true;
+    shownCount = 0;
+    offloadPath = writeToolOffload(input.fullOutput ?? output, input.options);
+    const poolBound = input.reservation.limited;
+    output = JSON.stringify({
+      error: `result exceeded ${formatSize(input.reservation.callCapBytes)}`,
+      ...poolBound ? { budget: jsonStubBudgetNote(input.reservation) } : {},
+      ...offloadPath !== null ? { offloadPath } : {},
+      ...!poolBound && next !== void 0 && next.length > 0 ? { next } : {}
+    });
+  } else if (truncated && input.fullOutput !== void 0) {
+    offloadPath = writeToolOffload(input.fullOutput, input.options);
+  }
+  if (format === "text") {
+    if (truncated && input.omitNotice !== true)
+      output += `
+
+${noticeLine(input, bodyBytes, totalBytes, offloadPath, next)}`;
+    if (input.reservation.limited && !input.reservation.exhausted) {
+      output += `
+
+${limitedBudgetNote(input.reservation)}`;
+    }
+  }
+  if ((input.withheldPaths ?? 0) > 0 && format === "text")
+    output += `
+
+[${input.withheldPaths} protected paths withheld by zero-access policy]`;
+  const shownBytes = byteLength(output) + (input.images ?? []).reduce((bytes, image) => bytes + byteLength(image.data), 0);
+  recordSpentBytes(input.reservation, shownBytes);
+  const budget = budgetDetails(input.reservation);
+  const observation = {
+    tool: input.tool,
+    unit: input.unit,
+    shownCount,
+    totalCount: input.totalCount,
+    shownBytes,
+    // shownBytes counts the appended notice/limited-budget lines; totalBytes
+    // measured only the pre-notice rendering (and equals it when a count-limited
+    // tool like ls offloads nothing). Floor the full-rendering size at the bytes
+    // actually returned so the envelope invariant totalBytes >= shownBytes holds.
+    totalBytes: Math.max(totalBytes, shownBytes),
+    truncated,
+    format,
+    ...next !== void 0 && next.length > 0 ? { next } : {},
+    ...offloadPath !== null ? { offloadPath } : {},
+    ...budget !== null ? { budget } : {}
+  };
+  return {
+    kind: "ok",
+    output,
+    ...input.images?.length ? { images: input.images } : {},
+    details: { ...input.details ?? {}, observation }
+  };
+}
+function createObservationPathFilter(cwd = process.cwd(), allowsPath) {
+  const policy = allowsPath ? void 0 : createSafetyPolicyEngine({ cwd });
+  const allows = allowsPath ?? ((path) => policy?.evaluate({ tool: "read", args: { path } }).reasonCode !== "path-policy:zeroAccessPaths");
+  const withheld = /* @__PURE__ */ new Set();
+  return {
+    allows(path) {
+      if (allows(path)) return true;
+      withheld.add(path);
+      return false;
+    },
+    get withheldPaths() {
+      return withheld.size;
+    }
+  };
+}
+
+export {
+  deterministicDiagnosticSummary,
+  legacyToolResultDigest,
+  sanitizeToolResultDigest,
+  toolResultContextText,
+  isDispositionedToolResultError,
+  toolResultPresentationText,
+  toolResultPresentationPolicy,
+  DEFAULT_MAX_LINES,
+  splitLinesForCounting,
+  truncateHead2 as truncateHead,
+  truncateTail2 as truncateTail,
+  DEFAULT_TOOL_RESULT_MAX_BYTES,
+  toolResultDigestFor,
+  sweepExpiredToolOffloads,
+  isSessionOffloadPath,
+  shapeToolResult,
+  OBSERVATION_POLICY_SLACK_BYTES,
+  OBSERVE_SELF_CAPS,
+  reserveObservation,
+  commitObservationReservation,
+  releaseObservation,
+  observationBudgetExhausted,
+  finalizeObservation,
+  createObservationPathFilter
+};
+//# sourceMappingURL=chunk-526ABLHD.js.map