@vurb/core 3.2.0

package/dist/core/createGroup.js

@@ -0,0 +1,144 @@
+/**
+ * createGroup() — Functional Tool Group Compiler
+ *
+ * A lightweight, closure-based alternative to the class-heavy
+ * `GroupedToolBuilder`. Instead of maintaining internal state via `this._x`,
+ * it compiles a group config into a frozen object with pre-composed
+ * middleware and an O(1) dispatch function.
+ *
+ * **Why Functional?**
+ * - Closures minify 30-40% better than class methods (Terser can rename local vars)
+ * - No prototype chain overhead — zero `this` binding issues
+ * - Frozen return type prevents accidental mutation
+ * - Compatible with Edge Runtimes (Cloudflare Workers, Deno Deploy)
+ *
+ * @example
+ * ```typescript
+ * import { createGroup, success } from 'vurb';
+ *
+ * const billing = createGroup({
+ *   name: 'billing',
+ *   description: 'Invoice management',
+ *   middleware: [requireAuth],
+ *   actions: {
+ *     get_invoice: {
+ *       schema: z.object({ id: z.string() }),
+ *       readOnly: true,
+ *       handler: async (ctx, args) => success(await ctx.db.invoices.get(args.id)),
+ *     },
+ *     pay: {
+ *       schema: z.object({ invoice_id: z.string(), amount: z.number() }),
+ *       destructive: true,
+ *       handler: async (ctx, args) => success(await ctx.db.payments.create(args)),
+ *     },
+ *   },
+ * });
+ *
+ * // billing.execute(ctx, 'get_invoice', { id: '123' })
+ * // billing.name === 'billing'
+ * // billing.actionNames === ['get_invoice', 'pay']
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+import { error as toolError } from '../core/response.js';
+import {} from '../core/types.js';
+// ── Middleware Composition ────────────────────────────────
+/**
+ * Compose an array of middleware into a single function.
+ * Right-to-left composition: last middleware is innermost (closest to handler).
+ * @internal
+ */
+function composeMiddleware(globalMiddleware, actionMiddleware, handler) {
+    const allMiddleware = [...globalMiddleware, ...actionMiddleware];
+    if (allMiddleware.length === 0) {
+        return handler;
+    }
+    // Build the chain from right to left
+    return allMiddleware.reduceRight((next, mw) => (ctx, args) => mw(ctx, args, () => next(ctx, args)), handler);
+}
+// ── Factory ──────────────────────────────────────────────
+/**
+ * Create a compiled, frozen tool group from a declarative config.
+ *
+ * The returned object has O(1) action dispatch via a pre-built Map.
+ * All middleware chains are pre-composed at creation time — zero
+ * runtime overhead on each call.
+ *
+ * @typeParam TContext - Application context type
+ * @param config - Group configuration with actions
+ * @returns A frozen {@link CompiledGroup} ready for execution
+ *
+ * @example
+ * ```typescript
+ * const tasks = createGroup({
+ *   name: 'tasks',
+ *   middleware: [logMiddleware],
+ *   actions: {
+ *     list: {
+ *       readOnly: true,
+ *       handler: async (ctx) => success(await ctx.db.tasks.findMany()),
+ *     },
+ *     create: {
+ *       schema: z.object({ title: z.string() }),
+ *       handler: async (ctx, args) => success(await ctx.db.tasks.create(args)),
+ *     },
+ *   },
+ * });
+ *
+ * const result = await tasks.execute(ctx, 'create', { title: 'Buy milk' });
+ * ```
+ */
+export function createGroup(config) {
+    const globalMiddleware = config.middleware ?? [];
+    const actionNames = Object.keys(config.actions);
+    // Pre-compose middleware chains for each action (O(1) dispatch)
+    const dispatchMap = new Map();
+    for (const [name, action] of Object.entries(config.actions)) {
+        const compiled = composeMiddleware(globalMiddleware, action.middleware ?? [], action.handler);
+        dispatchMap.set(name, compiled);
+    }
+    // Pre-validate action args using Zod schemas
+    const schemaMap = new Map();
+    for (const [name, action] of Object.entries(config.actions)) {
+        if (action.schema) {
+            schemaMap.set(name, action.schema);
+        }
+    }
+    const execute = async (ctx, action, args) => {
+        const chain = dispatchMap.get(action);
+        if (!chain) {
+            return toolError(`Unknown action "${action}" in group "${config.name}". Available: ${actionNames.join(', ')}`, 'INVALID_PARAMS');
+        }
+        // Validate with Zod if schema is defined — use safeParse to return
+        // ToolResponse instead of throwing ZodError (contract compliance).
+        // Uses the consumer's schema as-is to respect their unknown-keys policy
+        // (.passthrough(), .strip(), or .strict()).
+        const schema = schemaMap.get(action);
+        if (schema) {
+            const result = schema.safeParse(args);
+            if (!result.success) {
+                const issues = result.error.issues
+                    .map(i => `${i.path.join('.')}: ${i.message}`)
+                    .join('; ');
+                return toolError(`Validation failed for action "${action}" in group "${config.name}": ${issues}`, 'INVALID_PARAMS');
+            }
+            // Use result.data to preserve Zod transforms, defaults, and strip behavior
+            return chain(ctx, result.data ?? args);
+        }
+        return chain(ctx, args);
+    };
+    const getAction = (name) => {
+        return config.actions[name];
+    };
+    return Object.freeze({
+        name: config.name,
+        description: config.description,
+        tags: Object.freeze(config.tags ?? []),
+        actionNames: Object.freeze(actionNames),
+        execute,
+        getAction,
+    });
+}
+//# sourceMappingURL=createGroup.js.map

