@inhuman.tools/turn 0.0.0-stage → 0.1.0

package/dist/context/retention/step.d.ts

@@ -0,0 +1,33 @@
+/**
+ * R3: the retention clock. Deep horizons expire against `at`, which only moves
+ * at a step, so between steps the projected prefix is byte-stable and only the
+ * tail grows. The live inputs (wall clock, prior `warmUntilMs`, estimated
+ * savings) are read once here and recorded; the projection reads only `at`.
+ */
+import { CompletionExpectation } from "@inhuman.tools/harness-model";
+import type { StepConfig } from "./schema.js";
+import { type RetentionClock } from "./view.js";
+export type StepFacts = {
+    readonly self: string;
+    readonly step: StepConfig;
+    /** Prior completion on the spine: its recorded clock target, and when its cache lapses. */
+    readonly prior: {
+        readonly at: string | null;
+        readonly warmUntilMs: number | null;
+    } | null;
+    readonly turnFirstRound: boolean;
+    readonly afterCutoff: boolean;
+    /** Rounds between the prior clock target and this completion. */
+    readonly roundsSinceAt: number;
+    readonly now: number;
+    /** Estimated tokens a step would free. Lazy: walks the spine. */
+    readonly freedTokens: () => number;
+};
+/** Pure: the order is compaction, turn, cold, every, freed, else hold. */
+export declare function decideRetentionStep(f: StepFacts): RetentionClock;
+/**
+ * Stamp `tip.retentionClockJson` when its round opens. Call once the
+ * completion is on its turn's tape (it must be reachable from its turn).
+ */
+export declare function stampRetentionClock(tip: CompletionExpectation, now?: number): RetentionClock;
+//# sourceMappingURL=step.d.ts.map

package/dist/context/retention/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../src/context/retention/step.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,qBAAqB,EAAmC,MAAM,8BAA8B,CAAC;AAGtG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAE5F,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3F,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,CAAC;CACpC,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,GAAG,cAAc,CAkBhE;AASD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,qBAAqB,EAAE,GAAG,GAAE,MAAmB,GAAG,cAAc,CA0BxG"}

package/dist/context/retention/step.js

@@ -0,0 +1,74 @@
+/**
+ * R3: the retention clock. Deep horizons expire against `at`, which only moves
+ * at a step, so between steps the projected prefix is byte-stable and only the
+ * tail grows. The live inputs (wall clock, prior `warmUntilMs`, estimated
+ * savings) are read once here and recorded; the projection reads only `at`.
+ */
+import { latestCompactCutoff, owningTurn } from "@inhuman.tools/harness-model";
+import { projectHistory } from "../history.js";
+import { parseClock, policyOfTurn } from "./view.js";
+/** Pure: the order is compaction, turn, cold, every, freed, else hold. */
+export function decideRetentionStep(f) {
+    const step = (reason, extra = {}) => ({
+        at: f.self,
+        reason,
+        ...extra,
+    });
+    if (f.afterCutoff && f.step.atCompaction)
+        return step("compaction");
+    const priorAt = f.prior?.at ?? null;
+    if (priorAt === null)
+        return step("turn");
+    if (f.turnFirstRound && f.step.turnBoundary)
+        return step("turn");
+    const warm = f.prior?.warmUntilMs ?? null;
+    if (f.step.whenCacheCold && warm !== null && f.now > warm)
+        return step("cold", { coldByMs: f.now - warm });
+    if (f.step.everyRounds !== null && f.roundsSinceAt >= f.step.everyRounds)
+        return step("every");
+    if (f.step.minFreedTokens > 0) {
+        const freed = f.freedTokens();
+        if (freed >= f.step.minFreedTokens)
+            return step("freed", { freedTokens: freed });
+    }
+    return { at: priorAt, reason: "hold" };
+}
+function tokensOf(rows) {
+    let chars = 0;
+    for (const row of rows)
+        chars += JSON.stringify(row, (_key, value) => (value instanceof Uint8Array ? value.length : value)).length;
+    return Math.ceil(chars / 4);
+}
+/**
+ * Stamp `tip.retentionClockJson` when its round opens. Call once the
+ * completion is on its turn's tape (it must be reachable from its turn).
+ */
+export function stampRetentionClock(tip, now = Date.now()) {
+    const turn = owningTurn(tip);
+    const policy = policyOfTurn(turn);
+    const spine = tip.spine();
+    const index = spine.indexOf(tip);
+    const prior = index > 0 ? spine[index - 1] : null;
+    const priorAt = prior === null ? null : (parseClock(prior.retentionClockJson)?.at ?? null);
+    const priorPos = priorAt === null ? -1 : spine.findIndex((c) => c.uuid === priorAt);
+    const clock = decideRetentionStep({
+        self: tip.uuid,
+        step: policy.step,
+        prior: prior === null ? null : { at: priorPos < 0 ? null : priorAt, warmUntilMs: prior.warmUntilMs },
+        turnFirstRound: prior === null || owningTurn(prior) !== turn,
+        afterCutoff: prior === null && turn !== null && latestCompactCutoff(turn) !== null,
+        roundsSinceAt: priorPos < 0 ? 0 : index - priorPos,
+        now,
+        freedTokens: () => {
+            const held = spine[priorPos];
+            if (held === undefined)
+                return 0;
+            const before = tokensOf(projectHistory(tip, { clockAt: held }));
+            const after = tokensOf(projectHistory(tip, { clockAt: tip }));
+            return Math.max(0, before - after);
+        },
+    });
+    tip.retentionClockJson = JSON.stringify(clock);
+    return clock;
+}
+//# sourceMappingURL=step.js.map

