@inhuman.tools/turn 0.0.0-stage → 0.1.0

package/src/context/index.ts

@@ -0,0 +1,35 @@
+export {
+  contentTokensOf,
+  type EatCell,
+  historyBehind,
+  MessageChunk,
+  payloadSuffix,
+  projectCompactRows,
+  sliceCompactEat,
+  sliceCompactZones,
+  textOfCell,
+  Transcript,
+} from "./transcript.js";
+export { keepFloors, keepFloorsOfJob, kvKeepTurnsOf, stampCompactInputs } from "./compact-floors.js";
+export { compactDecision, compactDue, compactRejectReason, needFeasible, tailCompactCandidate } from "./compact.js";
+export {
+  SQUEEZE_COMPACT_CHARS,
+  SQUEEZE_MICRO_MIN_CHARS,
+  liftToolImages,
+  squeezeProgrammaticText,
+  squeezeToolCall,
+  toolImagesOf,
+  toolCallRepresentation,
+} from "./squeeze.js";
+export * from "./retention/index.js";
+export { usesGenericSilentProjection } from "./delivery.js";
+export { selectCompletionTools } from "./tools.js";
+export { BACKGROUND_TOOL, IN_FLIGHT_TOOL, NO_TOOLS_SYSTEM } from "./observations.js";
+export {
+  approvalNoteMessagesOf,
+  type HistoryMessage,
+  type HistoryUserPart,
+  notificationMessagesOf,
+  projectHistory,
+  steerMessagesOf,
+} from "./history.js";

package/src/context/observations.ts

@@ -0,0 +1,13 @@
+/**
+ * Model-facing copy for completion input. Vendor HTTP errors are not here.
+ */
+import { prompt } from "@inhuman.tools/harness-commons";
+
+/** No-tools face: unhomed completion, empty catalog, or Approvable parent (judge). */
+export const NO_TOOLS_SYSTEM = prompt.system`Reply in prose. You do not have tools.`;
+
+/** Unresolved foreground tool row. */
+export const IN_FLIGHT_TOOL = "in-flight";
+
+/** Unresolved background tool row. */
+export const BACKGROUND_TOOL = "running in background";

package/src/context/retention/defaults.ts

@@ -0,0 +1,58 @@
+/**
+ * Dist defaults for `contextRetention` (design §4.3). A turn minted before
+ * retention existed resolves to {@link LEGACY_CONTEXT_RETENTION}: everything
+ * lives until compaction, except what the owner fixed regardless of config —
+ * pictures live only through their own turn, a system note only for its round.
+ */
+import type { ContextRetention } from "./schema.js";
+
+export const DEFAULT_CONTEXT_RETENTION: ContextRetention = {
+  version: 1,
+  defaults: { minChars: 800 },
+  step: { turnBoundary: true, everyRounds: 4, minFreedTokens: 8000, whenCacheCold: true, atCompaction: true },
+  kinds: {
+    "image.user": { keep: ["turn", { newest: 4 }], leave: "stub", minChars: 0 },
+    "image.tool": { keep: ["turn", { newest: 2 }], leave: "stub", minChars: 0 },
+    "tool.read": { keep: ["turn", { rounds: 10 }], leave: "stub" },
+    "tool.search": { keep: { rounds: 2 }, leave: "stub" },
+    "tool.shell": { keep: { rounds: 3 }, leave: "summary" },
+    "tool.web.search": { keep: { rounds: 2 }, leave: "stub" },
+    "tool.web.fetch": { keep: "turn", leave: "stub" },
+    "tool.mcp": { keep: "turn", leave: "stub" },
+    "tool.program": { keep: "turn", leave: { head: 400 } },
+    "tool.agent": { keep: "compaction" },
+    "tool.comm": { keep: "round", leave: "stub", minChars: 200 },
+    "tool.write": { keep: "compaction" },
+    "tool.other": { keep: "compaction" },
+    "tool.args.write": { keep: "turn", leave: "stub", minChars: 2000 },
+    thinking: { keep: "turn", leave: "none", minChars: 0 },
+    steer: { keep: "compaction" },
+    "approval-note": { keep: "compaction" },
+    notification: { keep: "turn", leave: "summary" },
+    "system-note": { keep: "round", leave: "none", minChars: 0 },
+    error: { keep: "turn", leave: "summary", minChars: 0 },
+  },
+  tools: {},
+  dialects: { anthropic: { keep: "forever" } },
+};
+
+const LEGACY_KINDS: ContextRetention["kinds"] = Object.fromEntries(
+  Object.keys(DEFAULT_CONTEXT_RETENTION.kinds).map((kind) => [
+    kind,
+    { keep: "compaction", leave: "stub", minChars: 0 },
+  ]),
+);
+
+export const LEGACY_CONTEXT_RETENTION: ContextRetention = {
+  version: 1,
+  defaults: { minChars: 0 },
+  step: { turnBoundary: true, everyRounds: null, minFreedTokens: 0, whenCacheCold: false, atCompaction: true },
+  kinds: {
+    ...LEGACY_KINDS,
+    "image.user": { keep: ["turn", { newest: 4 }], leave: "stub", minChars: 0 },
+    "image.tool": { keep: ["turn", { newest: 2 }], leave: "stub", minChars: 0 },
+    "system-note": { keep: "round", leave: "none", minChars: 0 },
+  },
+  tools: {},
+  dialects: {},
+};