package/dist/core/createGroup.js.map

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

package/dist/core/execution/ConcurrencyGuard.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ConcurrencyGuard — Per-Tool Semaphore with Backpressure Queue
+ *
+ * Implements the Semaphore pattern to prevent thundering-herd scenarios
+ * where an LLM fires N concurrent tool calls in the same millisecond.
+ *
+ * Architecture:
+ *   ┌─────────────────────────────────────────────────┐
+ *   │  Incoming tool call                             │
+ *   │                                                 │
+ *   │  ┌───────────┐  slot free?  ┌──────────────┐   │
+ *   │  │  acquire() ├────YES────► │  run handler  │   │
+ *   │  │           │              └──────────────┘   │
+ *   │  │           │  queue has    ┌──────────────┐   │
+ *   │  │           ├──space?──YES─►│  enqueue()   │   │
+ *   │  │           │              └──────────────┘   │
+ *   │  │           │  both full    ┌──────────────┐   │
+ *   │  │           ├──────NO──────►│ load shedding│   │
+ *   │  └───────────┘              └──────────────┘   │
+ *   └─────────────────────────────────────────────────┘
+ *
+ * Properties:
+ * - Zero overhead when not configured (guard is `undefined`)
+ * - O(1) acquire/release with deque-based pending queue
+ * - Cooperative with AbortSignal: queued waiters are rejected on abort
+ * - Pure module: no side effects, no dependencies
+ *
+ * @module
+ * @internal
+ */
+/**
+ * Concurrency configuration for a tool builder.
+ *
+ * @example
+ * ```typescript
+ * createTool<AppContext>('billing')
+ *     .concurrency({ maxActive: 5, maxQueue: 20 })
+ *     .action({ name: 'process_invoice', handler: ... });
+ * ```
+ */
+export interface ConcurrencyConfig {
+    /**
+     * Maximum number of concurrent executions allowed.
+     * When all slots are occupied, new calls enter the queue.
+     *
+     * @minimum 1
+     */
+    readonly maxActive: number;
+    /**
+     * Maximum number of calls waiting in the backpressure queue.
+     * When the queue is full, new calls are immediately rejected
+     * with a load-shedding error.
+     *
+     * @minimum 0
+     * @default 0
+     */
+    readonly maxQueue?: number;
+}
+/**
+ * A concurrency guard that limits simultaneous tool executions.
+ *
+ * Created once per builder via `createConcurrencyGuard()`.
+ * Used by `GroupedToolBuilder.execute()` to gate entry.
+ */
+export declare class ConcurrencyGuard {
+    private readonly _maxActive;
+    private readonly _maxQueue;
+    private _active;
+    private readonly _pending;
+    constructor(config: ConcurrencyConfig);
+    /**
+     * Attempt to acquire an execution slot.
+     *
+     * - If a slot is free: increments active count, resolves immediately.
+     * - If queue has space: enqueues and returns a promise that resolves when a slot opens.
+     * - If both full: returns `null` (load shedding signal).
+     *
+     * @param signal - Optional AbortSignal for cooperative cancellation of queued waiters.
+     * @returns A release function (call when execution completes) or `null` for load shedding.
+     */
+    acquire(signal?: AbortSignal): Promise<(() => void)> | null;
+    /**
+     * Current number of active (in-flight) executions.
+     */
+    get active(): number;
+    /**
+     * Current number of waiters in the backpressure queue.
+     */
+    get queued(): number;
+    private _createRelease;
+    private _drainNext;
+    private _removePending;
+}
+/**
+ * Create a ConcurrencyGuard from configuration.
+ *
+ * Returns `undefined` when no configuration is provided,
+ * ensuring zero overhead on the fast path.
+ *
+ * @internal
+ */
+export declare function createConcurrencyGuard(config?: ConcurrencyConfig): ConcurrencyGuard | undefined;
+//# sourceMappingURL=ConcurrencyGuard.d.ts.map

