@iowarp/clio-coder 0.3.1 → 0.3.2

package/dist/chunk-VAKQQHWR.js

@@ -0,0 +1,434 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  byteLength,
+  truncateUtf8
+} from "./chunk-6XLNIQDB.js";
+import {
+  GUARDRAIL_DEFAULTS,
+  GUARDRAIL_ENV_VARS,
+  resolveGuardrail
+} from "./chunk-4ZG3XFUR.js";
+import {
+  clioStateDir
+} from "./chunk-BNAZZHFG.js";
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
+
+// src/tools/truncate.ts
+init_esm_shims();
+
+// src/engine/truncate.ts
+init_esm_shims();
+import {
+  formatSize,
+  GREP_MAX_LINE_LENGTH,
+  truncateHead,
+  truncateLine,
+  truncateTail
+} from "@earendil-works/pi-agent-core";
+
+// src/tools/truncate.ts
+var DEFAULT_MAX_LINES = 2e3;
+var DEFAULT_MAX_BYTES = 16 * 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/observation.ts
+init_esm_shims();
+
+// src/tools/result-shaping.ts
+init_esm_shims();
+import { mkdirSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+var DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES + 2 * 1024;
+var RESULT_TRUNCATION_MARKER = "\n[tool result truncated]";
+var RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
+function mergeDetails(details, resultSize) {
+  return { ...details ?? {}, resultSize };
+}
+function maxBytesFor(spec) {
+  const configured = spec.metadata?.resultSizePolicy?.maxBytes;
+  return typeof configured === "number" && Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : DEFAULT_TOOL_RESULT_MAX_BYTES;
+}
+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 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 safePathSegment(value) {
+  const safe = value.trim().replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 128);
+  return safe.length > 0 ? safe : "unnamed";
+}
+function timestampSegment() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[^A-Za-z0-9._-]/g, "_");
+}
+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 writeToolOffload(text, context, maxBytes = RESULT_OFFLOAD_MAX_BYTES) {
+  try {
+    const bytes = byteLength(text);
+    const sessionId = safePathSegment(context?.sessionId ?? "no-session");
+    const callId = safePathSegment(context?.toolCallId ?? timestampSegment());
+    const dir = join(clioStateDir(), "scratch", sessionId);
+    const path = join(dir, `${callId}.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) {
+  const observation = detailsRecord(result.details, "observation");
+  const offloadPath = writeToolOffload(text, context);
+  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 shapeToolResult(spec, result, context) {
+  if (existingOffloadPath(result.details) !== null) return result;
+  const maxBytes = maxBytesFor(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);
+  const truncated = truncateUtf8(text, maxBytes, RESULT_TRUNCATION_MARKER);
+  const offloadPath = writeToolOffload(text, context);
+  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)
+  };
+}
+
+// src/tools/observation.ts
+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
+};
+var DEFAULT_OBSERVATION_TURN_BUDGET_BYTES = GUARDRAIL_DEFAULTS.observationTurnBudgetBytes;
+var OBSERVATION_TURN_BUDGET_ENV = GUARDRAIL_ENV_VARS.observationTurnBudgetBytes;
+var MIN_BUDGET_SLICE_BYTES = 1024;
+var BUDGET_TRACK_LIMIT = 256;
+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(env = process.env) {
+  return Math.max(MIN_BUDGET_SLICE_BYTES, resolveGuardrail("observationTurnBudgetBytes", env));
+}
+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() };
+  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
+    };
+  }
+  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()
+  };
+  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()
+  };
+  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 observationBudgetExhausted(input) {
+  const { tool, unit, reservation, subject, hint } = input;
+  const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${formatSize(
+    reservation.usedBeforeBytes
+  )} already returned of ${formatSize(reservation.limitBytes)}. ${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)}`;
+    }
+  }
+  const shownBytes = byteLength(output);
+  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, details: { ...input.details ?? {}, observation } };
+}
+
+export {
+  formatSize,
+  GREP_MAX_LINE_LENGTH,
+  truncateLine,
+  DEFAULT_MAX_LINES,
+  splitLinesForCounting,
+  truncateHead2 as truncateHead,
+  truncateTail2 as truncateTail,
+  writeToolOffload,
+  isSessionOffloadPath,
+  shapeToolResult,
+  OBSERVATION_POLICY_SLACK_BYTES,
+  OBSERVE_SELF_CAPS,
+  reserveObservation,
+  commitObservationReservation,
+  releaseObservation,
+  observationBudgetExhausted,
+  finalizeObservation
+};
+//# sourceMappingURL=chunk-VAKQQHWR.js.map