package/src/context/retention/index.ts

@@ -0,0 +1,45 @@
+import { resolveRetention, serializePolicy, sessionRetentionLayer } from "./resolve.js";
+
+export { DEFAULT_CONTEXT_RETENTION, LEGACY_CONTEXT_RETENTION } from "./defaults.js";
+export { canonicalKeep, narrowRule } from "./narrow.js";
+export {
+  effectiveRule,
+  kindRule,
+  LEGACY_POLICY,
+  parsePolicy,
+  resolveRetention,
+  ruleFor,
+  serializePolicy,
+  sessionRetentionLayer,
+  type ResolvedPolicy,
+  type ResolveInput,
+  type ResolveResult,
+} from "./resolve.js";
+export { REF_CHARS, jobRef, visualRef } from "./render.js";
+export {
+  contextRetentionSchema,
+  parseRetentionLayer,
+  RETENTION_KINDS,
+  type ConcreteRule,
+  type ContextRetention,
+  type Horizon,
+  type Leave,
+  type RetentionKind,
+  type RetentionLayer,
+  type RuleInput,
+} from "./schema.js";
+export { decideRetentionStep, stampRetentionClock, type StepFacts } from "./step.js";
+export { kindOfJob, parseJobStamp, stampJobRetention, type JobStamp } from "./stamp.js";
+export { buildView, parseClock, policyOfTurn, type RetentionClock, type RetentionView } from "./view.js";
+
+/**
+ * R1: the policy JSON a turn is stamped with at mint. `userConfigJson` is
+ * `KernelRoot.contextRetentionJson`; session kv may only narrow it.
+ */
+export function turnRetentionJson(userConfigJson: string, kvs: Readonly<Record<string, string>>): string {
+  const { policy } = resolveRetention({
+    ...(userConfigJson === "" ? {} : { user: userConfigJson }),
+    session: sessionRetentionLayer(kvs),
+  });
+  return serializePolicy(policy);
+}

package/src/context/retention/narrow.ts