package/dist/core/execution/ConcurrencyGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConcurrencyGuard.d.ts","sourceRoot":"","sources":["../../../src/core/execution/ConcurrencyGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC9B;AAUD;;;;;GAKG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;gBAEpC,MAAM,EAAE,iBAAiB;IAOrC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,IAAI;IA6C3D;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAID,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,cAAc;CAMzB;AAID;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,CAAC,EAAE,iBAAiB,GAC3B,gBAAgB,GAAG,SAAS,CAG9B"}

package/dist/core/execution/ConcurrencyGuard.js

@@ -0,0 +1,147 @@
+/**
+ * ConcurrencyGuard — Per-Tool Semaphore with Backpressure Queue
+ *
+ * Implements the Semaphore pattern to prevent thundering-herd scenarios
+ * where an LLM fires N concurrent tool calls in the same millisecond.
+ *
+ * Architecture:
+ *   ┌─────────────────────────────────────────────────┐
+ *   │  Incoming tool call                             │
+ *   │                                                 │
+ *   │  ┌───────────┐  slot free?  ┌──────────────┐   │
+ *   │  │  acquire() ├────YES────► │  run handler  │   │
+ *   │  │           │              └──────────────┘   │
+ *   │  │           │  queue has    ┌──────────────┐   │
+ *   │  │           ├──space?──YES─►│  enqueue()   │   │
+ *   │  │           │              └──────────────┘   │
+ *   │  │           │  both full    ┌──────────────┐   │
+ *   │  │           ├──────NO──────►│ load shedding│   │
+ *   │  └───────────┘              └──────────────┘   │
+ *   └─────────────────────────────────────────────────┘
+ *
+ * Properties:
+ * - Zero overhead when not configured (guard is `undefined`)
+ * - O(1) acquire/release with deque-based pending queue
+ * - Cooperative with AbortSignal: queued waiters are rejected on abort
+ * - Pure module: no side effects, no dependencies
+ *
+ * @module
+ * @internal
+ */
+/**
+ * A concurrency guard that limits simultaneous tool executions.
+ *
+ * Created once per builder via `createConcurrencyGuard()`.
+ * Used by `GroupedToolBuilder.execute()` to gate entry.
+ */
+export class ConcurrencyGuard {
+    _maxActive;
+    _maxQueue;
+    _active = 0;
+    _pending = [];
+    constructor(config) {
+        this._maxActive = Math.max(1, Math.floor(config.maxActive));
+        this._maxQueue = Math.max(0, Math.floor(config.maxQueue ?? 0));
+    }
+    // ── Public API ───────────────────────────────────────
+    /**
+     * Attempt to acquire an execution slot.
+     *
+     * - If a slot is free: increments active count, resolves immediately.
+     * - If queue has space: enqueues and returns a promise that resolves when a slot opens.
+     * - If both full: returns `null` (load shedding signal).
+     *
+     * @param signal - Optional AbortSignal for cooperative cancellation of queued waiters.
+     * @returns A release function (call when execution completes) or `null` for load shedding.
+     */
+    acquire(signal) {
+        // Fast path: slot available
+        if (this._active < this._maxActive) {
+            this._active++;
+            return Promise.resolve(this._createRelease());
+        }
+        // Queue path: check capacity
+        if (this._pending.length >= this._maxQueue) {
+            return null; // Load shedding
+        }
+        // Enqueue waiter
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve: () => resolve(this._createRelease()),
+                reject,
+            };
+            this._pending.push(waiter);
+            // If signal is already aborted, reject immediately
+            if (signal?.aborted) {
+                this._removePending(waiter);
+                reject(new Error('Request cancelled while queued.'));
+                return;
+            }
+            // Listen for abort while queued
+            if (signal) {
+                const onAbort = () => {
+                    this._removePending(waiter);
+                    reject(new Error('Request cancelled while queued.'));
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                // Clean up listener when waiter resolves normally
+                const originalResolve = waiter.resolve;
+                waiter.resolve = () => {
+                    signal.removeEventListener('abort', onAbort);
+                    originalResolve();
+                };
+            }
+        });
+    }
+    /**
+     * Current number of active (in-flight) executions.
+     */
+    get active() {
+        return this._active;
+    }
+    /**
+     * Current number of waiters in the backpressure queue.
+     */
+    get queued() {
+        return this._pending.length;
+    }
+    // ── Private ──────────────────────────────────────────
+    _createRelease() {
+        let released = false;
+        return () => {
+            if (released)
+                return; // Idempotent
+            released = true;
+            this._active--;
+            this._drainNext();
+        };
+    }
+    _drainNext() {
+        if (this._pending.length > 0 && this._active < this._maxActive) {
+            this._active++;
+            const next = this._pending.shift();
+            next.resolve();
+        }
+    }
+    _removePending(waiter) {
+        const idx = this._pending.indexOf(waiter);
+        if (idx !== -1) {
+            this._pending.splice(idx, 1);
+        }
+    }
+}
+// ── Factory ──────────────────────────────────────────────
+/**
+ * Create a ConcurrencyGuard from configuration.
+ *
+ * Returns `undefined` when no configuration is provided,
+ * ensuring zero overhead on the fast path.
+ *
+ * @internal
+ */
+export function createConcurrencyGuard(config) {
+    if (!config)
+        return undefined;
+    return new ConcurrencyGuard(config);
+}
+//# sourceMappingURL=ConcurrencyGuard.js.map

