stageflow 0.40.0 → 0.44.0

package/dist/cli/exportAllCommand.js

@@ -135,7 +135,7 @@ function parseExportArgs(args) {
 }
 export async function* iterateExportNdjson(options) {
     yield `${JSON.stringify(buildExportHeader(options.filter, options.now ?? new Date()))}\n`;
-    const runs = await options.store.listRuns(options.filter);
+    const runs = await options.store.listRuns({ ...options.filter, origin: "any" });
     for (const summary of runs) {
         const detail = await options.store.readRun(summary.run_id);
         const pipelineBody = await options.store.readPipelineBody(summary.run_id);

package/dist/cli/hostClient.d.ts

@@ -77,5 +77,65 @@ export type HttpListTriggersResult = {
 export declare function httpFireTrigger(base: string, triggerId: string, task?: Record<string, unknown>): Promise<StartRunResult>;
 export declare function httpListTriggers(base: string): Promise<HttpListTriggersResult>;
 export declare function httpGetTrigger(base: string, triggerId: string): Promise<HttpTriggerLookupResult>;
+export type HttpEvalResult<T> = {
+    ok: true;
+    body: T;
+} | {
+    ok: false;
+    reason: string;
+    status: number;
+    code?: string;
+    findings?: unknown[];
+};
+export declare function httpListEvals(base: string, projectRoot?: string): Promise<HttpEvalResult<Record<string, unknown>>>;
+export declare function httpGetEval(base: string, evalId: string, projectRoot?: string): Promise<HttpEvalResult<Record<string, unknown>>>;
+export declare function httpValidateEval(base: string, input: {
+    project_root?: string;
+    yaml?: string;
+    path?: string;
+}): Promise<HttpEvalResult<Record<string, unknown>>>;
+export type HttpStartEvalRunInput = {
+    project_root?: string;
+    repeats?: number;
+    judge?: string;
+    model?: string;
+    user_model?: string;
+    allow_real_tools?: boolean;
+    max_cost_usd?: number;
+    case_ids?: string[];
+    tags?: string[];
+    label?: string;
+    started_via?: "console" | "cli" | "mcp";
+};
+export declare function httpStartEvalRun(base: string, evalId: string, input: HttpStartEvalRunInput): Promise<HttpEvalResult<{
+    eval_run_id: string;
+    status: string;
+    run_number?: number;
+}>>;
+export declare function httpGetEvalRun(base: string, evalRunId: string): Promise<HttpEvalResult<Record<string, any>>>;
+export declare function httpCancelEvalRun(base: string, evalRunId: string): Promise<HttpEvalResult<Record<string, any>>>;
+export declare function httpSortEvalFailures(base: string, evalRunId: string, input: {
+    classifier?: "auto" | "jev" | "judge";
+    only_unsorted?: boolean;
+    limit?: number;
+}): Promise<HttpEvalResult<Record<string, any>>>;
+export declare function httpListEvalSuggestions(base: string, evalRunId: string, status?: string): Promise<HttpEvalResult<{
+    items: Array<Record<string, any>>;
+    summary: Record<string, any>;
+}>>;
+export declare function httpListEvalRuns(base: string, query?: {
+    eval_id?: string;
+    project_root?: string;
+    limit?: number;
+    cursor?: string;
+}): Promise<HttpEvalResult<{
+    items: Array<Record<string, unknown>>;
+    next_cursor: string | null;
+}>>;
+export declare function httpDeleteEvalRun(base: string, evalRunId: string): Promise<HttpEvalResult<null>>;
+export declare function httpCompareEvalRuns(base: string, a: string, b: string): Promise<HttpEvalResult<Record<string, unknown>>>;
+export declare function httpListDatasets(base: string, projectRoot?: string): Promise<HttpEvalResult<{
+    items: Array<Record<string, unknown>>;
+}>>;
 export declare function resolveAbsolute(cwd: string, maybeRelative: string): string;
 export {};

package/dist/cli/hostClient.js

@@ -292,6 +292,77 @@ export async function httpGetTrigger(base, triggerId) {
     }
     return { ok: true, trigger: body };
 }
+function evalFailure(status, body) {
+    const rec = body && typeof body === "object" ? body : {};
+    return {
+        ok: false,
+        reason: extractError(body, status),
+        status,
+        ...(typeof rec.code === "string" ? { code: rec.code } : {}),
+        ...(Array.isArray(rec.findings) ? { findings: rec.findings } : {}),
+    };
+}
+function evalQuery(params) {
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === "")
+            continue;
+        parts.push(`${key}=${enc(String(value))}`);
+    }
+    return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+async function evalGet(base, urlPath, expected = 200) {
+    const { status, body } = await getJson(base, urlPath);
+    return status === expected ? { ok: true, body: body } : evalFailure(status, body);
+}
+export function httpListEvals(base, projectRoot) {
+    return evalGet(base, `/api/evals${evalQuery({ project_root: projectRoot })}`);
+}
+export function httpGetEval(base, evalId, projectRoot) {
+    return evalGet(base, `/api/evals/${enc(evalId)}${evalQuery({ project_root: projectRoot })}`);
+}
+export async function httpValidateEval(base, input) {
+    const { status, body } = await postJson(base, "/api/evals/validate", input);
+    return status === 200 ? { ok: true, body: body } : evalFailure(status, body);
+}
+export async function httpStartEvalRun(base, evalId, input) {
+    const { status, body } = await postJson(base, `/api/evals/${enc(evalId)}/runs`, input);
+    return status === 202
+        ? { ok: true, body: body }
+        : evalFailure(status, body);
+}
+export function httpGetEvalRun(base, evalRunId) {
+    return evalGet(base, `/api/eval-runs/${enc(evalRunId)}`);
+}
+export async function httpCancelEvalRun(base, evalRunId) {
+    const { status, body } = await postJson(base, `/api/eval-runs/${enc(evalRunId)}/cancel`, {});
+    return status === 200 ? { ok: true, body: body } : evalFailure(status, body);
+}
+export async function httpSortEvalFailures(base, evalRunId, input) {
+    const { status, body } = await postJson(base, `/api/eval-runs/${enc(evalRunId)}/failures/sort`, input);
+    return status === 200 ? { ok: true, body: body } : evalFailure(status, body);
+}
+export function httpListEvalSuggestions(base, evalRunId, status) {
+    return evalGet(base, `/api/eval-runs/${enc(evalRunId)}/failures/suggestions${evalQuery({ status })}`);
+}
+export function httpListEvalRuns(base, query = {}) {
+    return evalGet(base, `/api/eval-runs${evalQuery(query)}`);
+}
+export async function httpDeleteEvalRun(base, evalRunId) {
+    const res = await fetch(`${base}/api/eval-runs/${enc(evalRunId)}`, {
+        method: "DELETE",
+        headers: { ...clientAuthorizationHeaders("DELETE") },
+    });
+    if (res.status === 204)
+        return { ok: true, body: null };
+    return evalFailure(res.status, await parseJsonBody(res));
+}
+export function httpCompareEvalRuns(base, a, b) {
+    return evalGet(base, `/api/eval-compare${evalQuery({ a, b })}`);
+}
+export function httpListDatasets(base, projectRoot) {
+    return evalGet(base, `/api/datasets${evalQuery({ project_root: projectRoot })}`);
+}
 export function resolveAbsolute(cwd, maybeRelative) {
     return path.resolve(cwd, maybeRelative);
 }

package/dist/cli/validateOutput.d.ts

@@ -1,6 +1,6 @@
 import type { ValidationResult } from "../config/validateCatalog.js";
-export declare const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, and tasks as selected by flags). Provider auth and checkout paths are not checked.";
-export declare const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks as selected by flags)";
+export declare const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, tasks, and evals as selected by flags). Provider auth and checkout paths are not checked.";
+export declare const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks, evals as selected by flags)";
 export declare function formatValidationHuman(result: ValidationResult, options?: {
     strict?: boolean;
 }): string;