package/dist/context/retention/step.js.map

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

package/dist/context/retention/view.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The positions a retention decision is made against. Everything here is read
+ * from recorded facts: the completion order, each turn's R1 stamp, and the
+ * tip's R3 clock. Nothing reads config, kv, the catalog or the wall clock, so
+ * a restart re-projects byte-identically.
+ */
+import { CompletionExpectation, SessionTurn } from "@inhuman.tools/harness-model";
+import { type ResolvedPolicy } from "./resolve.js";
+import type { Horizon } from "./schema.js";
+export type ClockReason = "turn" | "every" | "freed" | "cold" | "compaction" | "hold";
+export type RetentionClock = {
+    /** Uuid of the completion the deep horizons are evaluated against. */
+    readonly at: string;
+    readonly reason: ClockReason;
+    readonly coldByMs?: number;
+    readonly freedTokens?: number;
+};
+export declare function parseClock(json: string): RetentionClock | null;
+/** A turn's policy: its own R1 stamp, else the nearest tail's, else the legacy rule set. */
+export declare function policyOfTurn(turn: SessionTurn | null): ResolvedPolicy;
+export type RetentionView = {
+    readonly tip: CompletionExpectation;
+    readonly order: readonly CompletionExpectation[];
+    readonly tipPos: number;
+    readonly tipTurn: number;
+    /** Null: no recorded clock, so deep horizons never expire anything. */
+    readonly clockPos: number | null;
+    readonly clockTurn: number | null;
+    readonly dialect: string | undefined;
+    posOf(c: CompletionExpectation): number;
+    turnOf(c: CompletionExpectation): number;
+    policyOf(c: CompletionExpectation): ResolvedPolicy;
+    /** The completion after `c`, which consumes `c`'s tool results. */
+    nextOf(c: CompletionExpectation): CompletionExpectation | null;
+};
+export type ViewOptions = {
+    /** Evaluate the deep horizons here instead of at the recorded clock. Used to estimate a step. */
+    readonly clockAt?: CompletionExpectation | null;
+    readonly dialect?: string;
+};
+/** `order` is the lead (kept zone) completions, then the spine, ending at the tip. */
+export declare function buildView(tip: CompletionExpectation, order: readonly CompletionExpectation[], options?: ViewOptions): RetentionView;
+export type ItemPlace = {
+    /** The completion whose input first contains the item. */
+    readonly consumer: CompletionExpectation;
+    /** The completion that produced or claimed the item; its turn is the item's turn. */
+    readonly owner: CompletionExpectation;
+    /** Evaluate against the tip instead of the clock. Pictures live only within their own turn. */
+    readonly againstTip?: boolean;
+};
+/**
+ * Any condition met expires the item. `newest` is decided by the caller,
+ * which ranks items of one kind; it is not a span.
+ */
+export declare function horizonExpired(keep: readonly Horizon[], view: RetentionView, place: ItemPlace): boolean;
+export declare function newestOf(keep: readonly Horizon[]): number | null;
+//# sourceMappingURL=view.d.ts.map