package/dist/core/execution/ConcurrencyGuard.js.map

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

package/dist/core/execution/EgressGuard.d.ts

@@ -0,0 +1,72 @@
+/**
+ * EgressGuard — Payload Size Limiter (FinOps + OOM Shield)
+ *
+ * Prevents oversized tool responses from:
+ * 1. Crashing the Node process with OOM (JSON.stringify of 30MB)
+ * 2. Overflowing the LLM context window ($15 per wasted request)
+ * 3. Saturating the transport layer
+ *
+ * This is a **brute-force safety net** — the last line of defense.
+ * Presenter `.agentLimit()` is the domain-aware guard; this is the
+ * byte-level guard for when `.agentLimit()` is not configured.
+ *
+ * Architecture:
+ *   ┌──────────────────────────────────────────────┐
+ *   │  ToolResponse from handler/Presenter         │
+ *   │                                              │
+ *   │  ┌──────────┐  within limit? ┌───────────┐  │
+ *   │  │ measure  ├────YES────────►│ pass-thru │  │
+ *   │  │ bytes    │                └───────────┘  │
+ *   │  │          │  exceeds?      ┌───────────┐  │
+ *   │  │          ├────YES────────►│ truncate  │  │
+ *   │  └──────────┘                │ + inject  │  │
+ *   │                              │ guidance  │  │
+ *   │                              └───────────┘  │
+ *   └──────────────────────────────────────────────┘
+ *
+ * Properties:
+ * - Zero overhead when not configured (guard returns input directly)
+ * - Measures byte length via Buffer.byteLength (UTF-8 accurate)
+ * - Truncates at the text level, preserving valid ToolResponse shape
+ * - Injects system intervention message for LLM self-correction
+ *
+ * @module
+ * @internal
+ */
+import { type ToolResponse } from '../response.js';
+/**
+ * Egress guard configuration.
+ *
+ * @example
+ * ```typescript
+ * registry.attachToServer(server, {
+ *     contextFactory: createContext,
+ *     maxPayloadBytes: 2 * 1024 * 1024, // 2MB safety net
+ * });
+ * ```
+ */
+export interface EgressConfig {
+    /**
+     * Maximum total payload size in bytes.
+     * When a response exceeds this limit, the text content is
+     * truncated and a system intervention message is appended.
+     *
+     * @minimum 1024 (1KB minimum to avoid unusable responses)
+     */
+    readonly maxPayloadBytes: number;
+}
+/**
+ * Apply egress guard to a ToolResponse.
+ *
+ * Measures the total byte length of all text content blocks.
+ * If the total exceeds `maxPayloadBytes`, truncates the LAST
+ * text block and appends a system intervention message.
+ *
+ * @param response - The ToolResponse to guard
+ * @param maxPayloadBytes - Maximum allowed bytes
+ * @returns The original response (if within limit) or a truncated copy
+ *
+ * @internal
+ */
+export declare function applyEgressGuard(response: ToolResponse, maxPayloadBytes: number): ToolResponse;
+//# sourceMappingURL=EgressGuard.d.ts.map