@@ -0,0 +1,123 @@
+/**
+ * Narrowing algebra. A narrowing layer appends conditions to `keep` ("whichever
+ * comes first"), may replace `leave` with a shorter remainder, and may lower
+ * `minChars`. It cannot lengthen anything: a source that tries is ignored for
+ * that key and reported.
+ */
+import { horizonList, NONE_FORBIDDEN_KINDS, type Horizon, type Leave, type RuleInput } from "./schema.js";
+
+/** How long a single condition keeps an item, as a comparable number. */
+export function horizonRank(h: Horizon): number {
+  if (h === "round") return 1;
+  if (h === "turn") return 1000;
+  if (h === "compaction") return 1_000_000;
+  if (h === "forever") return 10_000_000;
+  if ("rounds" in h) return h.rounds;
+  if ("turns" in h) return 1000 * h.turns;
+  return Number.POSITIVE_INFINITY; // `newest` bounds a count, not a span
+}
+
+/** Any-of semantics: the shortest condition decides how long an item lives. */
+export function keepRank(keep: readonly Horizon[]): number {
+  if (keep.length === 0) return 1_000_000;
+  return Math.min(...keep.map(horizonRank));
+}
+
+/** Canonical form of an any-of condition list: the tightest of each type, in a fixed order. */
+export function canonicalKeep(keep: readonly Horizon[]): Horizon[] {
+  let turns = Number.POSITIVE_INFINITY;
+  let rounds = Number.POSITIVE_INFINITY;
+  let newest = Number.POSITIVE_INFINITY;
+  let compaction = false;
+  let forever = false;
+  for (const h of keep) {
+    switch (h) {
+      case "round": {
+        rounds = Math.min(rounds, 1);
+        break;
+      }
+      case "turn": {
+        turns = Math.min(turns, 1);
+        break;
+      }
+      case "compaction": {
+        compaction = true;
+        break;
+      }
+      case "forever": {
+        forever = true;
+        break;
+      }
+      default:
+        if ("rounds" in h) rounds = Math.min(rounds, h.rounds);
+        else if ("turns" in h) turns = Math.min(turns, h.turns);
+        else newest = Math.min(newest, h.newest);
+    }
+  }
+  const out: Horizon[] = [];
+  if (Number.isFinite(turns)) out.push(turns === 1 ? "turn" : { turns });
+  if (Number.isFinite(rounds)) out.push(rounds === 1 ? "round" : { rounds });
+  if (Number.isFinite(newest)) out.push({ newest });
+  // `compaction` and `forever` only matter when nothing else bounds the item.
+  if (out.every((h): boolean => typeof h === "object" && "newest" in h)) {
+    if (compaction) out.push("compaction");
+    else if (forever) out.push("forever");
+  }
+  return out;
+}
+
+export function narrowKeep(base: readonly Horizon[], over: readonly Horizon[]): Horizon[] {
+  return canonicalKeep([...base, ...over]);
+}
+
+/** Remainder size, smallest first: none, a one-line stub, a summary, then `head` by length. */
+export function leaveRank(leave: Leave): number {
+  if (leave === "none") return 0;
+  if (leave === "stub") return 80;
+  if (leave === "summary") return 400;
+  return leave.head;
+}
+
+export function narrowLeave(base: Leave | undefined, over: Leave | undefined, kind: string | null): Leave | undefined {
+  if (over === undefined) return base;
+  if (over === "none" && kind !== null && NONE_FORBIDDEN_KINDS.has(kind)) return base;
+  if (base === undefined) return over;
+  return leaveRank(over) < leaveRank(base) ? over : base;
+}
+
+/** True when `over` shortens `base` in at least one respect. */
+export function narrows(base: RuleInput, over: RuleInput, kind: string | null): boolean {
+  const overKeep = horizonList(over.keep);
+  if (overKeep.length > 0) {
+    const baseKeep = horizonList(base.keep);
+    if (baseKeep.length === 0 || keepRank(overKeep) < keepRank(baseKeep)) return true;
+    if (overKeep.some((h) => typeof h === "object" && "newest" in h)) return true;
+  }
+  if (over.leave !== undefined && narrowLeave(base.leave, over.leave, kind) !== base.leave) return true;
+  if (over.minChars !== undefined && (base.minChars === undefined || over.minChars < base.minChars)) return true;
+  return false;
+}
+
+/** `base ∧ over`. The result never lives longer than `base`. */
+export function narrowRule(base: RuleInput, over: RuleInput, kind: string | null): RuleInput {
+  const keep = narrowKeep(horizonList(base.keep), horizonList(over.keep));
+  const leave = narrowLeave(base.leave, over.leave, kind);
+  const minChars =
+    over.minChars === undefined ? base.minChars : Math.min(base.minChars ?? Number.POSITIVE_INFINITY, over.minChars);
+  let onError = base.onError;
+  if (over.onError != null) {
+    onError =
+      base.onError == null
+        ? over.onError
+        : {
+            keep: narrowKeep(horizonList(base.onError.keep), horizonList(over.onError.keep)),
+            leave: narrowLeave(base.onError.leave, over.onError.leave, "error") ?? base.onError.leave,
+          };
+  }
+  return {
+    ...(keep.length === 0 ? {} : { keep: keep.length === 1 ? keep[0]! : keep }),
+    ...(leave === undefined ? {} : { leave }),
+    ...(minChars === undefined || !Number.isFinite(minChars) ? {} : { minChars }),
+    ...(onError === undefined ? {} : { onError }),
+  };
+}