package/dist/cli/validateOutput.js

@@ -1,6 +1,6 @@
 import { effectiveSeverity } from "../config/validateCatalog.js";
-export const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, and tasks as selected by flags). Provider auth and checkout paths are not checked.";
-export const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks as selected by flags)";
+export const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, tasks, and evals as selected by flags). Provider auth and checkout paths are not checked.";
+export const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks, evals as selected by flags)";
 function effectiveSeverityRank(finding, strict) {
     return effectiveSeverity(finding, strict) === "error" ? 0 : 1;
 }

package/dist/cli.js

@@ -20,6 +20,7 @@ import { RUN_STAGE_USAGE, runRunStageCommand } from "./cli/runStageCommand.js";
 import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
 import { AGENTS_USAGE, runAgentsCommand } from "./cli/agentsCommand.js";
 import { TRIGGER_USAGE, runTriggerCommand } from "./cli/triggerCommand.js";
+import { EVAL_USAGE, runEvalCommand } from "./cli/evalCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
@@ -125,6 +126,8 @@ ${RUNS_USAGE}
 
 ${TRIGGER_USAGE}
 
+${EVAL_USAGE}
+
 ${AGENTS_USAGE}
 
 ${PROVIDERS_USAGE}
@@ -168,6 +171,7 @@ function parseArgs(argv) {
         command === "export" ||
         command === "runs" ||
         command === "trigger" ||
+        command === "eval" ||
         command === "agents" ||
         command === "skills" ||
         command === "browser") {
@@ -495,6 +499,12 @@ async function main(argv) {
                 cwd: ctx.invocationCwd,
             });
         }
