stageflow 0.42.0 → 0.46.0

package/dist/agents/authorSessionStore.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { globalStageflowHome } from "../project/globalHome.js";
 function guardSessionId(sessionId) {
@@ -114,11 +114,26 @@ export function saveAuthorSession(record, storeRoot) {
     writeRecord(next, storeRoot);
     return next;
 }
+/** Removes the session directory. Returns false when the id is invalid or missing. */
+export function deleteAuthorSession(sessionId, storeRoot) {
+    let file;
+    try {
+        file = authorSessionFilePath(sessionId, storeRoot);
+    }
+    catch {
+        return false;
+    }
+    const dir = path.dirname(file);
+    if (!existsSync(dir))
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}
 function draftTitle(draft) {
     const name = typeof draft.name === "string" ? draft.name.trim() : "";
     return name || "Untitled draft";
 }
-function draftHasWork(record) {
+export function draftHasWork(record) {
     if (record.transcript.length > 0)
         return true;
     for (const key of ["name", "instructions", "description"]) {

package/dist/agents/evalGate.js

@@ -9,6 +9,7 @@ const ALWAYS_BLOCKED = new Set([
     "stageflow.agent_chat",
     "stageflow.fire_trigger",
     "stageflow.sort_eval_failures",
+    "stageflow.calibrate_eval_grader",
     "stageflow.cancel_eval_run",
 ]);
 const BLOCKED_UNLESS_REAL = new Set(["stageflow.probe_project_mcp"]);

package/dist/agents/hostContext.d.ts

@@ -53,5 +53,5 @@ export declare function createAgentHostContext(options: {
     /** Host services the Stageflow tools need; agent services are added here. Without it agents get no Stageflow tools. */
     /** Hold streams open to AgentMail and iMessage for agents linked to them. Only a running Host does this. */
     listenOnChannels?: boolean;
-    toolkitDeps?: Pick<McpToolDeps, "manager" | "store" | "agentDir" | "providerAuthContext" | "projectRoot" | "providerBoot">;
+    toolkitDeps?: Pick<McpToolDeps, "manager" | "store" | "agentDir" | "providerAuthContext" | "projectRoot" | "providerBoot" | "channels" | "memories" | "evalRunManager">;
 }): AgentHostContext;

package/dist/agents/runtime/piRuntime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { type AgentDefinition } from "../../config/loadAgent.js";
 import { type StageMemory } from "../../memory/access.js";
 import { type SandboxRunner } from "../sandbox.js";
@@ -38,6 +38,8 @@ export type OpenSessionInput = {
     /** Stageflow tools this agent is granted. */
     stageflowTools?: ToolkitTool[];
     memory?: StageMemory;
+    /** Defaults to true; one-shot judge sessions have no use for it. */
+    workingState?: boolean;
     hooks: () => TurnHooks | undefined;
 };
 export type OpenedSession = {
@@ -48,5 +50,7 @@ export type OpenedSession = {
     toolNames: string[];
     shutdown(): Promise<void>;
 };
+/** Runs the agent tool gate before every call, except for tools the session wiring marks as internal. */
+export declare function createAgentGateExtension(gate: OpenSessionInput["gate"], isInternalTool: (toolName: string) => boolean): ExtensionFactory;
 export declare const DEFAULT_IDLE_RELEASE_MS: number;
 export declare function createPiAgentRuntime(options: PiRuntimeOptions): ConversationBackend;

package/dist/agents/runtime/piRuntime.js

@@ -1,11 +1,13 @@
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { defineTool, ModelRuntime, resolveCliModel, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { collectMcpExtensionToolNames, mcpToolMetadataMissing } from "../../agent/piAdapter.js";
 import { attachIsolatedMcp } from "../../agent/piIsolatedMcp.js";
 import { warmIsolatedMcpMetadata } from "../../agent/piIsolatedMcpProbe.js";
 import { createPiAgentSession, createSealedResourceLoader } from "../../agent/piSessionFactory.js";
+import { createPiSettingsManager } from "../../agent/piSettings.js";
+import { createSessionContextWiring } from "../../compaction/sessionWiring.js";
 import { bindCursorApiKey, isCursorModelRef } from "../../agent/cursorProvider.js";
 import { findProviderSupport } from "../../agent/providerSupport.js";
 import { grantedBuiltinTools } from "../../config/loadAgent.js";
@@ -19,11 +21,22 @@ import { isUsableAuthFile, resolveCredentialBinding } from "../../runtime/creden
 import { getModelCatalog } from "../../models/catalog.js";
 import { AgentError } from "../errors.js";
 import { MEMORY_STORE_BASH_DENIED, memoryStorePathInCommand } from "../../memory/bashDeny.js";
+import { compactionUsageCost } from "../../agent/compactionEvents.js";
 import { memoryHome } from "../../memory/host.js";
 import { forbiddenWriteTarget } from "../policy.js";
 import { prepareExecutionLaunch } from "../sandbox.js";
 import { grantedStageflowTools, isOperatorOnlyTool } from "../../toolkit/index.js";
 import { grantIdForPiTool, STAGEFLOW_PI_PREFIX } from "./types.js";
+/** Runs the agent tool gate before every call, except for tools the session wiring marks as internal. */
+export function createAgentGateExtension(gate, isInternalTool) {
+    return (pi) => {
+        pi.on("tool_call", async (event) => {
+            if (isInternalTool(event.toolName))
+                return undefined;
+            return gate({ toolCallId: event.toolCallId, toolName: event.toolName, input: event.input });
+        });
+    };
+}
 function piToolNames(definition) {
     return grantedBuiltinTools(definition);
 }
@@ -84,7 +97,7 @@ async function openPiSession(options, input) {
     try {
         await mkdir(options.agentDir, { recursive: true });
         const modelRuntime = await ModelRuntime.create({ authPath, modelsPath: path.join(path.dirname(authPath), "models.json") });
-        const settingsManager = SettingsManager.inMemory({ compaction: { enabled: true } });
+        const settingsManager = createPiSettingsManager();
         const mcpServers = Object.keys(definition.tools.mcp);
         const resolvedMcp = mcpServers.length > 0
             ? await resolveStageMcpServers({ projectRoot, allowlist: mcpServers, env: {}, scope: { kind: "agent" } })
@@ -97,18 +110,18 @@ async function openPiSession(options, input) {
                 throw new AgentError("agent.backend_unavailable", `Skill "${name}" is not installed`);
             skillPaths.push(skill.filePath);
         }
-        const gateExtension = (pi) => {
-            pi.on("tool_call", async (event) => {
-                const outcome = await input.gate({ toolCallId: event.toolCallId, toolName: event.toolName, input: event.input });
-                return outcome;
-            });
-        };
-        const extensionFactories = [{ name: "stageflow-agent-gate", factory: gateExtension }, ...(attached.extensionFactories ?? [])];
+        const contextWiring = createSessionContextWiring({ workingState: input.workingState !== false });
+        const gateExtension = createAgentGateExtension(input.gate, contextWiring.isInternalTool);
+        const extensionFactories = [
+            { name: "stageflow-agent-gate", factory: gateExtension },
+            ...contextWiring.extensions,
+            ...(attached.extensionFactories ?? []),
+        ];
         const loader = createSealedResourceLoader({
             cwd: projectRoot,
             agentDir: options.agentDir,
             settingsManager,
-            systemPrompt: input.systemPrompt,
+            systemPrompt: contextWiring.guidance ? `${input.systemPrompt}\n\n${contextWiring.guidance}` : input.systemPrompt,
             additionalExtensionPaths: extensionPaths,
             ...(skillPaths.length > 0 ? { additionalSkillPaths: skillPaths } : {}),
             extensionFactories,
@@ -127,6 +140,7 @@ async function openPiSession(options, input) {
             throw new AgentError("agent.backend_unavailable", `Failed to load extension(s): ${errors.map((e) => `${e.path}: ${e.error}`).join("; ")}`);
         }
         const toolNames = [...input.toolNames];
+        toolNames.push(...contextWiring.toolNames);
         if (attached.extensionFactories) {
             const mcp = collectMcpExtensionToolNames(loader);
             if (!mcp.ok)
@@ -149,6 +163,7 @@ async function openPiSession(options, input) {
                     label: `Ask ${agentId}`,
                     description: `Hand a task to the "${agentId}" agent and get its reply.`,
                     parameters: Type.Object({ message: Type.String({ description: "The task or question for the agent." }) }),
+                    constrainedSampling: { type: "json_schema", strict: "prefer" },
                     execute: async (callId, args) => {
                         const reply = await input.delegateTool(agentId, args.message, callId);
                         return { content: [{ type: "text", text: reply }], details: {} };
@@ -159,7 +174,10 @@ async function openPiSession(options, input) {
         }
         if (input.memory) {
             for (const definition of memorySession(input.memory).tools) {
-                customTools.push(defineTool(definition));
+                customTools.push(defineTool({
+                    ...definition,
+                    constrainedSampling: { type: "json_schema", strict: "prefer" },
+                }));
                 toolNames.push(definition.name);
             }
         }
@@ -169,6 +187,7 @@ async function openPiSession(options, input) {
                 label: tool.name,
                 description: tool.description,
                 parameters: Type.Unsafe(tool.parameters),
+                constrainedSampling: { type: "json_schema", strict: "prefer" },
                 execute: async (_id, args, signal) => {
                     const result = await tool.run(args ?? {}, { signal: signal ?? new AbortController().signal, caller: { agentId: definition.id, definition } });
                     if (!result.ok)
@@ -334,6 +353,7 @@ export function createPiAgentRuntime(options) {
             let text = "";
             const usage = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
             let startedAt = new Date();
+            let compactionStartedAt;
             const calls = new Map();
             // A model call that goes quiet (provider queue, dropped connection) must not hold the session forever.
             // Waiting on a person (approval), a running tool or a sub-agent is not a stall.
@@ -370,7 +390,20 @@ export function createPiAgentRuntime(options) {
             const unsubscribe = session.subscribe((event) => {
                 arm();
                 const e = event;
-                if (e.type === "message_start" && e.message?.role === "assistant")
+                if (e.type === "compaction_start")
+                    compactionStartedAt = new Date();
+                else if (e.type === "compaction_end") {
+                    const end = event;
+                    const info = compactionUsageCost(end);
+                    usage.inputTokens += info.inputTokens;
+                    usage.outputTokens += info.outputTokens;
+                    usage.costUsd += info.costUsd;
+                    const model = session.model?.id;
+                    if (end.result?.usage) {
+                        input.hooks.modelFinished({ startedAt: compactionStartedAt ?? new Date(), endedAt: new Date(), ...info, ...(model ? { model } : {}) });
+                    }
+                }
+                else if (e.type === "message_start" && e.message?.role === "assistant")
                     startedAt = new Date();
                 else if (e.type === "message_update" && e.assistantMessageEvent?.type === "text_delta" && typeof e.assistantMessageEvent.delta === "string") {
                     text += e.assistantMessageEvent.delta;
@@ -435,6 +468,7 @@ export function createPiAgentRuntime(options) {
                 definition: { ...input.definition, tools: { ...input.definition.tools, builtin: [], builtin_tools: [], mcp: {}, skills: [] }, sub_agents: [] },
                 systemPrompt: input.systemPrompt ?? "You are a strict evaluator. Answer only with the requested number.",
                 toolNames: [],
+                workingState: false,
                 gate: async () => ({ block: true, reason: "No tools" }),
                 hooks: () => undefined,
             });

package/dist/agents/service.js

@@ -576,8 +576,9 @@ export class AgentService {
                     return false;
                 throw error;
             });
-            if (onDisk || (existing && !existing.archived))
-                throw new AgentError("agent.exists");
+            if (onDisk || (existing && !existing.archived)) {
+                throw new AgentError("agent.exists", `An agent with id "${definition.id}" already exists`);
+            }
             // A new agent always starts disabled (R1); enabling is its own revision.
             await this.writeRevision(projectRoot, { ...definition, enabled: false }, actor, "Created");
         });

package/dist/agents/sessions.js

@@ -5,6 +5,8 @@ import { EVAL_SESSION_SOURCE, isEvalSession } from "./evalSession.js";
 import { guardedStream } from "./guardrails.js";
 import { fitHistory } from "./historyFit.js";
 import { isToolGranted, requiresAskFirst } from "./policy.js";
+import { scrubSecrets } from "../compaction/scrub.js";
+import { WORKING_STATE_TOOL_NAME } from "../compaction/types.js";
 import { prepareSpan } from "./trace.js";
 const GROUNDEDNESS_PROMPT = (reply, evidence) => [
     "Rate how well the ANSWER is supported by the TOOL OUTPUTS, from 0 (unsupported or contradicted) to 1 (fully supported).",
@@ -202,7 +204,7 @@ export class AgentConversation {
                         ...(isEvalSession(active.session) ? { "gen_ai.tool.call.id": call.id } : {}),
                         ...(childSessionOf(call) ? { "stageflow.sub_agent.session_id": childSessionOf(call) } : {}),
                     },
-                    input: toJson(call.input),
+                    input: call.tool === WORKING_STATE_TOOL_NAME ? scrubSecrets(toJson(call.input)) : toJson(call.input),
                     output: result.output,
                 });
             },

package/dist/cli/evalCommand.d.ts

@@ -1,6 +1,6 @@
 import { type RunNpm } from "../evals/engine/promptfoo/install.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
-export declare const EVAL_USAGE = "Usage:\n  sf eval list [--json]\n  sf eval show <id|path> [--json]\n  sf eval validate [<id|path>] [--json] [--strict]\n  sf eval run <id|path> [--repeats <n>] [--judge <model>] [--model <id>] [--user-model <model>] [--allow-real-tools] [--max-cost <usd>] [--case <id> ...] [--tag <tag> ...] [--label <text>] [--no-wait] [--json]\n  sf eval runs [<evalId>] [--json]\n  sf eval runs show <evalRunId> [--json]\n  sf eval runs cancel <evalRunId>\n  sf eval runs delete <evalRunId>\n  sf eval sort <evalRunId> [--classifier auto|jev|judge] [--limit <n>] [--resort] [--json]\n  sf eval suggestions <evalRunId> [--status pending|accepted|dismissed] [--json]\n  sf eval compare <evalRunIdA> <evalRunIdB> [--json]\n  sf eval datasets [--json]\n  sf eval engine status [--json]\n  sf eval engine install\n\n  Agent evals: --model overrides the agent's model, --user-model the model that plays the user. An eval whose\n  conversation.tools is real also needs --allow-real-tools.\n\n  Every subcommand also accepts --project-root <id-or-path>.";
+export declare const EVAL_USAGE = "Usage:\n  sf eval list [--json]\n  sf eval show <id|path> [--json]\n  sf eval validate [<id|path>] [--json] [--strict]\n  sf eval run <id|path> [--repeats <n>] [--judge <model>] [--model <id>] [--user-model <model>] [--allow-real-tools] [--max-cost <usd>] [--case <id> ...] [--tag <tag> ...] [--label <text>] [--no-wait] [--json]\n  sf eval runs [<evalId>] [--json]\n  sf eval runs show <evalRunId> [--json]\n  sf eval runs cancel <evalRunId>\n  sf eval runs delete <evalRunId>\n  sf eval sort <evalRunId> [--classifier auto|jev|judge] [--limit <n>] [--resort] [--json]\n  sf eval calibrate <evalId> <graderId> [--split all|dev|held_out] [--max-cost <usd>] [--stability] [--json]\n  sf eval suggestions <evalRunId> [--status pending|accepted|dismissed] [--json]\n  sf eval compare <evalRunIdA> <evalRunIdB> [--json]\n  sf eval datasets [--json]\n  sf eval engine status [--json]\n  sf eval engine install\n\n  Agent evals: --model overrides the agent's model, --user-model the model that plays the user. An eval whose\n  conversation.tools is real also needs --allow-real-tools.\n\n  Every subcommand also accepts --project-root <id-or-path>.";
 export type EvalCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/evalCommand.js

@@ -9,7 +9,7 @@ import { installPromptfoo } from "../evals/engine/promptfoo/install.js";
 import { engineStatus } from "../evals/engine/promptfoo/status.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
-import { httpCancelEvalRun, httpCompareEvalRuns, httpDeleteEvalRun, httpEnsureProject, httpGetEval, httpGetEvalRun, httpListDatasets, httpListEvalRuns, httpListEvalSuggestions, httpSortEvalFailures, httpListEvals, httpStartEvalRun, } from "./hostClient.js";
+import { httpCancelEvalRun, httpCompareEvalRuns, httpDeleteEvalRun, httpEnsureProject, httpGetEval, httpGetEvalRun, httpListDatasets, httpListEvalRuns, httpListEvalSuggestions, httpCalibrateEvalGrader, httpSortEvalFailures, httpListEvals, httpStartEvalRun, } from "./hostClient.js";
 import { resolveCliProjectRootLocal } from "./resolveCliProjectRoot.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const EVAL_USAGE = `Usage:
@@ -22,6 +22,7 @@ export const EVAL_USAGE = `Usage:
   sf eval runs cancel <evalRunId>
   sf eval runs delete <evalRunId>
   sf eval sort <evalRunId> [--classifier auto|jev|judge] [--limit <n>] [--resort] [--json]
+  sf eval calibrate <evalId> <graderId> [--split all|dev|held_out] [--max-cost <usd>] [--stability] [--json]
   sf eval suggestions <evalRunId> [--status pending|accepted|dismissed] [--json]
   sf eval compare <evalRunIdA> <evalRunIdB> [--json]
   sf eval datasets [--json]
@@ -61,6 +62,7 @@ const FLAGS = {
     runs: {},
     sort: { "--classifier": { value: true }, "--limit": { value: true }, "--resort": {} },
     suggestions: { "--status": { value: true } },
+    calibrate: { "--split": { value: true }, "--max-cost": { value: true }, "--stability": {} },
     compare: {},
     datasets: {},
     engine: {},
@@ -76,6 +78,7 @@ function parseArgs(command, rest) {
         noWait: false,
         allowRealTools: false,
         resort: false,
+        stability: false,
         cases: [],
         tags: [],
         positionals: [],
@@ -150,6 +153,15 @@ function parseArgs(command, rest) {
             case "--resort":
                 parsed.resort = true;
                 break;
+            case "--stability":
+                parsed.stability = true;
+                break;
+            case "--split":
+                if (value !== "all" && value !== "dev" && value !== "held_out") {
+                    throw new UsageError("--split must be all, dev or held_out");
+                }
+                parsed.split = value;
+                break;
             case "--status":
                 if (value !== "pending" && value !== "accepted" && value !== "dismissed") {
                     throw new UsageError("--status must be pending, accepted or dismissed");
@@ -404,7 +416,9 @@ export async function runEvalCommand(args, options = {}) {
                     ? expectArgs(2, 2, "<evalRunIdA> <evalRunIdB>")
                     : command === "sort" || command === "suggestions"
                         ? expectArgs(1, 1, "<evalRunId>")
-                        : null;
+                        : command === "calibrate"
+                            ? expectArgs(2, 2, "<evalId> <graderId>")
+                            : null;
     if (argError)
         return usageError(argError);
     let runsSub;
@@ -554,6 +568,29 @@ export async function runEvalCommand(args, options = {}) {
                 out.log(`Review and accept in the console, or POST /api/eval-runs/${positionals[0]}/failures/suggestions/accept`);
             });
         }
+        case "calibrate": {
+            const result = await httpCalibrateEvalGrader(base, positionals[0], positionals[1], {
+                project_root: wireRoot,
+                ...(parsed.split !== undefined ? { split: parsed.split } : {}),
+                ...(parsed.maxCost !== undefined ? { max_cost_usd: parsed.maxCost } : {}),
+                ...(parsed.stability ? { stability: true } : {}),
+            });
+            return show(result, (b) => {
+                const st = b.stats;
+                const num = (v) => (typeof v === "number" ? v.toFixed(2) : "n/a");
+                out.log(`${b.grader_id} (${b.judge}): ${st.n} labels, agreement ${num(st.agreement)}, kappa ${num(st.cohen_kappa)}, pass recall ${num(st.tpr)}, fail recall ${num(st.tnr)}; cost ${usd(b.cost_usd)}`);
+                const cm = st.confusion;
+                out.log(`judge pass / human pass ${cm.tp}\tjudge pass / human fail ${cm.fp}\tjudge fail / human fail ${cm.tn}\tjudge fail / human pass ${cm.fn}`);
+                if (st.stability) {
+                    out.log(`stability over ${st.stability.k} judge calls per output: ${st.stability.unstable} of ${st.stability.n} outputs split (flip rate ${num(st.stability.flip_rate)})`);
+                }
+                for (const w of st.warnings)
+                    out.log(`warning: ${w}`);
+                for (const d of b.disagreements) {
+                    out.log(`${d.case_id}#${d.repeat_index}\thuman ${d.label}\tjudge ${d.judge}\t${d.reason ?? ""}`);
+                }
+            });
+        }
         case "suggestions":
             return show(await httpListEvalSuggestions(base, positionals[0], parsed.status), (b) => {
                 for (const s of b.items)

package/dist/cli/hostClient.d.ts

@@ -119,6 +119,12 @@ export declare function httpSortEvalFailures(base: string, evalRunId: string, in
     only_unsorted?: boolean;
     limit?: number;
 }): Promise<HttpEvalResult<Record<string, any>>>;
+export declare function httpCalibrateEvalGrader(base: string, evalId: string, graderId: string, input: {
+    project_root?: string;
+    split?: "all" | "dev" | "held_out";
+    max_cost_usd?: number;
+    stability?: boolean;
+}): 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>;

package/dist/cli/hostClient.js

@@ -342,6 +342,10 @@ 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 async function httpCalibrateEvalGrader(base, evalId, graderId, input) {
+    const { status, body } = await postJson(base, `/api/evals/${enc(evalId)}/graders/${enc(graderId)}/calibrate`, 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 })}`);
 }

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;