package/dist/chunk-VG7TBQIY.js

@@ -0,0 +1,128 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  toPosixPath
+} from "./chunk-OQE5J4C6.js";
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
+
+// src/tools/ignore-policy.ts
+init_esm_shims();
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+var ALWAYS_EXCLUDED_DIRS = [".clio-coder", ".fallow", ".git"];
+var GENERATED_DIRS = [
+  ".cache",
+  ".next",
+  ".pytest_cache",
+  ".turbo",
+  ".venv",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "target"
+];
+function isInsideGitRepo(startPath) {
+  let current = startPath;
+  for (; ; ) {
+    if (existsSync(join(current, ".git"))) return true;
+    const parent = dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+function excludedDirsFor(searchPath, includeIgnored) {
+  const segments = new Set(
+    toPosixPath(searchPath).split("/").filter((segment) => segment.length > 0)
+  );
+  const dirs = includeIgnored ? ALWAYS_EXCLUDED_DIRS : [...ALWAYS_EXCLUDED_DIRS, ...GENERATED_DIRS];
+  return dirs.filter((dir) => !segments.has(dir));
+}
+function rgIgnoreArgs(searchPath, includeIgnored) {
+  const args = ["--hidden"];
+  if (includeIgnored) args.push("--no-ignore");
+  else if (!isInsideGitRepo(searchPath)) args.push("--no-require-git");
+  for (const dir of excludedDirsFor(searchPath, includeIgnored)) args.push("--glob", `!**/${dir}/**`);
+  return args;
+}
+function fdIgnoreArgs(searchPath, includeIgnored) {
+  const args = ["--hidden"];
+  if (includeIgnored) args.push("--no-ignore");
+  else if (!isInsideGitRepo(searchPath)) args.push("--no-require-git");
+  for (const dir of excludedDirsFor(searchPath, includeIgnored)) args.push("--exclude", dir);
+  return args;
+}
+function fallbackIgnoredDirs(includeIgnored) {
+  return new Set(includeIgnored ? ALWAYS_EXCLUDED_DIRS : [...ALWAYS_EXCLUDED_DIRS, ...GENERATED_DIRS]);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function escapeRegexChar(ch) {
+  return /[\\^$+?.()|{}]/.test(ch) ? `\\${ch}` : ch;
+}
+function escapeClassChar(ch) {
+  return /[\\\]^-]/.test(ch) ? `\\${ch}` : ch;
+}
+function normalizeGlobInput(input) {
+  return input.replace(/\\/g, "/");
+}
+function compileGlobRegex(pattern) {
+  const normalized = normalizeGlobInput(pattern);
+  if (normalized.length === 0) {
+    throw new Error("glob: pattern must not be empty");
+  }
+  let regex = "^";
+  for (let i = 0; i < normalized.length; ) {
+    const ch = normalized[i];
+    if (ch === void 0) break;
+    if (ch === "*") {
+      if (normalized[i + 1] === "*") {
+        if (normalized[i + 2] === "/") {
+          regex += "(?:.*\\/)?";
+          i += 3;
+          continue;
+        }
+        regex += ".*";
+        i += 2;
+        continue;
+      }
+      regex += "[^/]*";
+      i += 1;
+      continue;
+    }
+    if (ch === "?") {
+      regex += "[^/]";
+      i += 1;
+      continue;
+    }
+    if (ch === "[") {
+      const end = normalized.indexOf("]", i + 1);
+      if (end === -1) {
+        throw new Error(`glob: invalid pattern (unclosed character class): ${pattern}`);
+      }
+      const content = normalized.slice(i + 1, end);
+      if (content.length === 0) {
+        throw new Error(`glob: invalid pattern (empty character class): ${pattern}`);
+      }
+      regex += `[${Array.from(content).map(escapeClassChar).join("")}]`;
+      i = end + 1;
+      continue;
+    }
+    regex += escapeRegexChar(ch);
+    i += 1;
+  }
+  regex += "$";
+  return new RegExp(regex);
+}
+
+export {
+  rgIgnoreArgs,
+  fdIgnoreArgs,
+  fallbackIgnoredDirs,
+  escapeRegExp,
+  normalizeGlobInput,
+  compileGlobRegex
+};
+//# sourceMappingURL=chunk-VG7TBQIY.js.map