package/dist/context/retention/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/context/retention/view.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,qBAAqB,EAAc,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE9F,OAAO,EAA8B,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,CAAC;AAEtF,MAAM,MAAM,cAAc,GAAG;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAIF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAgB9D;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,cAAc,CAQrE;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,KAAK,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IACxC,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,CAAC,EAAE,qBAAqB,GAAG,cAAc,CAAC;IACnD,mEAAmE;IACnE,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,IAAI,CAAC;CAChE,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,iGAAiG;IACjG,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,SAAS,CACvB,GAAG,EAAE,qBAAqB,EAC1B,KAAK,EAAE,SAAS,qBAAqB,EAAE,EACvC,OAAO,GAAE,WAAgB,GACxB,aAAa,CAgCf;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CA0BvG;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CAMhE"}

package/dist/context/retention/view.js

@@ -0,0 +1,121 @@
+/**
+ * The positions a retention decision is made against. Everything here is read
+ * from recorded facts: the completion order, each turn's R1 stamp, and the
+ * tip's R3 clock. Nothing reads config, kv, the catalog or the wall clock, so
+ * a restart re-projects byte-identically.
+ */
+import { owningTurn, SessionTurn } from "@inhuman.tools/harness-model";
+import { LEGACY_POLICY, parsePolicy } from "./resolve.js";
+const REASONS = new Set(["turn", "every", "freed", "cold", "compaction", "hold"]);
+export function parseClock(json) {
+    if (json === "")
+        return null;
+    try {
+        const raw = JSON.parse(json);
+        if (typeof raw.at !== "string" || raw.at === "" || typeof raw.reason !== "string" || !REASONS.has(raw.reason)) {
+            return null;
+        }
+        return {
+            at: raw.at,
+            reason: raw.reason,
+            ...(typeof raw.coldByMs === "number" ? { coldByMs: raw.coldByMs } : {}),
+            ...(typeof raw.freedTokens === "number" ? { freedTokens: raw.freedTokens } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** A turn's policy: its own R1 stamp, else the nearest tail's, else the legacy rule set. */
+export function policyOfTurn(turn) {
+    const seen = new Set();
+    for (let cell = turn; cell instanceof SessionTurn && !seen.has(cell); cell = cell.turnTail) {
+        seen.add(cell);
+        const parsed = parsePolicy(cell.retentionJson);
+        if (parsed !== null)
+            return parsed;
+    }
+    return LEGACY_POLICY;
+}
+/** `order` is the lead (kept zone) completions, then the spine, ending at the tip. */
+export function buildView(tip, order, options = {}) {
+    const pos = new Map();
+    const turnOrd = new Map();
+    const turns = new Map();
+    for (const [index, c] of order.entries()) {
+        pos.set(c, index);
+        const turn = owningTurn(c);
+        if (!turns.has(turn))
+            turns.set(turn, turns.size);
+        turnOrd.set(c, turns.get(turn) ?? 0);
+    }
+    const posOf = (c) => pos.get(c) ?? -1;
+    const turnOf = (c) => turnOrd.get(c) ?? 0;
+    let clockCompletion;
+    if (options.clockAt !== undefined)
+        clockCompletion = options.clockAt;
+    else {
+        const clock = parseClock(tip.retentionClockJson);
+        clockCompletion = clock === null ? null : (order.find((c) => c.uuid === clock.at) ?? null);
+    }
+    const clockPos = clockCompletion === null ? null : posOf(clockCompletion);
+    return {
+        tip,
+        order,
+        tipPos: posOf(tip),
+        tipTurn: turnOf(tip),
+        clockPos: clockPos === null || clockPos < 0 ? null : clockPos,
+        clockTurn: clockPos === null || clockPos < 0 || clockCompletion === null ? null : turnOf(clockCompletion),
+        dialect: options.dialect,
+        posOf,
+        turnOf,
+        policyOf: (c) => policyOfTurn(owningTurn(c)),
+        nextOf: (c) => order[posOf(c) + 1] ?? null,
+    };
+}
+/**
+ * Any condition met expires the item. `newest` is decided by the caller,
+ * which ranks items of one kind; it is not a span.
+ */
+export function horizonExpired(keep, view, place) {
+    const consumerPos = view.posOf(place.consumer);
+    const ownerTurn = view.turnOf(place.owner);
+    if (consumerPos < 0)
+        return false;
+    for (const h of keep) {
+        if (h === "round") {
+            if (view.tipPos - consumerPos >= 1)
+                return true;
+            continue;
+        }
+        if (h === "turn") {
+            const ref = place.againstTip === true ? view.tipTurn : view.clockTurn;
+            if (ref !== null && ref > ownerTurn)
+                return true;
+            continue;
+        }
+        if (h === "compaction" || h === "forever")
+            continue;
+        if ("rounds" in h) {
+            const ref = h.rounds === 1 || place.againstTip === true ? view.tipPos : view.clockPos;
+            if (ref !== null && ref - consumerPos >= h.rounds)
+                return true;
+            continue;
+        }
+        if ("turns" in h) {
+            const ref = place.againstTip === true ? view.tipTurn : view.clockTurn;
+            if (ref !== null && ref - ownerTurn >= h.turns)
+                return true;
+        }
+    }
+    return false;
+}
+export function newestOf(keep) {
+    let out = null;
+    for (const h of keep) {
+        if (typeof h === "object" && "newest" in h)
+            out = out === null ? h.newest : Math.min(out, h.newest);
+    }
+    return out;
+}
+//# sourceMappingURL=view.js.map

package/dist/context/retention/view.js.map

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

package/dist/context/squeeze.d.ts

@@ -0,0 +1,45 @@
+import { ProgrammaticJob, ToolCallJob, type ToolCallRepresentation } from "@inhuman.tools/harness-model";
+export type SqueezeTo = "compact" | "micro";
+/** Measured optimal observation size. Chars, not tokens. */
+export declare const SQUEEZE_COMPACT_CHARS = 5000;
+/** Below this, micro is a no-op — replacing a short answer with a path is pointless. */
+export declare const SQUEEZE_MICRO_MIN_CHARS = 100;
+export type SqueezeInput = {
+    readonly to: SqueezeTo;
+    readonly payload: unknown;
+    readonly persistable: boolean;
+    /** `job:<ref>` the model passes to `context_recall`. Without it a reduced result carries no pointer. */
+    readonly recallRef?: string;
+    readonly name: string;
+};
+/** Source observation as a string. Top-level strings stay raw; values ride the serializer. */
+export declare function paintObservation(payload: unknown): string;
+export declare function squeezeObservation(input: SqueezeInput): string;
+export type ToolImage = {
+    /** 1-based position among this result's images. */
+    readonly index: number;
+    readonly mime: string;
+    readonly size: number;
+    /** Null when the block was not valid base64 or exceeds the wire cap. */
+    readonly bytes: Uint8Array | null;
+};
+/** Dimensionless note: `[Image 1: image/png, 31.4 KB]`, or the elided form with a recall pointer. */
+export declare function toolImageLine(image: ToolImage, state: "shown" | "elided", ref?: string): string;
+/**
+ * Pull image content blocks out of a result so base64 never reaches the model
+ * as text. The painted payload keeps a one-line note per image.
+ */
+export declare function liftToolImages(payload: unknown, note?: (image: ToolImage) => string): {
+    readonly payload: unknown;
+    readonly images: readonly ToolImage[];
+};
+/** The images a sealed tool result carries, in order. */
+export declare function toolImagesOf(tool: ToolCallJob): readonly ToolImage[];
+/** Compact line derived from the sealed receipt. */
+export declare function compactToolLine(job: ToolCallJob | ProgrammaticJob): string;
+/** scheme_repl / exam results ride the same cap and pointer as tool results. */
+export declare function squeezeProgrammaticText(job: ProgrammaticJob, text: string): string;
+/** Server-side compact wire paint. Not a client-document method. */
+export declare function squeezeToolCall(tool: ToolCallJob, to: SqueezeTo, note?: (image: ToolImage) => string): string;
+export declare function toolCallRepresentation(tool: ToolCallJob): ToolCallRepresentation;
+//# sourceMappingURL=squeeze.d.ts.map

package/dist/context/squeeze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"squeeze.d.ts","sourceRoot":"","sources":["../../src/context/squeeze.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAIzG,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,wGAAwG;IACxG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIzD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA4B9D;AA4BD,MAAM,MAAM,SAAS,GAAG;IACtB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACnC,CAAC;AAsBF,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAiD,GAC5E;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,CAmBtE;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,SAAS,EAAE,CAEpE;AAOD,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,eAAe,GAAG,MAAM,CAO1E;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlF;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,GAAG,MAAM,CAQ7G;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,sBAAsB,CAOhF"}

package/dist/context/squeeze.js

@@ -0,0 +1,182 @@
+/**
+ * Squeeze — tool-call observation paint. Not compact. Not settlement.
+ *
+ * Stored `outcomeJson` stays the source. This module projects it for the wire.
+ * Compact.scm does not inspect payload size.
+ *
+ * A reduced observation points at `context_recall`: the sealed receipt is read
+ * back from the graph, paged, instead of from a `/tmp` copy. There is no second
+ * world on disk. Regenerateable results (`read` | `net`) get no pointer:
+ * re-invoking is the address.
+ *
+ * Top-level strings stay raw text (a file body stays a file body). Serializer
+ * quoting of a top-level string is the wrong observation for read_file.
+ * Structured `value` payloads ride `toSExprString` caps — not a second compact
+ * pass in the driver.
+ *
+ * MCP image blocks never ride as base64 text: {@link liftToolImages} takes them
+ * out of the painted observation, and the projection decides whether the model
+ * sees the picture or a stub.
+ */
+import { toSExprString, toSExprStringWithElisions } from "@here.build/arrival-serializer";
+import { ToolCallJob } from "@inhuman.tools/harness-model";
+import { humanSize, refOfNode } from "./retention/render.js";
+/** Measured optimal observation size. Chars, not tokens. */
+export const SQUEEZE_COMPACT_CHARS = 5000;
+/** Below this, micro is a no-op — replacing a short answer with a path is pointless. */
+export const SQUEEZE_MICRO_MIN_CHARS = 100;
+/** Source observation as a string. Top-level strings stay raw; values ride the serializer. */
+export function paintObservation(payload) {
+    if (payload === undefined)
+        return "";
+    if (typeof payload === "string")
+        return payload;
+    return toSExprString(payload);
+}
+export function squeezeObservation(input) {
+    const { to, payload, persistable, name } = input;
+    const pointer = persistable && input.recallRef !== undefined ? recallComment(input.recallRef) : "";
+    if (typeof payload === "string") {
+        if (to === "micro") {
+            if (payload.length < SQUEEZE_MICRO_MIN_CHARS)
+                return payload;
+            if (!persistable)
+                return clearedStub(name);
+            return pointer === "" ? compactBody(payload).text : pointer;
+        }
+        const { text, reduced } = compactBody(payload);
+        if (reduced && pointer !== "")
+            return `${pointer}\n${text}`;
+        return text;
+    }
+    if (to === "micro") {
+        const full = paintObservation(payload);
+        if (full.length < SQUEEZE_MICRO_MIN_CHARS)
+            return full;
+        if (!persistable)
+            return clearedStub(name);
+        return pointer === "" ? squeezeValue(payload) : pointer;
+    }
+    const { text, reduced } = toSExprStringWithElisions(payload, {
+        maxTotalChars: SQUEEZE_COMPACT_CHARS,
+        maxStringChars: SQUEEZE_COMPACT_CHARS,
+    });
+    if (reduced && pointer !== "")
+        return `${pointer}\n${text}`;
+    return text;
+}
+function squeezeValue(payload) {
+    return toSExprString(payload, {
+        maxTotalChars: SQUEEZE_COMPACT_CHARS,
+        maxStringChars: SQUEEZE_COMPACT_CHARS,
+    });
+}
+function compactBody(payload) {
+    if (payload.length <= SQUEEZE_COMPACT_CHARS)
+        return { text: payload, reduced: false };
+    const dropped = payload.length - SQUEEZE_COMPACT_CHARS;
+    return {
+        text: `${payload.slice(0, SQUEEZE_COMPACT_CHARS)}…(+${dropped} chars)`,
+        reduced: true,
+    };
+}
+function recallComment(ref) {
+    return `;;full response: context_recall ${JSON.stringify({ ref })}`;
+}
+function clearedStub(name) {
+    return name === "" ? "[Old tool result content cleared]" : `[Old ${name} result content cleared]`;
+}
+const MAX_TOOL_IMAGE_BYTES = 5 * 1024 * 1024;
+function isImageBlock(block) {
+    return typeof block === "object" && block !== null && block.type === "image";
+}
+function decodeBase64(data) {
+    if (typeof data !== "string")
+        return null;
+    const compact = data.replaceAll(/\s/g, "");
+    if (compact === "" || compact.length % 4 !== 0 || !/^[\w+/-]+={0,2}$/.test(compact))
+        return null;
+    const decoded = Buffer.from(compact, "base64");
+    if (decoded.length === 0 || decoded.length > MAX_TOOL_IMAGE_BYTES)
+        return null;
+    return new Uint8Array(decoded);
+}
+/** Dimensionless note: `[Image 1: image/png, 31.4 KB]`, or the elided form with a recall pointer. */
+export function toolImageLine(image, state, ref) {
+    const head = `Image ${image.index}${state === "elided" ? " elided" : ""}: ${image.mime}, ${humanSize(image.size)}`;
+    return state === "elided" && ref !== undefined ? `[${head} — recall ${ref}]` : `[${head}]`;
+}
+/**
+ * Pull image content blocks out of a result so base64 never reaches the model
+ * as text. The painted payload keeps a one-line note per image.
+ */
+export function liftToolImages(payload, note = (image) => toolImageLine(image, "shown")) {
+    if (!Array.isArray(payload) || !payload.some((block) => isImageBlock(block)))
+        return { payload, images: [] };
+    const images = [];
+    const lifted = payload.map((block) => {
+        if (!isImageBlock(block))
+            return block;
+        const mimeRaw = block.mimeType ?? block.mime_type;
+        const bytes = decodeBase64(block.data);
+        const size = bytes === null ? (typeof block.data === "string" ? Math.floor((block.data.length * 3) / 4) : 0) : bytes.length;
+        const image = {
+            index: images.length + 1,
+            mime: typeof mimeRaw === "string" && mimeRaw !== "" ? mimeRaw : "image",
+            size,
+            bytes,
+        };
+        images.push(image);
+        return { type: "text", text: note(image) };
+    });
+    return { payload: lifted, images };
+}
+/** The images a sealed tool result carries, in order. */
+export function toolImagesOf(tool) {
+    return liftToolImages(tool.observationPayload()).images;
+}
+function refField(node) {
+    const ref = refOfNode(node);
+    return ref === undefined ? {} : { recallRef: ref };
+}
+/** Compact line derived from the sealed receipt. */
+export function compactToolLine(job) {
+    if (job instanceof ToolCallJob && job.regenerateable)
+        return "";
+    if (job instanceof ToolCallJob)
+        return squeezeToolCall(job, "compact");
+    const parts = job.resultParts();
+    if (parts !== undefined)
+        return parts.map((part) => squeezeProgrammaticText(job, part.text)).join("\n");
+    const text = job.resultText();
+    return squeezeProgrammaticText(job, text !== "" ? text : (job.receiptJson ?? ""));
+}
+/** scheme_repl / exam results ride the same cap and pointer as tool results. */
+export function squeezeProgrammaticText(job, text) {
+    return squeezeObservation({
+        to: "compact",
+        payload: text,
+        persistable: true,
+        ...refField(job),
+        name: "",
+    });
+}
+/** Server-side compact wire paint. Not a client-document method. */
+export function squeezeToolCall(tool, to, note) {
+    return squeezeObservation({
+        to,
+        payload: liftToolImages(tool.observationPayload(), note).payload,
+        persistable: !tool.regenerateable,
+        ...refField(tool),
+        name: tool.name,
+    });
+}
+export function toolCallRepresentation(tool) {
+    return {
+        id: tool.toolCallId,
+        name: tool.name,
+        args: tool.invocation(),
+        result: paintObservation(liftToolImages(tool.observationPayload()).payload),
+    };
+}
+//# sourceMappingURL=squeeze.js.map

package/dist/context/squeeze.js.map

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

package/dist/context/tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Completion tools[] face: frozen turn.tools when present, else live catalog.
+ * Vendor OpenAI wrapping stays in the actor. Live-catalog scheme_repl
+ * description overlay is also the actor — frozen ToolSpec text is left as-is.
+ */
+import { CompletionExpectation } from "@inhuman.tools/harness-model";
+import { KernelToolCatalog } from "../tool-catalog/index.js";
+export type ContextTool = {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+};
+export declare function liveCatalogOf(expectation: CompletionExpectation, catalog?: KernelToolCatalog): KernelToolCatalog | undefined;
+/** Frozen turn set wins so MCP churn cannot rewrite the prefix. */
+export declare function selectCompletionTools(expectation: CompletionExpectation, catalog?: KernelToolCatalog): readonly ContextTool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/context/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/context/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGL,qBAAqB,EAGtB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAa,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAExE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C,CAAC;AAEF,wBAAgB,aAAa,CAC3B,WAAW,EAAE,qBAAqB,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,iBAAiB,GAAG,SAAS,CAE/B;AAED,mEAAmE;AACnE,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,qBAAqB,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,SAAS,WAAW,EAAE,CA6BxB"}