@autonome-research/thread-phase 3.0.0

package/dist/context/compressor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Message compressor — Layer 2 of token defense.
+ *
+ * When the total message history exceeds the compression threshold, older
+ * tool-result messages get their content replaced with one-line summaries.
+ * Tool call/result pairing is preserved (orphaned calls or results would
+ * cause API errors at the next request).
+ *
+ * Operates on the framework's internal Message shape (see ../messages.ts).
+ * Tool results are their own role:'tool' messages with toolCallId pointing
+ * back to an assistant message's toolCalls[i].id.
+ */
+import type { Message } from '../messages.js';
+export interface CompressorStrategy {
+    compress(messages: Message[], options: CompressionOptions): Message[];
+}
+export interface CompressionOptions {
+    /** Number of leading messages to keep verbatim (system + initial user). */
+    protectFirst: number;
+    /** Number of trailing messages to keep verbatim (recent context). */
+    protectLast: number;
+    /** Activity-log entries used to enrich compressed summaries. Optional. */
+    activityLog: Array<{
+        agent: string;
+        action: string;
+        detail?: string;
+    }>;
+}
+export declare class DeterministicCompressor implements CompressorStrategy {
+    compress(messages: Message[], options: CompressionOptions): Message[];
+}
+export declare class AggressiveCompressor implements CompressorStrategy {
+    compress(messages: Message[], options: CompressionOptions): Message[];
+}
+export declare function sanitizeToolPairs(messages: Message[]): Message[];
+//# sourceMappingURL=compressor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compressor.d.ts","sourceRoot":"","sources":["../../src/context/compressor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAuC,MAAM,gBAAgB,CAAC;AAMnF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,EAAE,CAAC;CACvE;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxE;AAMD,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,EAAE;CA2BtE;AAOD,qBAAa,oBAAqB,YAAW,kBAAkB;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,EAAE;CAqCtE;AAiBD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAmEhE"}

package/dist/context/compressor.js