package/dist/core/execution/EgressGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EgressGuard.d.ts","sourceRoot":"","sources":["../../../src/core/execution/EgressGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACpC;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,YAAY,EACtB,eAAe,EAAE,MAAM,GACxB,YAAY,CA6Ed"}

package/dist/core/execution/EgressGuard.js

@@ -0,0 +1,163 @@
+/**
+ * EgressGuard — Payload Size Limiter (FinOps + OOM Shield)
+ *
+ * Prevents oversized tool responses from:
+ * 1. Crashing the Node process with OOM (JSON.stringify of 30MB)
+ * 2. Overflowing the LLM context window ($15 per wasted request)
+ * 3. Saturating the transport layer
+ *
+ * This is a **brute-force safety net** — the last line of defense.
+ * Presenter `.agentLimit()` is the domain-aware guard; this is the
+ * byte-level guard for when `.agentLimit()` is not configured.
+ *
+ * Architecture:
+ *   ┌──────────────────────────────────────────────┐
+ *   │  ToolResponse from handler/Presenter         │
+ *   │                                              │
+ *   │  ┌──────────┐  within limit? ┌───────────┐  │
+ *   │  │ measure  ├────YES────────►│ pass-thru │  │
+ *   │  │ bytes    │                └───────────┘  │
+ *   │  │          │  exceeds?      ┌───────────┐  │
+ *   │  │          ├────YES────────►│ truncate  │  │
+ *   │  └──────────┘                │ + inject  │  │
+ *   │                              │ guidance  │  │
+ *   │                              └───────────┘  │
+ *   └──────────────────────────────────────────────┘
+ *
+ * Properties:
+ * - Zero overhead when not configured (guard returns input directly)
+ * - Measures byte length via Buffer.byteLength (UTF-8 accurate)
+ * - Truncates at the text level, preserving valid ToolResponse shape
+ * - Injects system intervention message for LLM self-correction
+ *
+ * @module
+ * @internal
+ */
+import {} from '../response.js';
+// ── Constants ────────────────────────────────────────────
+const MIN_PAYLOAD_BYTES = 1024;
+const TRUNCATION_SUFFIX = '\n\n[SYSTEM INTERVENTION: Payload truncated at {limit} to prevent memory crash. ' +
+    'You MUST use pagination (limit/offset) or filters to retrieve smaller result sets.]';
+// ── Guard Implementation ─────────────────────────────────
+/**
+ * Apply egress guard to a ToolResponse.
+ *
+ * Measures the total byte length of all text content blocks.
+ * If the total exceeds `maxPayloadBytes`, truncates the LAST
+ * text block and appends a system intervention message.
+ *
+ * @param response - The ToolResponse to guard
+ * @param maxPayloadBytes - Maximum allowed bytes
+ * @returns The original response (if within limit) or a truncated copy
+ *
+ * @internal
+ */
+export function applyEgressGuard(response, maxPayloadBytes) {
+    const limit = Math.max(MIN_PAYLOAD_BYTES, maxPayloadBytes);
+    // Measure total byte length across all content blocks
+    let totalBytes = 0;
+    for (const block of response.content) {
+        totalBytes += byteLength(block.text);
+    }
+    // Fast path: within limit
+    if (totalBytes <= limit) {
+        return response;
+    }
+    // Truncation path: find how much to cut
+    const suffix = TRUNCATION_SUFFIX.replace('{limit}', formatBytes(limit));
+    const suffixBytes = byteLength(suffix);
+    const targetBytes = limit - suffixBytes;
+    if (targetBytes <= 0) {
+        // Edge case: limit is smaller than the suffix itself
+        return {
+            content: [{ type: 'text', text: suffix.trim() }],
+            isError: true,
+        };
+    }
+    // Truncate by rebuilding content blocks
+    let remainingBytes = targetBytes;
+    const truncatedContent = [];
+    for (const block of response.content) {
+        const blockBytes = byteLength(block.text);
+        if (remainingBytes <= 0) {
+            // Skip remaining blocks entirely
+            break;
+        }
+        if (blockBytes <= remainingBytes) {
+            // Block fits entirely
+            truncatedContent.push({ type: 'text', text: block.text });
+            remainingBytes -= blockBytes;
+        }
+        else {
+            // Block needs truncation — truncate at character boundary
+            const truncatedText = truncateToByteLimit(block.text, remainingBytes);
+            truncatedContent.push({ type: 'text', text: truncatedText + suffix });
+            remainingBytes = 0;
+        }
+    }
+    // If blocks were skipped (remainingBytes exhausted exactly at a block
+    // boundary), append the truncation suffix so the LLM knows content
+    // was removed. Without this, the response looks deceptively complete.
+    const allBlocksIncluded = truncatedContent.length === response.content.length;
+    if (!allBlocksIncluded && truncatedContent.length > 0) {
+        const last = truncatedContent[truncatedContent.length - 1];
+        if (!last.text.endsWith(suffix.trim())) {
+            truncatedContent[truncatedContent.length - 1] = {
+                type: 'text',
+                text: last.text + suffix,
+            };
+        }
+    }
+    // Ensure at least one content block exists
+    if (truncatedContent.length === 0) {
+        truncatedContent.push({ type: 'text', text: suffix.trim() });
+    }
+    const result = {
+        content: truncatedContent,
+    };
+    if (response.isError) {
+        result.isError = true;
+    }
+    return result;
+}
+// ── Utilities ────────────────────────────────────────────
+/**
+ * Get the UTF-8 byte length of a string.
+ * Uses TextEncoder for cross-platform compatibility.
+ */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: false });
+function byteLength(str) {
+    return encoder.encode(str).byteLength;
+}
+/**
+ * Truncate a string to fit within a byte limit.
+ * Respects multi-byte UTF-8 character boundaries by backtracking
+ * from the cut point to avoid producing U+FFFD replacement characters.
+ */
+function truncateToByteLimit(str, maxBytes) {
+    const encoded = encoder.encode(str);
+    if (encoded.byteLength <= maxBytes)
+        return str;
+    // Backtrack from the byte boundary to a valid UTF-8 sequence start.
+    // UTF-8 continuation bytes have the pattern 10xxxxxx (0x80..0xBF).
+    let end = maxBytes;
+    while (end > 0 && ((encoded[end] ?? 0) & 0xC0) === 0x80) {
+        end--;
+    }
+    const sliced = encoded.slice(0, end);
+    return decoder.decode(sliced);
+}
+/**
+ * Format bytes into a human-readable string.
+ */
+function formatBytes(bytes) {
+    if (bytes >= 1024 * 1024) {
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+    if (bytes >= 1024) {
+        return `${(bytes / 1024).toFixed(0)}KB`;
+    }
+    return `${bytes}B`;
+}
+//# sourceMappingURL=EgressGuard.js.map

package/dist/core/execution/EgressGuard.js.map

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