profclaw 2.3.0 → 2.4.0

package/dist/agents/executor-runner.js

@@ -0,0 +1,303 @@
+/**
+ * ExecutorRunner: the built-in model-backed AgentRunner for verified runs.
+ *
+ * Adapts AgentExecutor to the AgentRunner seam used by runVerifiedGoal:
+ * - runs the executor with the run's worktree as the only place it can touch
+ *   (worktree-confined tools plus the PermissionManager, never push or PR);
+ * - feeds it the goal plus the previous attempt's trimmed verifier output;
+ * - reports tokens, dollars and cache hit rate so the loop's budget guard works,
+ *   and cancels an attempt mid-flight when the remaining budget is spent;
+ * - cascades models: starts on the smart router's cheap pick and moves one
+ *   tier up after N consecutive verifier failures (N is configurable).
+ *
+ * AgentExecutor is used as-is. Cache usage is read from its public
+ * `step:complete` event, so the executor internals are not touched.
+ */
+import { randomUUID } from 'node:crypto';
+import { AgentExecutor } from './executor.js';
+import { createRunPermissionManager, createWorktreeToolset } from './worktree-tools.js';
+import { classifyComplexity, selectModel } from '../providers/smart-router.js';
+import { getModelInfo, resolveModelAlias } from '../providers/core/models.js';
+import { extractCacheUsage, getCacheConfigForModel } from '../providers/prompt-cache.js';
+const TIER_ORDER = ['trivial', 'standard', 'complex'];
+function toChoice(spec, tier) {
+    const resolved = resolveModelAlias(spec);
+    const modelId = resolved?.model ?? spec;
+    const info = getModelInfo(modelId);
+    const provider = resolved?.provider ?? info?.provider;
+    if (!provider) {
+        throw new Error(`Unknown model "${spec}". Use an alias, a catalog id, or provider/model.`);
+    }
+    return {
+        provider,
+        model: modelId,
+        costPer1MInput: info?.costPer1MInput ?? 0,
+        costPer1MOutput: info?.costPer1MOutput ?? 0,
+        tier,
+    };
+}
+/**
+ * Build the ordered list of models an attempt series may use.
+ *
+ * `modelSpec` (comma separated) pins an explicit ladder, cheapest first.
+ * Without it the smart router classifies the goal, picks the cheap model for
+ * that tier, and appends the picks for each higher tier (deduplicated).
+ */
+export function buildModelLadder(goal, availableProviders, modelSpec) {
+    const specs = (modelSpec ?? '').split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    if (specs.length > 0)
+        return specs.map((s) => toChoice(s, 'pinned'));
+    if (availableProviders.size === 0) {
+        throw new Error('No model provider is configured. Set a provider API key or pass --model.');
+    }
+    const complexity = classifyComplexity(goal, { hasCodeContext: true, hasToolUse: true });
+    const startIndex = TIER_ORDER.indexOf(complexity.tier);
+    const ladder = [];
+    for (const tier of TIER_ORDER.slice(startIndex)) {
+        const picked = selectModel({ ...complexity, tier }, availableProviders).selectedModel;
+        if (!picked.supportsTools)
+            continue;
+        if (ladder.some((c) => c.model === picked.id))
+            continue;
+        ladder.push({
+            provider: picked.provider,
+            model: picked.id,
+            costPer1MInput: picked.costPer1MInput,
+            costPer1MOutput: picked.costPer1MOutput,
+            tier,
+        });
+    }
+    if (ladder.length === 0)
+        throw new Error('The router found no tool-capable model. Pass --model.');
+    return ladder;
+}
+/** Dollar cost with cache reads and writes priced by their multipliers. */
+export function computeCostUsd(choice, usage, cache) {
+    const read = Math.min(usage.cacheReadTokens, usage.inputTokens);
+    const write = Math.min(usage.cacheWriteTokens, usage.inputTokens - read);
+    const fresh = usage.inputTokens - read - write;
+    const inputUnits = fresh + read * cache.readMultiplier + write * cache.writeMultiplier;
+    return (inputUnits * choice.costPer1MInput + usage.outputTokens * choice.costPer1MOutput) / 1_000_000;
+}
+export const DEFAULT_RUNNER_CONFIG = {
+    escalateAfter: 2,
+    maxStepsPerAttempt: 40,
+    attemptTokenBudget: 200_000,
+    commandTimeoutMs: 120_000,
+    maxToolOutputChars: 8_000,
+};
+function envNumber(env, key) {
+    const raw = env[key];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/** Precedence: explicit flag > PROFCLAW_RUN_* env var > default. */
+export function resolveRunnerConfig(flags, env = process.env) {
+    const pick = (key, envKey) => flags[key] ?? envNumber(env, envKey) ?? DEFAULT_RUNNER_CONFIG[key];
+    const cfg = {
+        escalateAfter: Math.floor(pick('escalateAfter', 'PROFCLAW_RUN_ESCALATE_AFTER')),
+        maxStepsPerAttempt: Math.max(1, Math.floor(pick('maxStepsPerAttempt', 'PROFCLAW_RUN_MAX_STEPS'))),
+        attemptTokenBudget: Math.max(1, Math.floor(pick('attemptTokenBudget', 'PROFCLAW_RUN_ATTEMPT_TOKENS'))),
+        commandTimeoutMs: Math.max(1, pick('commandTimeoutMs', 'PROFCLAW_RUN_COMMAND_TIMEOUT_MS')),
+        maxToolOutputChars: Math.max(1, Math.floor(pick('maxToolOutputChars', 'PROFCLAW_RUN_TOOL_OUTPUT_CHARS'))),
+    };
+    return cfg;
+}
+const SYSTEM_PROMPT = [
+    'You are a coding agent working toward a goal inside an isolated git worktree.',
+    'Use the tools to read and edit files and to run commands. Every path is relative to the working directory and you cannot leave it.',
+    'Run the verify command yourself to check your work. The run only counts as done when that command exits 0.',
+    'Never push to a remote, never open pull requests, never touch git configuration.',
+    'When finished, call complete_task with a short summary.',
+].join('\n');
+export function buildAgentMessages(input) {
+    const lines = [
+        `Goal: ${input.goal}`,
+        `Verify command (must exit 0): ${input.verifyCommand}`,
+        `Attempt ${input.attempt}.`,
+    ];
+    if (input.feedback) {
+        lines.push('', 'The previous attempt did not pass verification. Trimmed verifier output:', input.feedback);
+    }
+    return [
+        { role: 'system', content: SYSTEM_PROMPT },
+        { role: 'user', content: lines.join('\n') },
+    ];
+}
+function stepUsage(result) {
+    return typeof result === 'object' && result !== null ? result['usage'] : undefined;
+}
+/** Tool results that report failure as data ({ success: false } or { error }) rather than throwing. */
+function isFailedToolResult(out) {
+    if (typeof out !== 'object' || out === null)
+        return false;
+    const rec = out;
+    return rec['success'] === false || rec['ok'] === false || (typeof rec['error'] === 'string' && rec['error'] !== '');
+}
+export class ExecutorRunner {
+    options;
+    config;
+    env;
+    permissions;
+    tierIndex = 0;
+    failuresOnTier = 0;
+    spentTokens = 0;
+    spentUsd = 0;
+    constructor(options) {
+        this.options = options;
+        if (options.ladder.length === 0)
+            throw new Error('ExecutorRunner needs at least one model');
+        this.config = resolveRunnerConfig(options.config ?? {}, options.env);
+        this.env = options.env;
+        this.permissions = options.permissions ?? createRunPermissionManager();
+    }
+    /** Model the next attempt would use (for tests and diagnostics). */
+    get currentChoice() {
+        return this.options.ladder[this.tierIndex];
+    }
+    /**
+     * A call that arrives with feedback means the previous attempt failed
+     * verification (or crashed). After `escalateAfter` such failures in a row on
+     * the same model, move to the next tier up, if there is one.
+     */
+    selectChoice(input) {
+        let escalated = false;
+        if (input.feedback !== undefined)
+            this.failuresOnTier++;
+        const { escalateAfter } = this.config;
+        if (escalateAfter > 0 &&
+            this.failuresOnTier >= escalateAfter &&
+            this.tierIndex < this.options.ladder.length - 1) {
+            this.tierIndex++;
+            this.failuresOnTier = 0;
+            escalated = true;
+        }
+        return { choice: this.currentChoice, escalated };
+    }
+    async runAttempt(input) {
+        const { choice, escalated } = this.selectChoice(input);
+        this.options.onEvent?.({ type: 'model_selected', attempt: input.attempt, choice, escalated });
+        const tokenCap = this.options.maxTokens ?? 0;
+        const costCap = this.options.maxCostUsd ?? 0;
+        const tokensLeft = tokenCap > 0 ? Math.max(1, tokenCap - this.spentTokens) : Number.POSITIVE_INFINITY;
+        const costLeft = costCap > 0 ? costCap - this.spentUsd : Number.POSITIVE_INFINITY;
+        const attemptBudget = Math.floor(Math.min(this.config.attemptTokenBudget, tokensLeft));
+        const toolset = createWorktreeToolset({
+            workdir: input.workdir,
+            permissions: this.permissions,
+            commandTimeoutMs: this.config.commandTimeoutMs,
+            maxOutputChars: this.config.maxToolOutputChars,
+        });
+        const sessionId = `verified-run-${randomUUID().slice(0, 8)}-a${input.attempt}`;
+        const loop = (this.options.createLoop ?? defaultCreateLoop)({
+            sessionId,
+            goal: input.goal,
+            config: {
+                maxSteps: this.config.maxStepsPerAttempt,
+                maxBudget: attemptBudget,
+                securityMode: 'sandbox',
+                // Tool timeout in the executor must outlast the shell timeout.
+                stepTimeoutMs: this.config.commandTimeoutMs + 5_000,
+                enableStreaming: false,
+            },
+        });
+        let cacheRead = 0;
+        let cacheWrite = 0;
+        let budgetStopped = false;
+        const usageNow = (state) => ({
+            inputTokens: state.inputTokensUsed,
+            outputTokens: state.outputTokensUsed,
+            cacheReadTokens: cacheRead,
+            cacheWriteTokens: cacheWrite,
+        });
+        loop.on('step:complete', (state, result) => {
+            const usage = extractCacheUsage(stepUsage(result));
+            cacheRead += usage.cacheReadTokens;
+            cacheWrite += usage.cacheWriteTokens;
+            if (computeCostUsd(choice, usageNow(state), getCacheConfigForModel(choice.model, this.env)) >= costLeft && !budgetStopped) {
+                budgetStopped = true;
+                loop.cancel();
+            }
+        });
+        input.signal?.addEventListener('abort', () => loop.cancel(), { once: true });
+        let failure;
+        let finalState;
+        try {
+            const model = await this.options.createModel(choice);
+            const onToolCall = this.options.onToolCall;
+            const execute = onToolCall
+                ? async (name, args) => {
+                    const startedAt = Date.now();
+                    try {
+                        const out = await toolset.execute(name, args);
+                        onToolCall({ attempt: input.attempt, name, args, durationMs: Date.now() - startedAt, ok: !isFailedToolResult(out) });
+                        return out;
+                    }
+                    catch (error) {
+                        onToolCall({ attempt: input.attempt, name, args, durationMs: Date.now() - startedAt, ok: false });
+                        throw error;
+                    }
+                }
+                : toolset.execute;
+            finalState = await loop.run(model, buildAgentMessages(input), toolset.tools, execute, choice.provider);
+        }
+        catch (error) {
+            failure = error instanceof Error ? error.message : String(error);
+            finalState = loop.getState();
+        }
+        finally {
+            await toolset.dispose();
+        }
+        const inputTokens = finalState.inputTokensUsed;
+        const outputTokens = finalState.outputTokensUsed;
+        const tokens = inputTokens + outputTokens > 0 ? inputTokens + outputTokens : finalState.usedBudget;
+        const costUsd = computeCostUsd(choice, usageNow(finalState), getCacheConfigForModel(choice.model, this.env));
+        this.spentTokens += tokens;
+        this.spentUsd += costUsd;
+        // A failure before any tokens were spent is a setup problem (auth, model
+        // unavailable): surface it so the loop records an agent error. After real
+        // spend, report it in the summary and let the verifier judge the worktree.
+        if (failure !== undefined && tokens === 0)
+            throw new Error(failure);
+        const summary = this.summarize(finalState, failure, budgetStopped);
+        const cacheHitRate = inputTokens > 0 && cacheRead + cacheWrite > 0 ? cacheRead / inputTokens : undefined;
+        return {
+            summary,
+            tokensUsed: tokens,
+            costUsd,
+            model: choice.model,
+            cacheHitRate,
+            usage: { inputTokens, outputTokens, cacheReadTokens: cacheRead, cacheWriteTokens: cacheWrite },
+        };
+    }
+    summarize(state, failure, budgetStopped) {
+        if (budgetStopped)
+            return 'Stopped mid-attempt: the run cost budget was reached.';
+        if (failure !== undefined)
+            return `Agent error after partial work: ${failure}`;
+        return (state.finalResult?.summary ?? 'Agent finished without a summary.').slice(0, 500);
+    }
+}
+function defaultCreateLoop(args) {
+    return new AgentExecutor(args.sessionId, args.sessionId, args.goal, args.config);
+}
+/** Build a runner on the configured providers via the smart router. */
+export async function createDefaultExecutorRunner(args) {
+    const { aiProvider } = await import('../providers/ai-sdk.js');
+    const env = args.env ?? process.env;
+    const modelSpec = args.model ?? (env['PROFCLAW_RUN_MODEL']?.trim() || undefined);
+    const ladder = buildModelLadder(args.goal, new Set(aiProvider.getConfiguredProviders()), modelSpec);
+    return new ExecutorRunner({
+        ladder,
+        createModel: (choice) => aiProvider.getModel(choice.provider, choice.model),
+        config: args.config,
+        env,
+        maxTokens: args.maxTokens,
+        maxCostUsd: args.maxCostUsd,
+        onEvent: args.onEvent,
+        onToolCall: args.onToolCall,
+    });
+}
+//# sourceMappingURL=executor-runner.js.map

package/dist/agents/executor.d.ts

@@ -91,6 +91,8 @@ export declare class AgentExecutor extends EventEmitter<AgentEvents> {
      */
     private injectFailureHint;
     private extractContext;
+    /** Route one step's usage (with cache tokens) into the cost tracker. */
+    private trackStepUsage;
     private finalize;
     private collectArtifacts;
     private collectNextSteps;

package/dist/agents/executor.js

@@ -13,6 +13,8 @@ import { EFFORT_BUDGET_MAP } from "./types.js";
 import { defaultStopConditions, taskCompleted } from "./stop-conditions.js";
 import { ToolCircuitBreaker } from "./circuit-breaker.js";
 import { logger } from "../utils/logger.js";
+import { applyAnthropicMessageCache, applyAnthropicToolCache, extractCacheUsage, } from "../providers/prompt-cache.js";
+import { trackChatUsage } from "../costs/token-tracker.js";
 import { ResultStore } from "./result-store.js";
 import { getAgentSummaryTracker } from "./agent-summary.js";
 import { getHookRegistry } from "../hooks/registry.js";
@@ -251,8 +253,8 @@ export class AgentExecutor extends EventEmitter {
                 const providerOptions = this.buildProviderOptions(providerHint);
                 const result = await generateText({
                     model,
-                    messages,
-                    tools: hasTools ? executableTools : undefined,
+                    messages: applyAnthropicMessageCache(messages, providerHint ?? ''),
+                    tools: hasTools ? applyAnthropicToolCache(executableTools, providerHint ?? '') : undefined,
                     ...(providerOptions ? { providerOptions } : {}),
                     stopWhen: [
                         sdkStepCountIs(this.config.maxSteps),
@@ -270,6 +272,16 @@ export class AgentExecutor extends EventEmitter {
                         this.state.usedBudget += tokensUsed;
                         this.state.inputTokensUsed += stepInput;
                         this.state.outputTokensUsed += stepOutput;
+                        const cacheUsage = extractCacheUsage(step.usage);
+                        this.trackStepUsage(model, stepInput, stepOutput, cacheUsage);
+                        if (cacheUsage.cacheReadTokens > 0 || cacheUsage.cacheWriteTokens > 0) {
+                            logger.debug("[AgentExecutor] Prompt cache usage", {
+                                sessionId: this.state.sessionId,
+                                cacheReadTokens: cacheUsage.cacheReadTokens,
+                                cacheWriteTokens: cacheUsage.cacheWriteTokens,
+                                promptTokens: cacheUsage.promptTokens,
+                            });
+                        }
                         // Update summary tracker with step progress
                         getAgentSummaryTracker().update(this.state.sessionId, {
                             status: 'thinking',
@@ -965,6 +977,27 @@ export class AgentExecutor extends EventEmitter {
             }
         }
     }
+    /** Route one step's usage (with cache tokens) into the cost tracker. */
+    trackStepUsage(model, inputTokens, outputTokens, cache) {
+        const total = inputTokens + outputTokens;
+        if (total <= 0)
+            return;
+        const modelId = typeof model === "string" ? model : getRecord(model)?.modelId;
+        if (typeof modelId !== "string" || modelId.length === 0)
+            return;
+        try {
+            trackChatUsage(modelId, total, inputTokens, outputTokens, {
+                cacheReadTokens: cache.cacheReadTokens,
+                cacheWriteTokens: cache.cacheWriteTokens,
+            });
+        }
+        catch (err) {
+            logger.warn("[AgentExecutor] Usage tracking failed", {
+                sessionId: this.state.sessionId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     // Finalization
     finalize() {
         // Clean up any temp files written by the result store (fire-and-forget)

package/dist/agents/output-truncator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool Output Truncator
+ *
+ * Caps large tool results (file reads, command output, logs, web content) to a
+ * configurable char budget before they reach the model. The head and the tail
+ * are kept (errors and summaries usually live at the end), the middle is
+ * replaced by an explicit marker, and the full result is kept in the
+ * ResultStore so the model can fetch a range with `fetch_result`.
+ */
+import type { ResultStore } from './result-store.js';
+export interface TruncationConfig {
+    /** Max chars of a result sent to the model */
+    maxChars: number;
+    /** Fraction of the budget spent on the head (rest goes to the tail) */
+    headRatio: number;
+    /** Max chars returned by a single fetch_result call */
+    fetchMaxChars: number;
+}
+export declare function getTruncationConfig(): TruncationConfig;
+/** Truncation is on unless PROFCLAW_TOOL_OUTPUT_TRUNCATION is off/0/false/no. */
+export declare function isTruncationEnabled(): boolean;
+export interface TruncatedText {
+    text: string;
+    truncated: boolean;
+    /** Number of chars removed from the middle */
+    omitted: number;
+}
+/**
+ * Keep the head and tail of `text`, replacing the middle with a marker.
+ */
+export declare function truncateText(text: string, maxChars: number, headRatio?: number, hint?: string): TruncatedText;
+export interface TruncatedResult {
+    /** Value to hand to the model (original reference when nothing was cut) */
+    value: unknown;
+    truncated: boolean;
+    omitted: number;
+}
+/**
+ * Truncate an arbitrary tool result. Long string fields are shortened in place
+ * so the object shape survives; if the whole payload is still over budget
+ * (e.g. a huge array), it falls back to truncating the JSON text.
+ */
+export declare function truncateResult(result: unknown, config?: TruncationConfig, hint?: string): TruncatedResult;
+/**
+ * Truncate `result` if needed. When truncation happens the FULL result is
+ * saved in `store` under `toolCallId` so `fetch_result` can page through it.
+ */
+export declare function truncateAndStore(store: ResultStore, toolCallId: string, result: unknown, config?: TruncationConfig): Promise<TruncatedResult>;
+export interface ResultRange {
+    resultId: string;
+    offset: number;
+    length: number;
+    totalChars: number;
+    content: string;
+    hasMore: boolean;
+}
+/** Read a char range of a stored full result (JSON text of the original). */
+export declare function readStoredRange(store: ResultStore, resultId: string, offset: number, length: number, config?: TruncationConfig): Promise<ResultRange | null>;
+//# sourceMappingURL=output-truncator.d.ts.map

package/dist/agents/output-truncator.js

@@ -0,0 +1,128 @@
+/**
+ * Tool Output Truncator
+ *
+ * Caps large tool results (file reads, command output, logs, web content) to a
+ * configurable char budget before they reach the model. The head and the tail
+ * are kept (errors and summaries usually live at the end), the middle is
+ * replaced by an explicit marker, and the full result is kept in the
+ * ResultStore so the model can fetch a range with `fetch_result`.
+ */
+import { readFile } from 'node:fs/promises';
+const DEFAULT_MAX_CHARS = 12_000;
+const DEFAULT_HEAD_RATIO = 0.7;
+function readPositiveInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function getTruncationConfig() {
+    const maxChars = readPositiveInt('PROFCLAW_TOOL_OUTPUT_MAX_CHARS', DEFAULT_MAX_CHARS);
+    const rawRatio = Number.parseFloat(process.env.PROFCLAW_TOOL_OUTPUT_HEAD_RATIO ?? '');
+    const headRatio = Number.isFinite(rawRatio) && rawRatio > 0 && rawRatio < 1 ? rawRatio : DEFAULT_HEAD_RATIO;
+    return {
+        maxChars,
+        headRatio,
+        fetchMaxChars: readPositiveInt('PROFCLAW_TOOL_FETCH_MAX_CHARS', maxChars),
+    };
+}
+/** Truncation is on unless PROFCLAW_TOOL_OUTPUT_TRUNCATION is off/0/false/no. */
+export function isTruncationEnabled() {
+    const flag = (process.env.PROFCLAW_TOOL_OUTPUT_TRUNCATION ?? '').toLowerCase();
+    return !['off', '0', 'false', 'no'].includes(flag);
+}
+/**
+ * Keep the head and tail of `text`, replacing the middle with a marker.
+ */
+export function truncateText(text, maxChars, headRatio = DEFAULT_HEAD_RATIO, hint = '') {
+    if (text.length <= maxChars) {
+        return { text, truncated: false, omitted: 0 };
+    }
+    const headLen = Math.floor(maxChars * headRatio);
+    const tailLen = Math.max(0, maxChars - headLen);
+    const omitted = text.length - headLen - tailLen;
+    const marker = `\n[truncated ${omitted} chars${hint ? `. ${hint}` : ''}]\n`;
+    const tail = tailLen > 0 ? text.slice(text.length - tailLen) : '';
+    return { text: text.slice(0, headLen) + marker + tail, truncated: true, omitted };
+}
+function shrinkStrings(value, maxChars, headRatio, hint, stats, depth) {
+    if (typeof value === 'string') {
+        const t = truncateText(value, maxChars, headRatio, hint);
+        stats.omitted += t.omitted;
+        return t.text;
+    }
+    if (depth > 6 || value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((v) => shrinkStrings(v, maxChars, headRatio, hint, stats, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = shrinkStrings(v, maxChars, headRatio, hint, stats, depth + 1);
+    }
+    return out;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Truncate an arbitrary tool result. Long string fields are shortened in place
+ * so the object shape survives; if the whole payload is still over budget
+ * (e.g. a huge array), it falls back to truncating the JSON text.
+ */
+export function truncateResult(result, config = getTruncationConfig(), hint = '') {
+    const serialized = typeof result === 'string' ? result : safeStringify(result);
+    if (serialized.length <= config.maxChars) {
+        return { value: result, truncated: false, omitted: 0 };
+    }
+    if (typeof result === 'string') {
+        const t = truncateText(result, config.maxChars, config.headRatio, hint);
+        return { value: t.text, truncated: true, omitted: t.omitted };
+    }
+    const stats = { omitted: 0 };
+    const shrunk = shrinkStrings(result, config.maxChars, config.headRatio, hint, stats, 0);
+    const shrunkSerialized = safeStringify(shrunk);
+    if (shrunkSerialized.length <= config.maxChars * 1.25 + 256 && stats.omitted > 0) {
+        return { value: shrunk, truncated: true, omitted: stats.omitted };
+    }
+    const t = truncateText(serialized, config.maxChars, config.headRatio, hint);
+    return { value: t.text, truncated: true, omitted: t.omitted };
+}
+// Store integration
+/**
+ * Truncate `result` if needed. When truncation happens the FULL result is
+ * saved in `store` under `toolCallId` so `fetch_result` can page through it.
+ */
+export async function truncateAndStore(store, toolCallId, result, config = getTruncationConfig()) {
+    const hint = `full output saved as result_id "${toolCallId}", call fetch_result with offset/length`;
+    const truncated = truncateResult(result, config, hint);
+    if (truncated.truncated) {
+        await store.store(toolCallId, result);
+    }
+    return truncated;
+}
+/** Read a char range of a stored full result (JSON text of the original). */
+export async function readStoredRange(store, resultId, offset, length, config = getTruncationConfig()) {
+    const stored = store.retrieve(resultId);
+    if (!stored)
+        return null;
+    const full = stored.fullPath ? await readFile(stored.fullPath, 'utf8') : stored.inline;
+    const start = Math.max(0, Math.min(offset, full.length));
+    const len = Math.max(1, Math.min(length, config.fetchMaxChars));
+    const content = full.slice(start, start + len);
+    return {
+        resultId,
+        offset: start,
+        length: content.length,
+        totalChars: full.length,
+        content,
+        hasMore: start + content.length < full.length,
+    };
+}
+//# sourceMappingURL=output-truncator.js.map

package/dist/agents/receipt/receipt-cli.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Helpers that connect receipts to the CLI: key handling and writer setup.
+ */
+import { ReceiptWriter } from './receipt-writer.js';
+export interface RunReceiptArgs {
+    projectRoot: string;
+    runId: string;
+    /** --sign-key path; falls back to env PROFCLAW_RECEIPT_KEY */
+    signKeyPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Create the writer for a run. Signing is off unless a key path is given. */
+export declare function createRunReceipt(args: RunReceiptArgs): ReceiptWriter;
+/** Version of the running profclaw package, or 'unknown'. */
+export declare function toolVersion(): string;
+export interface KeyPairFiles {
+    privateKeyPath: string;
+    publicKeyPath: string;
+}
+/** Write an Ed25519 keypair into dir. The private key file is mode 0600. */
+export declare function generateKeyPairFiles(dir: string): KeyPairFiles;
+/** Short one-line description of tool arguments. Long values are cut so files are not copied into the receipt. */
+export declare function summarizeArgs(args: Record<string, unknown>, maxChars?: number): string;
+export interface RunReceiptSetup {
+    runId: string;
+    receipt?: ReceiptWriter;
+    /** Hook for ExecutorRunner: records each tool call */
+    onToolCall?: (event: {
+        attempt: number;
+        name: string;
+        args: Record<string, unknown>;
+        durationMs: number;
+        ok: boolean;
+    }) => void;
+}
+/** Everything `profclaw run` needs to record a receipt; a no-op setup when disabled. */
+export declare function setupRunReceipt(args: {
+    enabled: boolean;
+    projectRoot: string;
+    signKeyPath?: string;
+    env?: NodeJS.ProcessEnv;
+}): RunReceiptSetup;
+//# sourceMappingURL=receipt-cli.d.ts.map