@@ -0,0 +1,158 @@
+/**
+ * Message compressor — Layer 2 of token defense.
+ *
+ * When the total message history exceeds the compression threshold, older
+ * tool-result messages get their content replaced with one-line summaries.
+ * Tool call/result pairing is preserved (orphaned calls or results would
+ * cause API errors at the next request).
+ *
+ * Operates on the framework's internal Message shape (see ../messages.ts).
+ * Tool results are their own role:'tool' messages with toolCallId pointing
+ * back to an assistant message's toolCalls[i].id.
+ */
+// ---------------------------------------------------------------------------
+// Default: deterministic compression of old tool-result messages.
+// ---------------------------------------------------------------------------
+export class DeterministicCompressor {
+    compress(messages, options) {
+        const { protectFirst, protectLast } = options;
+        if (messages.length <= protectFirst + protectLast) {
+            return messages;
+        }
+        const head = messages.slice(0, protectFirst);
+        const tail = messages.slice(-protectLast);
+        const middle = messages.slice(protectFirst, messages.length - protectLast);
+        const compressed = [...head];
+        for (const msg of middle) {
+            if (msg.role === 'tool') {
+                const compressedMsg = {
+                    role: 'tool',
+                    toolCallId: msg.toolCallId,
+                    content: `[Previous tool result: ${msg.content.length} chars — compressed to save context]`,
+                };
+                compressed.push(compressedMsg);
+            }
+            else {
+                compressed.push(msg);
+            }
+        }
+        compressed.push(...tail);
+        return compressed;
+    }
+}
+// ---------------------------------------------------------------------------
+// Aggressive: also compress tool-call arguments in old assistant messages.
+// Used when deterministic compression isn't enough (HARD_STOP path).
+// ---------------------------------------------------------------------------
+export class AggressiveCompressor {
+    compress(messages, options) {
+        const { protectFirst, protectLast } = options;
+        if (messages.length <= protectFirst + protectLast) {
+            return messages;
+        }
+        const head = messages.slice(0, protectFirst);
+        const tail = messages.slice(-protectLast);
+        const middle = messages.slice(protectFirst, messages.length - protectLast);
+        const compressed = [...head];
+        for (const msg of middle) {
+            if (msg.role === 'tool') {
+                compressed.push({
+                    role: 'tool',
+                    toolCallId: msg.toolCallId,
+                    content: '[Compressed — old tool result removed]',
+                });
+            }
+            else if (msg.role === 'assistant' && msg.toolCalls.length > 0) {
+                const stubbed = {
+                    role: 'assistant',
+                    content: msg.content,
+                    toolCalls: msg.toolCalls.map((tc) => ({
+                        id: tc.id,
+                        name: tc.name,
+                        input: { _compressed: true, summary: `Called ${tc.name}` },
+                    })),
+                };
+                compressed.push(stubbed);
+            }
+            else {
+                compressed.push(msg);
+            }
+        }
+        compressed.push(...tail);
+        return compressed;
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool-pair sanitization.
+//
+// Ensures every assistant ToolCall has a matching tool-result message and
+// vice versa. Orphaned results get dropped; orphaned calls get stub results
+// inserted. Run AFTER compression and before the next API call.
+//
+// Partial-orphan handling: when an assistant emits multiple tool calls and
+// only some have matching results, stubs for the orphaned calls are
+// appended *after* the run of real tool-result messages (i.e. immediately
+// before whatever non-tool message comes next, or end-of-array). This
+// preserves the OpenAI invariant "every tool_call.id must have a tool
+// message" without re-ordering existing real results.
+// ---------------------------------------------------------------------------
+export function sanitizeToolPairs(messages) {
+    const callIds = new Set();
+    const resultIds = new Set();
+    for (const msg of messages) {
+        if (msg.role === 'assistant') {
+            for (const tc of msg.toolCalls)
+                callIds.add(tc.id);
+        }
+        else if (msg.role === 'tool') {
+            resultIds.add(msg.toolCallId);
+        }
+    }
+    const orphanedCalls = new Set([...callIds].filter((id) => !resultIds.has(id)));
+    const orphanedResults = new Set([...resultIds].filter((id) => !callIds.has(id)));
+    if (orphanedCalls.size === 0 && orphanedResults.size === 0) {
+        return messages;
+    }
+    const result = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        // Drop orphaned tool-result messages outright.
+        if (msg.role === 'tool' && orphanedResults.has(msg.toolCallId)) {
+            continue;
+        }
+        result.push(msg);
+        // Insert stub results for orphaned calls right after the assistant +
+        // any contiguous run of (kept) real tool-result messages that follow
+        // it. This handles the partial-orphan case where some calls have real
+        // results and some don't — stubs go AFTER the real ones rather than
+        // being skipped entirely (which would leave the orphans unpaired).
+        if (msg.role === 'assistant') {
+            const orphansHere = msg.toolCalls.map((tc) => tc.id).filter((id) => orphanedCalls.has(id));
+            if (orphansHere.length === 0)
+                continue;
+            // Walk forward over any tool messages immediately following the
+            // assistant — append the kept ones to result first, then stub the
+            // orphans, so the final order is: assistant → real results → stubs.
+            let j = i + 1;
+            while (j < messages.length && messages[j].role === 'tool') {
+                const next = messages[j];
+                if (!orphanedResults.has(next.toolCallId)) {
+                    result.push(next);
+                }
+                j++;
+            }
+            for (const id of orphansHere) {
+                result.push({
+                    role: 'tool',
+                    toolCallId: id,
+                    content: '[Result removed during context compression]',
+                });
+            }
+            // Skip past the tool messages we just consumed; the outer loop's
+            // `i++` lands on `j`.
+            i = j - 1;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=compressor.js.map

package/dist/context/compressor.js.map

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

package/dist/context/index.d.ts

@@ -0,0 +1,4 @@
+export { TokenBudgetTracker, BudgetStatus, RoughTokenEstimator, type TokenEstimator, type TokenBudgetConfig, type BudgetCheck, } from './token-budget.js';
+export { TruncateAndCacheResultCapper, NoOpResultCapper, type ResultCapper, } from './result-capper.js';
+export { DeterministicCompressor, AggressiveCompressor, sanitizeToolPairs, type CompressorStrategy, type CompressionOptions, } from './compressor.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,4 @@
+export { TokenBudgetTracker, BudgetStatus, RoughTokenEstimator, } from './token-budget.js';
+export { TruncateAndCacheResultCapper, NoOpResultCapper, } from './result-capper.js';
+export { DeterministicCompressor, AggressiveCompressor, sanitizeToolPairs, } from './compressor.js';
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,GAIpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC"}

package/dist/context/result-capper.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tool-result capping — Layer 1 of token defense.
+ *
+ * Caps individual tool results before they enter the message history.
+ * Oversize results get a preview returned and (optionally) the full content
+ * stored in the pipeline cache for later retrieval.
+ */
+import type { PipelineCache } from '../cache.js';
+export interface ResultCapper {
+    /**
+     * Cap a tool result. If under limit, returns as-is.
+     * If over, returns a preview and (if cache is provided) stows the full
+     * content under `full_result:{toolCallId}` for later retrieval.
+     */
+    cap(content: string, toolName: string, toolCallId: string, cache?: PipelineCache | null): string;
+}
+/**
+ * Default capper: truncate at last newline within the preview budget,
+ * cache full content if a cache is provided.
+ */
+export declare class TruncateAndCacheResultCapper implements ResultCapper {
+    private maxChars;
+    private previewChars;
+    constructor(maxChars?: number, previewChars?: number);
+    cap(content: string, _toolName: string, toolCallId: string, cache?: PipelineCache | null): string;
+    private generatePreview;
+}
+/** No-op capper for tests or when capping is disabled. */
+export declare class NoOpResultCapper implements ResultCapper {
+    cap(content: string): string;
+}
+//# sourceMappingURL=result-capper.d.ts.map

package/dist/context/result-capper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-capper.d.ts","sourceRoot":"","sources":["../../src/context/result-capper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,CAAC;CAClG;AAED;;;GAGG;AACH,qBAAa,4BAA6B,YAAW,YAAY;IAC/D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,QAAQ,GAAE,MAAe,EAAE,YAAY,GAAE,MAAc;IAKnE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM;IAmBjG,OAAO,CAAC,eAAe;CAaxB;AAED,0DAA0D;AAC1D,qBAAa,gBAAiB,YAAW,YAAY;IACnD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAG7B"}

package/dist/context/result-capper.js

@@ -0,0 +1,50 @@
+/**
+ * Tool-result capping — Layer 1 of token defense.
+ *
+ * Caps individual tool results before they enter the message history.
+ * Oversize results get a preview returned and (optionally) the full content
+ * stored in the pipeline cache for later retrieval.
+ */
+/**
+ * Default capper: truncate at last newline within the preview budget,
+ * cache full content if a cache is provided.
+ */
+export class TruncateAndCacheResultCapper {
+    maxChars;
+    previewChars;
+    constructor(maxChars = 12_000, previewChars = 1_500) {
+        this.maxChars = maxChars;
+        this.previewChars = previewChars;
+    }
+    cap(content, _toolName, toolCallId, cache) {
+        if (content.length <= this.maxChars) {
+            return content;
+        }
+        const preview = this.generatePreview(content);
+        const fullLength = content.length;
+        if (cache) {
+            cache.set(`full_result:${toolCallId}`, content);
+        }
+        return (`[Result capped: ${fullLength} chars total, showing first ${preview.length} chars. ` +
+            `Full result available in pipeline cache (key: full_result:${toolCallId}).]\n\n` +
+            preview);
+    }
+    generatePreview(content) {
+        if (content.length <= this.previewChars) {
+            return content;
+        }
+        const truncated = content.slice(0, this.previewChars);
+        const lastNewline = truncated.lastIndexOf('\n');
+        if (lastNewline > this.previewChars / 2) {
+            return truncated.slice(0, lastNewline + 1) + '\n...[truncated]';
+        }
+        return truncated + '\n...[truncated]';
+    }
+}
+/** No-op capper for tests or when capping is disabled. */
+export class NoOpResultCapper {
+    cap(content) {
+        return content;
+    }
+}
+//# sourceMappingURL=result-capper.js.map

package/dist/context/result-capper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-capper.js","sourceRoot":"","sources":["../../src/context/result-capper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH;;;GAGG;AACH,MAAM,OAAO,4BAA4B;IAC/B,QAAQ,CAAS;IACjB,YAAY,CAAS;IAE7B,YAAY,WAAmB,MAAM,EAAE,eAAuB,KAAK;QACjE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,SAAiB,EAAE,UAAkB,EAAE,KAA4B;QACtF,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;QAElC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,GAAG,CAAC,eAAe,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,CACL,mBAAmB,UAAU,+BAA+B,OAAO,CAAC,MAAM,UAAU;YACpF,6DAA6D,UAAU,SAAS;YAChF,OAAO,CACR,CAAC;IACJ,CAAC;IAEO,eAAe,CAAC,OAAe;QACrC,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACxC,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACtD,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,WAAW,GAAG,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YACxC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,GAAG,kBAAkB,CAAC;QAClE,CAAC;QAED,OAAO,SAAS,GAAG,kBAAkB,CAAC;IACxC,CAAC;CACF;AAED,0DAA0D;AAC1D,MAAM,OAAO,gBAAgB;IAC3B,GAAG,CAAC,OAAe;QACjB,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/context/token-budget.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Token budget tracking and enforcement.
+ *
+ * Estimates token usage for the next API request (system + messages + tools)
+ * and reports a status code that the agent runner uses to trigger compression
+ * or force a final response.
+ *
+ * Estimator strategy is swappable. Default is a chars-per-token heuristic;
+ * downstream can plug in a tiktoken-based estimator for exact counts.
+ */
+import type { Message, ToolDefinition } from '../messages.js';
+export interface TokenEstimator {
+    estimate(text: string): number;
+    estimateRequest(systemPrompt: string, messages: Message[], tools: ToolDefinition[]): number;
+}
+/**
+ * Default: ~4 chars per token. Accurate enough for budget enforcement.
+ * Replace with a tiktoken-based estimator for exact counts.
+ */
+export declare class RoughTokenEstimator implements TokenEstimator {
+    private readonly charsPerToken;
+    constructor(charsPerToken?: number);
+    estimate(text: string): number;
+    estimateRequest(systemPrompt: string, messages: Message[], tools: ToolDefinition[]): number;
+}
+export interface TokenBudgetConfig {
+    contextWindow: number;
+    /** Trigger compression at this fraction of available budget (default 0.50). */
+    compressionThreshold: number;
+    /** Force output at this fraction of available budget (default 0.80). */
+    hardStopThreshold: number;
+    /** Tokens reserved for the model's response. */
+    responseReserve: number;
+    /** Per-result cap (chars) before the result-capper truncates. */
+    perResultCapChars: number;
+    /** Preview size (chars) when a result is capped. */
+    previewSizeChars: number;
+    /**
+     * Leading messages preserved verbatim during compression — typically the
+     * system prompt and the seed user message. Default 1.
+     */
+    protectFirst: number;
+    /**
+     * Trailing messages preserved verbatim during compression — recent context
+     * the model needs to make progress. Default 6 (deterministic) / 4 (aggressive).
+     * Set to a per-pipeline value when the workflow needs more or less recent history.
+     */
+    protectLast: number;
+    /** Trailing messages preserved during the aggressive (HARD_STOP) compressor. Default 4. */
+    protectLastAggressive: number;
+}
+export declare enum BudgetStatus {
+    OK = "ok",
+    COMPRESS = "compress",
+    HARD_STOP = "hard_stop"
+}
+export interface BudgetCheck {
+    status: BudgetStatus;
+    estimatedTokens: number;
+    /** 0.0 to 1.0+. Fraction of (contextWindow - responseReserve). */
+    budgetUsed: number;
+    compressionThreshold: number;
+    hardStopThreshold: number;
+}
+export declare class TokenBudgetTracker {
+    private config;
+    private estimator;
+    constructor(config?: Partial<TokenBudgetConfig>, estimator?: TokenEstimator);
+    check(systemPrompt: string, messages: Message[], tools: ToolDefinition[]): BudgetCheck;
+    getResultCap(): {
+        maxChars: number;
+        previewChars: number;
+    };
+    getProtectCounts(): {
+        protectFirst: number;
+        protectLast: number;
+        protectLastAggressive: number;
+    };
+    getEstimator(): TokenEstimator;
+}
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/context/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../src/context/token-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAM9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC;CAC7F;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,aAAa,GAAE,MAAU;IAIrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK9B,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;CAO5F;AAMD,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAkBD,oBAAY,YAAY;IACtB,EAAE,OAAO;IACT,QAAQ,aAAa;IACrB,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAiB;gBAEtB,MAAM,GAAE,OAAO,CAAC,iBAAiB,CAAM,EAAE,SAAS,CAAC,EAAE,cAAc;IAK/E,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,WAAW;IAqBtF,YAAY,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAO1D,gBAAgB,IAAI;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,qBAAqB,EAAE,MAAM,CAAC;KAC/B;IAQD,YAAY,IAAI,cAAc;CAG/B"}

package/dist/context/token-budget.js

@@ -0,0 +1,99 @@
+/**
+ * Token budget tracking and enforcement.
+ *
+ * Estimates token usage for the next API request (system + messages + tools)
+ * and reports a status code that the agent runner uses to trigger compression
+ * or force a final response.
+ *
+ * Estimator strategy is swappable. Default is a chars-per-token heuristic;
+ * downstream can plug in a tiktoken-based estimator for exact counts.
+ */
+/**
+ * Default: ~4 chars per token. Accurate enough for budget enforcement.
+ * Replace with a tiktoken-based estimator for exact counts.
+ */
+export class RoughTokenEstimator {
+    charsPerToken;
+    constructor(charsPerToken = 4) {
+        this.charsPerToken = charsPerToken;
+    }
+    estimate(text) {
+        if (!text)
+            return 0;
+        return Math.ceil(text.length / this.charsPerToken);
+    }
+    estimateRequest(systemPrompt, messages, tools) {
+        let totalChars = 0;
+        if (systemPrompt)
+            totalChars += systemPrompt.length;
+        if (messages.length > 0)
+            totalChars += JSON.stringify(messages).length;
+        if (tools.length > 0)
+            totalChars += JSON.stringify(tools).length;
+        return Math.ceil(totalChars / this.charsPerToken);
+    }
+}
+const DEFAULT_CONFIG = {
+    contextWindow: 131_072,
+    compressionThreshold: 0.5,
+    hardStopThreshold: 0.8,
+    responseReserve: 4_096,
+    perResultCapChars: 12_000,
+    previewSizeChars: 1_500,
+    protectFirst: 1,
+    protectLast: 6,
+    protectLastAggressive: 4,
+};
+// ---------------------------------------------------------------------------
+// Budget tracker
+// ---------------------------------------------------------------------------
+export var BudgetStatus;
+(function (BudgetStatus) {
+    BudgetStatus["OK"] = "ok";
+    BudgetStatus["COMPRESS"] = "compress";
+    BudgetStatus["HARD_STOP"] = "hard_stop";
+})(BudgetStatus || (BudgetStatus = {}));
+export class TokenBudgetTracker {
+    config;
+    estimator;
+    constructor(config = {}, estimator) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.estimator = estimator ?? new RoughTokenEstimator();
+    }
+    check(systemPrompt, messages, tools) {
+        const estimatedTokens = this.estimator.estimateRequest(systemPrompt, messages, tools);
+        const available = this.config.contextWindow - this.config.responseReserve;
+        const budgetUsed = estimatedTokens / available;
+        let status = BudgetStatus.OK;
+        if (budgetUsed >= this.config.hardStopThreshold) {
+            status = BudgetStatus.HARD_STOP;
+        }
+        else if (budgetUsed >= this.config.compressionThreshold) {
+            status = BudgetStatus.COMPRESS;
+        }
+        return {
+            status,
+            estimatedTokens,
+            budgetUsed,
+            compressionThreshold: this.config.compressionThreshold,
+            hardStopThreshold: this.config.hardStopThreshold,
+        };
+    }
+    getResultCap() {
+        return {
+            maxChars: this.config.perResultCapChars,
+            previewChars: this.config.previewSizeChars,
+        };
+    }
+    getProtectCounts() {
+        return {
+            protectFirst: this.config.protectFirst,
+            protectLast: this.config.protectLast,
+            protectLastAggressive: this.config.protectLastAggressive,
+        };
+    }
+    getEstimator() {
+        return this.estimator;
+    }
+}
+//# sourceMappingURL=token-budget.js.map

package/dist/context/token-budget.js.map

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

package/dist/helpers/caller.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Best-effort name derivation from the calling file's path.
+ *
+ * Walks the captured stack and returns the basename of the first frame
+ * outside this `helpers/` directory. Used by `oneShot` / `schedule` /
+ * `hook` to auto-name registrations when the caller didn't pass one.
+ *
+ * Pure heuristic — for production registrations the caller should pass
+ * an explicit `name`. The stack-walk is fast and synchronous; the
+ * helper file paths the matcher looks for are stable.
+ */
+/**
+ * Returns a slug-y name derived from the calling file (the first stack
+ * frame that isn't inside `helpers/`). Falls back to `fallback` if no
+ * usable frame is found.
+ */
+export declare function deriveNameFromCaller(fallback: string): string;
+//# sourceMappingURL=caller.d.ts.map

package/dist/helpers/caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.d.ts","sourceRoot":"","sources":["../../src/helpers/caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa7D"}

package/dist/helpers/caller.js

@@ -0,0 +1,40 @@
+/**
+ * Best-effort name derivation from the calling file's path.
+ *
+ * Walks the captured stack and returns the basename of the first frame
+ * outside this `helpers/` directory. Used by `oneShot` / `schedule` /
+ * `hook` to auto-name registrations when the caller didn't pass one.
+ *
+ * Pure heuristic — for production registrations the caller should pass
+ * an explicit `name`. The stack-walk is fast and synchronous; the
+ * helper file paths the matcher looks for are stable.
+ */
+import { basename } from 'node:path';
+const HELPER_FILE_MATCHERS = [
+    'helpers/one-shot',
+    'helpers/schedule',
+    'helpers/hook',
+    'helpers/caller',
+    'helpers/index',
+];
+/**
+ * Returns a slug-y name derived from the calling file (the first stack
+ * frame that isn't inside `helpers/`). Falls back to `fallback` if no
+ * usable frame is found.
+ */
+export function deriveNameFromCaller(fallback) {
+    const stack = new Error().stack ?? '';
+    const lines = stack.split('\n').slice(1);
+    for (const line of lines) {
+        const match = line.match(/\(?(\/[^):\s]+\.(?:ts|js|mts|mjs|cjs))(?::\d+)?(?::\d+)?\)?/);
+        if (!match)
+            continue;
+        const path = match[1];
+        if (HELPER_FILE_MATCHERS.some((m) => path.includes(m)))
+            continue;
+        const base = basename(path).replace(/\.(ts|js|mts|mjs|cjs)$/, '');
+        return base;
+    }
+    return fallback;
+}
+//# sourceMappingURL=caller.js.map

package/dist/helpers/caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.js","sourceRoot":"","sources":["../../src/helpers/caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,MAAM,oBAAoB,GAAG;IAC3B,kBAAkB;IAClB,kBAAkB;IAClB,cAAc;IACd,gBAAgB;IAChB,eAAe;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACxF,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QACjE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/helpers/hook.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `hook` — register a pipeline driven by an inbound HTTP webhook.
+ *
+ *   export default hook({ path: '/webhook/digest' }, async (payload, ctx) => {
+ *     return { ok: true, processed: payload };
+ *   });
+ *
+ * The library maintains one `node:http` server per project — every `hook`
+ * registration adds a new route to the same server. The server starts
+ * lazily on the first `Trigger.start()`. Routes resolve by exact path
+ * match; only POST with a JSON body is supported in v3.0.0.
+ *
+ * The handler is called with the parsed JSON body and ctx. Its return
+ * value is JSON-serialized and sent back as the HTTP response body
+ * (status 200). Throws produce status 500 with `{ error: message }`.
+ *
+ * Server port: `process.env.THREAD_PHASE_HTTP_PORT` if set, else 7777.
+ */
+import { type Server } from 'node:http';
+import type { Trigger, TriggerEvent } from '../triggers/types.js';
+import type { ExtensionRegisterFn, HelperHandler } from './types.js';
+export interface HookSpec {
+    /** URL path the webhook listens on. Exact match. */
+    path: string;
+    /** HTTP method. Only 'POST' is supported in v3.0.0. */
+    method?: 'POST';
+}
+export interface HookOptions {
+    /** Pipeline + trigger base name. Defaults to the calling file's basename. */
+    name?: string;
+    /** Free-form description for `thread-phase list`. */
+    description?: string;
+}
+/** Test-only: tear down the shared server so each test starts clean. */
+export declare function _resetHttpServerForTests(): void;
+export declare class HttpTrigger implements Trigger<unknown> {
+    readonly name: string;
+    readonly path: string;
+    readonly method: 'POST';
+    /** @internal — exposed for tests asserting the shared-server invariant. */
+    readonly _server: Server;
+    private seq;
+    private stopped;
+    private queued;
+    private waiter;
+    private readonly shared;
+    /** Map event.id → pending response so the handler's return value can be sent back. */
+    private readonly pendingById;
+    /** Map event.id → user handler's return value (so dispatch can resolve sync). */
+    private readonly resultsById;
+    constructor(opts: {
+        name: string;
+        path: string;
+        method: 'POST';
+    });
+    /**
+     * Called by the shared HTTP handler. Enqueues a new event and returns
+     * a promise that resolves with the user handler's return value.
+     */
+    dispatch(body: unknown): Promise<unknown>;
+    /**
+     * Resolve the pending HTTP response for a given event id. Called by the
+     * helper-generated Phase once the user handler has returned.
+     */
+    resolveResponse(eventId: number, value: unknown): void;
+    /** Reject the pending HTTP response for a given event id. */
+    rejectResponse(eventId: number, err: Error): void;
+    start(): AsyncGenerator<TriggerEvent<unknown>, void>;
+    stop(): Promise<void>;
+    private ensureServerStarted;
+}
+export declare function hook<TBody = unknown, TResult = unknown>(spec: HookSpec, handler: HelperHandler<TBody, TResult>, options?: HookOptions): ExtensionRegisterFn;
+//# sourceMappingURL=hook.d.ts.map