+        if (parsed.command === "eval") {
+            return runEvalCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
         if (parsed.command === "agents") {
             return runAgentsCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,

package/dist/compaction/directives.d.ts

@@ -0,0 +1,18 @@
+import type { LooseMessage } from "./pin.js";
+export type DirectiveSource = "operator" | "user" | "rejection";
+/** Words from the people running the work, copied verbatim so a summary cannot reword a decision. */
+export type Directive = {
+    source: DirectiveSource;
+    text: string;
+};
+export declare const DIRECTIVE_MAX_CHARS = 600;
+export declare const USER_DIRECTIVE_MAX_CHARS = 280;
+export declare const DIRECTIVES_CARRY_MAX = 60;
+/**
+ * Operator answers, rejected emits and user messages, in order. The stage kickoff and reminder prompts are
+ * skipped: they carry no decision.
+ */
+export declare function extractDirectives(messages: readonly LooseMessage[]): Directive[];
+export declare function mergeDirectives(previous: readonly Directive[], fresh: readonly Directive[], max?: number): Directive[];
+/** Directive-like entries first (newest up to 60% of the budget, then oldest), then the rest if room remains. */
+export declare function renderDirectives(directives: readonly Directive[], maxChars: number): string;

package/dist/compaction/directives.js

@@ -0,0 +1,119 @@
+import { ASK_OPERATOR_TOOL_NAME, EMIT_STAGE_ENVELOPE_TOOL_NAME } from "../tools/stageToolNames.js";
+import { scrubSecrets } from "./scrub.js";
+export const DIRECTIVE_MAX_CHARS = 600;
+export const USER_DIRECTIVE_MAX_CHARS = 280;
+export const DIRECTIVES_CARRY_MAX = 60;
+const NOISE_USER = /^(?:Begin this stage\b|Reminder \d+ of \d+)/i;
+const FEEDBACK_RESUME_PREFIX = /^Continue this stage after feedback-loop send-back\.\s*Incorporate the operator\/source feedback below[^\n]*\n*/i;
+const OPERATOR_TOOLS = new Set([ASK_OPERATOR_TOOL_NAME]);
+const ENVELOPE_TOOLS = new Set([EMIT_STAGE_ENVELOPE_TOOL_NAME]);
+function blocksText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((b) => (b !== null && typeof b === "object" && b.type === "text" && typeof b.text === "string" ? b.text : ""))
+        .filter(Boolean)
+        .join("\n");
+}
+function clip(text, max = DIRECTIVE_MAX_CHARS) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Operator answers, rejected emits and user messages, in order. The stage kickoff and reminder prompts are
+ * skipped: they carry no decision.
+ */
+export function extractDirectives(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === "user") {
+            const text = blocksText(m.content).trim().replace(FEEDBACK_RESUME_PREFIX, "");
+            if (!text.trim() || NOISE_USER.test(text.trim()))
+                continue;
+            out.push({ source: "user", text: clip(scrubSecrets(text), USER_DIRECTIVE_MAX_CHARS) });
+        }
+        else if (m.role === "toolResult") {
+            const name = typeof m.toolName === "string" ? m.toolName : "";
+            const text = blocksText(m.content);
+            if (!text.trim())
+                continue;
+            if (OPERATOR_TOOLS.has(name))
+                out.push({ source: "operator", text: clip(scrubSecrets(text)) });
+            else if (ENVELOPE_TOOLS.has(name) && m.isError === true)
+                out.push({ source: "rejection", text: clip(scrubSecrets(text)) });
+        }
+    }
+    return out;
+}
+export function mergeDirectives(previous, fresh, max = DIRECTIVES_CARRY_MAX) {
+    const seen = new Set();
+    const merged = [];
+    for (const d of [...previous, ...fresh]) {
+        const key = `${d.source}\u0000${d.text}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(d);
+    }
+    return merged.slice(-max);
+}
+const LABEL = { operator: "Operator", user: "User", rejection: "Rejected" };
+const DIRECTIVE_WORDS = /\b(?:always|never|must|should|shall|don'?t|do not|cannot|can'?t|only|prefer|require[sd]?|approved?|rejected?|decid(?:e|ed|ion)|deadline|due|before|after|until|instead|budget|limit|forbidden|allowed|use|avoid|ensure|remember|important)\b/i;
+const SHORT_MESSAGE_CHARS = 160;
+/** Instruction-like or short messages outrank long prose, so filler cannot crowd out a rule. */
+function isDirectiveLike(d) {
+    if (d.source !== "user")
+        return true;
+    return d.text.length <= SHORT_MESSAGE_CHARS || DIRECTIVE_WORDS.test(d.text);
+}
+/** Directive-like entries first (newest up to 60% of the budget, then oldest), then the rest if room remains. */
+export function renderDirectives(directives, maxChars) {
+    if (directives.length === 0)
+        return "";
+    const header = "## Operator and user directives (verbatim, oldest first)";
+    const lineOf = (d) => `- ${LABEL[d.source]}: ${d.text}`;
+    const picked = new Set();
+    let used = header.length;
+    const take = (i, limit) => {
+        const cost = lineOf(directives[i]).length + 1;
+        if (used + cost > limit)
+            return false;
+        picked.add(i);
+        used += cost;
+        return true;
+    };
+    const primary = directives.map((d, i) => (isDirectiveLike(d) ? i : -1)).filter((i) => i >= 0);
+    const secondary = directives.map((d, i) => (isDirectiveLike(d) ? -1 : i)).filter((i) => i >= 0);
+    const newestLimit = Math.floor(maxChars * 0.6);
+    for (let k = primary.length - 1; k >= 0; k--)
+        if (!take(primary[k], newestLimit))
+            break;
+    for (const i of primary) {
+        if (picked.has(i))
+            continue;
+        if (!take(i, maxChars))
+            break;
+    }
+    for (const i of secondary) {
+        if (!take(i, maxChars))
+            break;
+    }
+    if (picked.size === 0)
+        return "";
+    const lines = [];
+    let gap = false;
+    for (let i = 0; i < directives.length; i++) {
+        if (picked.has(i)) {
+            if (gap)
+                lines.push("- (…)");
+            gap = false;
+            lines.push(lineOf(directives[i]));
+        }
+        else if (lines.length > 0)
+            gap = true;
+    }
+    const omitted = directives.length - picked.size;
+    return [header, ...lines, ...(omitted > 0 ? [`- (${omitted} omitted for space)`] : [])].join("\n");
+}

package/dist/compaction/extension.d.ts

@@ -0,0 +1,20 @@
+import { compact as piCompact, type ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type ClearingPolicy } from "./mask.js";
+export type CompactionPolicy = {
+    /** Clear stale re-fetchable tool results in the text the summarizer reads. */
+    clearInSummary?: ClearingPolicy;
+    /** Clear stale re-fetchable tool results in every request once the window is this full (0-1). */
+    preemptive?: {
+        usageFraction: number;
+        policy: ClearingPolicy;
+    };
+};
+export declare const DEFAULT_COMPACTION_POLICY: CompactionPolicy;
+type CompactFn = typeof piCompact;
+export type CompactionExtensionOptions = {
+    policy?: CompactionPolicy;
+    compact?: CompactFn;
+    onWarn?: (message: string) => void;
+};
+export declare function createCompactionExtension(options?: CompactionExtensionOptions): ExtensionFactory;
+export {};

package/dist/compaction/extension.js

@@ -0,0 +1,78 @@
+import { compact as piCompact, } from "@earendil-works/pi-coding-agent";
+import { applyClearing, planClearing } from "./mask.js";
+import { COMPACTION_FOCUS, composeCompactionSummary, readStageflowDetails, stageflowDetails, } from "./summarize.js";
+import { getWorkingStateSections } from "./workingState.js";
+export const DEFAULT_COMPACTION_POLICY = {};
+function lastCompactionDetails(branch) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const e = branch[i];
+        if (e?.type === "compaction")
+            return readStageflowDetails(e.details);
+    }
+    return undefined;
+}
+export function createCompactionExtension(options = {}) {
+    const policy = options.policy ?? DEFAULT_COMPACTION_POLICY;
+    const compact = options.compact ?? piCompact;
+    const warn = options.onWarn ?? (() => { });
+    return (pi) => {
+        pi.on("session_before_compact", async (event, rawCtx) => {
+            const ctx = rawCtx;
+            const model = ctx.model;
+            if (!model)
+                return undefined;
+            try {
+                const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+                if (!auth.ok)
+                    return undefined;
+                const { preparation } = event;
+                const previousDetails = lastCompactionDetails(event.branchEntries);
+                const historyCount = preparation.messagesToSummarize.length;
+                const composed = await composeCompactionSummary({
+                    messages: [...preparation.messagesToSummarize, ...preparation.turnPrefixMessages],
+                    ...(preparation.previousSummary !== undefined ? { previousSummary: preparation.previousSummary } : {}),
+                    ...(previousDetails ? { previousDetails } : {}),
+                    state: getWorkingStateSections(ctx.sessionManager.getEntries()),
+                    ...(policy.clearInSummary ? { clearInSummary: policy.clearInSummary } : {}),
+                    summarize: ({ messages, previousSummary }) => compact({
+                        ...preparation,
+                        messagesToSummarize: messages.slice(0, historyCount),
+                        turnPrefixMessages: messages.slice(historyCount),
+                        ...(previousSummary !== undefined ? { previousSummary } : {}),
+                    }, model, auth.apiKey, auth.headers, COMPACTION_FOCUS, event.signal, ctx.thinkingLevel, undefined, auth.env),
+                });
+                const { result, prepared } = composed;
+                return {
+                    compaction: {
+                        summary: composed.summary,
+                        firstKeptEntryId: result.firstKeptEntryId,
+                        tokensBefore: result.tokensBefore,
+                        ...(result.usage ? { usage: result.usage } : {}),
+                        details: stageflowDetails(result.details, previousDetails, prepared.pinned, prepared.cleared, prepared.directives),
+                    },
+                };
+            }
+            catch (err) {
+                if (event.signal.aborted)
+                    throw err;
+                warn(`stageflow compaction fell back to Pi default: ${err instanceof Error ? err.message : String(err)}`);
+                return undefined;
+            }
+        });
+        const preemptive = policy.preemptive;
+        if (preemptive) {
+            pi.on("context", async (event, rawCtx) => {
+                const ctx = rawCtx;
+                const usage = ctx.getContextUsage();
+                if (!usage || usage.tokens === null || usage.contextWindow <= 0)
+                    return undefined;
+                if (usage.tokens / usage.contextWindow < preemptive.usageFraction)
+                    return undefined;
+                const plan = planClearing(event.messages, preemptive.policy);
+                if (plan.cleared.length === 0)
+                    return undefined;
+                return { messages: applyClearing(event.messages, plan) };
+            });
+        }
+    };
+}

package/dist/compaction/mask.d.ts

@@ -0,0 +1,18 @@
+import type { LooseMessage } from "./pin.js";
+import type { ClearedResult } from "./types.js";
+export type ClearingPolicy = {
+    /** Never touch results at or after the Nth assistant turn from the end. */
+    keepRecentTurns: number;
+    /** Ignore results smaller than this many UTF-8 bytes. */
+    minBytes: number;
+    /** Overrides the default recover hint when it returns a non-empty string. */
+    recoverHintFor?: (message: LooseMessage) => string | undefined;
+};
+export type ClearingPlan = {
+    cleared: ClearedResult[];
+    clearIds: Set<string>;
+};
+export declare function planClearing(messages: readonly LooseMessage[], policy: ClearingPolicy): ClearingPlan;
+export declare function placeholderFor(item: ClearedResult): string;
+export declare function applyClearing<T extends LooseMessage>(messages: readonly T[], plan: ClearingPlan): T[];
+export declare function renderClearedIndex(cleared: readonly ClearedResult[], maxChars: number): string;

package/dist/compaction/mask.js

@@ -0,0 +1,155 @@
+import { scrubSecrets } from "./scrub.js";
+import { classifyForClearing } from "./toolPolicy.js";
+const PLACEHOLDER_PREFIX = "[Tool result cleared to save context:";
+const DESCRIPTOR_MAX = 100;
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function resultText(message) {
+    const content = message.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    let out = "";
+    for (const block of content) {
+        const b = record(block);
+        if (b?.type === "text" && typeof b.text === "string")
+            out += (out ? "\n" : "") + b.text;
+    }
+    return out;
+}
+function oneLine(text, max) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+function findToolCall(messages, before, toolCallId) {
+    for (let i = before - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== "assistant" || !Array.isArray(m.content))
+            continue;
+        for (const block of m.content) {
+            const b = record(block);
+            if (b?.type === "toolCall" && b.id === toolCallId)
+                return b;
+        }
+    }
+    return undefined;
+}
+function callArgs(call) {
+    return record(call?.arguments) ?? {};
+}
+function describe(toolName, args) {
+    const pathArg = typeof args.path === "string" ? args.path : typeof args.file_path === "string" ? args.file_path : undefined;
+    if (pathArg)
+        return oneLine(`${toolName} ${pathArg}`, DESCRIPTOR_MAX);
+    if (typeof args.command === "string")
+        return oneLine(`${toolName}: ${args.command}`, DESCRIPTOR_MAX);
+    if (typeof args.pattern === "string")
+        return oneLine(`${toolName} ${args.pattern}${typeof args.path === "string" ? ` in ${args.path}` : ""}`, DESCRIPTOR_MAX);
+    const keys = Object.keys(args);
+    if (keys.length === 0)
+        return toolName;
+    let json = "";
+    try {
+        json = JSON.stringify(args);
+    }
+    catch {
+        json = "";
+    }
+    return oneLine(json ? `${toolName} ${json}` : toolName, DESCRIPTOR_MAX);
+}
+function defaultHint(message, toolName, args) {
+    const spill = record(record(message.details)?.stageflowToolOutput);
+    const spillPath = typeof spill?.path === "string" ? spill.path : undefined;
+    if (spillPath)
+        return `read ${spillPath}`;
+    if (toolName === "read") {
+        const p = typeof args.path === "string" ? args.path : typeof args.file_path === "string" ? args.file_path : undefined;
+        if (p)
+            return `read ${p} (offset/limit as before)`;
+    }
+    return `re-run ${toolName} with the same arguments`;
+}
+function isPlaceholder(text) {
+    return text.startsWith(PLACEHOLDER_PREFIX);
+}
+export function planClearing(messages, policy) {
+    const cleared = [];
+    const clearIds = new Set();
+    let boundary = messages.length;
+    if (policy.keepRecentTurns > 0) {
+        let seen = 0;
+        boundary = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "assistant" && ++seen === policy.keepRecentTurns) {
+                boundary = i;
+                break;
+            }
+        }
+    }
+    for (let i = 0; i < boundary; i++) {
+        const m = messages[i];
+        if (m.role !== "toolResult")
+            continue;
+        const toolCallId = typeof m.toolCallId === "string" ? m.toolCallId : undefined;
+        const toolName = typeof m.toolName === "string" ? m.toolName : undefined;
+        if (!toolCallId || !toolName || clearIds.has(toolCallId))
+            continue;
+        if (classifyForClearing(toolName, m.isError === true, m.details) !== "clearable")
+            continue;
+        const text = resultText(m);
+        if (isPlaceholder(text))
+            continue;
+        const bytes = Buffer.byteLength(text, "utf8");
+        if (bytes < policy.minBytes)
+            continue;
+        const args = callArgs(findToolCall(messages, i, toolCallId));
+        const custom = policy.recoverHintFor?.(m);
+        cleared.push({
+            toolName,
+            toolCallId,
+            bytes,
+            descriptor: scrubSecrets(describe(toolName, args)),
+            recoverHint: scrubSecrets(custom && custom.trim().length > 0 ? oneLine(custom, 300) : defaultHint(m, toolName, args)),
+        });
+        clearIds.add(toolCallId);
+    }
+    return { cleared, clearIds };
+}
+export function placeholderFor(item) {
+    return `${PLACEHOLDER_PREFIX} ${item.descriptor}, ${item.bytes} bytes. To get it again: ${item.recoverHint}]`;
+}
+export function applyClearing(messages, plan) {
+    if (plan.clearIds.size === 0)
+        return [...messages];
+    const byId = new Map(plan.cleared.map((c) => [c.toolCallId, c]));
+    return messages.map((m) => {
+        if (m.role !== "toolResult" || typeof m.toolCallId !== "string" || !plan.clearIds.has(m.toolCallId))
+            return m;
+        const item = byId.get(m.toolCallId);
+        if (!item || isPlaceholder(resultText(m)))
+            return m;
+        return { ...m, content: [{ type: "text", text: placeholderFor(item) }] };
+    });
+}
+export function renderClearedIndex(cleared, maxChars) {
+    const title = "## Cleared tool results (re-fetch if needed)";
+    const omitted = (n) => `- (${n} more omitted)`;
+    if (cleared.length === 0)
+        return title;
+    const reserve = omitted(cleared.length).length + 1;
+    const lines = [];
+    let used = title.length;
+    for (const item of cleared) {
+        const line = `- ${item.descriptor} (${item.bytes} bytes) — ${oneLine(item.recoverHint, 200)}`;
+        if (used + line.length + 1 + reserve > maxChars)
+            break;
+        lines.push(line);
+        used += line.length + 1;
+    }
+    const out = [title, ...lines];
+    if (lines.length < cleared.length)
+        out.push(omitted(cleared.length - lines.length));
+    return out.join("\n").slice(0, Math.max(maxChars, 0));
+}

package/dist/compaction/pin.d.ts

@@ -0,0 +1,21 @@
+import type { PinnedFact } from "./types.js";
+/** Minimal message shape (Pi session messages); only role and content are read. */
+export type LooseMessage = {
+    role?: unknown;
+    content?: unknown;
+    toolName?: unknown;
+    [key: string]: unknown;
+};
+export type RankedPinnedFact = PinnedFact & {
+    count: number;
+    score: number;
+};
+export type ExtractPinnedOptions = {
+    maxFactsPerMessage?: number;
+    maxFacts?: number;
+    maxLinesPerMessage?: number;
+    maxLineChars?: number;
+    noiseThreshold?: number;
+};
+export declare function extractPinnedFacts(messages: readonly LooseMessage[], options?: ExtractPinnedOptions): RankedPinnedFact[];
+export declare function renderPinned(facts: readonly PinnedFact[], maxChars: number): string;