package/src/context/retention/render.ts

@@ -0,0 +1,177 @@
+/**
+ * What an expired item leaves behind. Every remainder is deterministic: the
+ * same sealed receipt always renders to the same bytes (no timestamps, no
+ * ordering-dependent JSON), so a stub never moves the cached prefix.
+ */
+import type { Leave } from "./schema.js";
+
+export const REF_CHARS = 8;
+
+export function jobRef(uuid: string): string {
+  return `job:${uuid.slice(0, REF_CHARS)}`;
+}
+
+/** A node that is not yet materialized in a document has no uuid; it simply has no ref. */
+export function refOfNode(node: { readonly uuid: string }): string | undefined {
+  try {
+    return jobRef(node.uuid);
+  } catch {
+    return undefined;
+  }
+}
+
+export function visualRef(id: string): string {
+  return `visual:${id}`;
+}
+
+export function humanSize(chars: number): string {
+  if (chars < 1024) return `${chars} B`;
+  if (chars < 1024 * 1024) return `${(chars / 1024).toFixed(1)} KB`;
+  return `${(chars / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function oneLine(text: string, max: number): string {
+  const flat = text.replaceAll(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max)}…`;
+}
+
+export type StubFacts = {
+  /** Wire or program name. */
+  readonly tool: string;
+  readonly kind: string;
+  readonly ref: string;
+  readonly args: Readonly<Record<string, unknown>> | null;
+  /** The full painted observation the elision replaces. */
+  readonly full: string;
+  readonly ok: boolean;
+  readonly value: unknown;
+  readonly code: string | undefined;
+};
+
+function argString(args: StubFacts["args"], ...keys: string[]): string {
+  for (const key of keys) {
+    const value = args?.[key];
+    if (typeof value === "string" && value !== "") return value;
+  }
+  return "";
+}
+
+function lineCount(text: string): number {
+  if (text === "") return 0;
+  return text.split("\n").length;
+}
+
+function identityOf(f: StubFacts): string {
+  const size = humanSize(f.full.length);
+  switch (f.kind) {
+    case "tool.read": {
+      const target = argString(f.args, "path", "file_path", "pattern") || "?";
+      return `${oneLine(target, 120)}, ${lineCount(f.full)} lines, ${size}`;
+    }
+    case "tool.search": {
+      const needle = argString(f.args, "pattern", "query");
+      const where = argString(f.args, "path", "cwd");
+      return `"${oneLine(needle, 80)}"${where === "" ? "" : ` in ${oneLine(where, 80)}`}, ${lineCount(f.full)} lines`;
+    }
+    case "tool.web.search": {
+      const urls = [...f.full.matchAll(/https?:\/\/[^\s"'<>)\]]+/g)].map((m) => m[0]);
+      const unique = [...new Set(urls)];
+      const shown = unique.slice(0, 3).join(", ");
+      return `"${oneLine(argString(f.args, "query"), 80)}", ${unique.length} urls${shown === "" ? "" : `: ${shown}${unique.length > 3 ? "…" : ""}`}`;
+    }
+    case "tool.web.fetch":
+      return `${oneLine(argString(f.args, "url"), 160)}, ${size}`;
+    case "tool.program":
+      return `${oneLine(argString(f.args, "expr", "code", "program"), 80)} → ${size}`;
+    default: {
+      const target = argString(f.args, "path", "file_path", "pattern", "query", "command", "url", "name");
+      return target === "" ? size : `${oneLine(target, 80)}, ${size}`;
+    }
+  }
+}
+
+function recallHint(f: StubFacts): string {
+  return f.kind === "tool.read" ? `re-read or recall ${f.ref}` : `recall ${f.ref}`;
+}
+
+export function stubLine(f: StubFacts): string {
+  return `[${f.tool} elided: ${identityOf(f)} — ${recallHint(f)}]`;
+}
+
+function exitCodeOf(value: unknown): number | null {
+  if (value == null || typeof value !== "object") return null;
+  const code = (value as Record<string, unknown>).exitCode;
+  return typeof code === "number" ? code : null;
+}
+
+function tailLines(f: StubFacts, count: number): string {
+  const rec = f.value != null && typeof f.value === "object" ? (f.value as Record<string, unknown>) : null;
+  const stdout = typeof rec?.stdout === "string" ? rec.stdout : "";
+  const stderr = typeof rec?.stderr === "string" ? rec.stderr : "";
+  const text = rec === null || (stdout === "" && stderr === "") ? f.full : `${stdout}\n${stderr}`;
+  const lines = text
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== "");
+  return lines
+    .slice(-count)
+    .map((line) => oneLine(line, 160))
+    .join(" | ");
+}
+
+function shellSummary(f: StubFacts): string {
+  const command = oneLine(argString(f.args, "command"), 80);
+  const exit = exitCodeOf(f.value);
+  const status = exit === null ? (f.ok ? "ok" : "failed") : `exit ${exit}`;
+  const tail = tailLines(f, 5);
+  return `[shell \`${command}\` ${status}, ${humanSize(f.full.length)} elided${tail === "" ? "" : `; tail: ${tail}`} — recall ${f.ref}]`;
+}
+
+function errorSummary(f: StubFacts): string {
+  const first = oneLine(f.full.split("\n").find((line) => line.trim() !== "") ?? "", 200);
+  const code = f.code === undefined || f.code === "" ? "" : ` (${f.code})`;
+  return `[${f.tool} failed${code}: ${first} — recall ${f.ref}]`;
+}
+
+function genericSummary(f: StubFacts): string {
+  return `${oneLine(f.full, 200)} [${f.tool} elided, ${humanSize(f.full.length)} — recall ${f.ref}]`;
+}
+
+/** The remainder of a tool result whose horizon has passed. */
+export function toolRemainder(leave: Leave, f: StubFacts, failed: boolean): string {
+  if (leave === "none" || leave === "stub") return stubLine(f);
+  if (leave === "summary") {
+    if (f.kind === "tool.shell") return shellSummary(f);
+    if (failed) return errorSummary(f);
+    return genericSummary(f);
+  }
+  return `${f.full.slice(0, leave.head)}\n${stubLine(f)}`;
+}
+
+/** The remainder of a prelude cell (steer, note, notification, system note). `null` leaves nothing. */
+export function textRemainder(leave: Leave, kind: string, text: string): string | null {
+  if (leave === "none") return null;
+  if (leave === "stub") return `[${kind} elided: ${text.length} chars]`;
+  if (leave === "summary") return `${oneLine(text, 200)} [${kind} elided, ${text.length} chars]`;
+  return `${text.slice(0, leave.head)} [${kind} elided, ${text.length} chars]`;
+}
+
+/** Large string fields of a call's arguments become a stub; the JSON stays valid. */
+export function elideArgs(
+  args: Readonly<Record<string, unknown>>,
+  ref: string,
+  minChars: number,
+): { readonly json: string; readonly elided: boolean } {
+  const out: Record<string, unknown> = {};
+  let elided = false;
+  const total = JSON.stringify(args).length;
+  for (const [key, value] of Object.entries(args)) {
+    if (total >= minChars && typeof value === "string" && value.length > 200) {
+      out[key] = `[elided: ${lineCount(value)} lines, ${humanSize(value.length)} — recall ${ref}]`;
+      elided = true;
+    } else {
+      out[key] = value;
+    }
+  }
+  return { json: JSON.stringify(out), elided };
+}