@pellux/goodvibes-sdk 0.18.13 → 0.18.15

package/dist/_internal/platform/runtime/tools/phased-executor.js

@@ -0,0 +1,338 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { emitBudgetExceededCost, emitBudgetExceededMs, emitBudgetExceededTokens, emitToolCancelled, emitToolExecuting, emitToolFailed, emitToolMapped, emitToolPermissioned, emitToolPosthooked, emitToolPrehooked, emitToolSucceeded, emitToolValidated, } from '../emitters/tools.js';
+import { budgetPhase, executePhase, mapOutputPhase, permissionPhase, posthookPhase, prehookPhase, validatePhase, } from './phases/index.js';
+/**
+ * PhasedToolExecutor — runs a ToolCall through the multi-phase execution pipeline.
+ *
+ * Pipeline (in order):
+ *   validate → prehook → permission → execute → mapOutput → posthook → succeeded
+ *
+ * Any phase that sets `abort: true` on its PhaseResult will halt the pipeline
+ * and transition to the `failed` or `cancelled` terminal state.
+ *
+ * Cancellation is cooperative: the executor checks `context.cancellation.signal`
+ * at each phase boundary and immediately transitions to `cancelled` when aborted.
+ *
+ * @example
+ * ```ts
+ * const executor = createPhasedExecutor({ enableHooks: true, enablePermissions: true, enableEvents: true });
+ * const result = await executor.execute(call, tool, context);
+ * ```
+ */
+/** Maximum number of completed records retained in memory before eviction. */
+const MAX_RECORDS = 1000;
+export class PhasedToolExecutor {
+    config;
+    records = new Map();
+    controllers = new Map();
+    /** Maps ToolCall instances to their idempotency key without mutating the input. */
+    _idKeyMap = new WeakMap();
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Execute a tool call through all pipeline phases.
+     * Returns a ToolResult regardless of outcome — callers never need to catch.
+     */
+    async execute(call, tool, context) {
+        // --- Idempotency check ---
+        // Must run before creating a record to avoid registering calls that will be
+        // short-circuited as duplicates or rejected as in-flight.
+        if (this.config.idempotencyStore) {
+            const idKey = this.config.idempotencyStore.generateKey({
+                sessionId: context.ids.sessionId,
+                turnId: context.ids.turnId,
+                callId: call.id,
+            });
+            const check = this.config.idempotencyStore.checkAndRecord(idKey);
+            if (check.status === 'duplicate') {
+                logger.debug('PhasedToolExecutor: duplicate tool call — returning cached result', {
+                    callId: call.id,
+                    tool: call.name,
+                    idKey,
+                    priorStatus: check.record.status,
+                });
+                // Return the cached result from the prior completed execution.
+                // If the prior run failed (status === 'failed'), the cached result will
+                // be undefined and we return a generic error to the LLM.
+                if (check.record.result !== undefined) {
+                    return check.record.result;
+                }
+                return {
+                    callId: call.id,
+                    success: false,
+                    error: 'Duplicate tool call: prior execution failed; retry is not permitted.',
+                };
+            }
+            if (check.status === 'in-flight') {
+                logger.warn('PhasedToolExecutor: in-flight duplicate detected — rejecting', {
+                    callId: call.id,
+                    tool: call.name,
+                    idKey,
+                    inFlightSince: check.record.createdAt,
+                });
+                return {
+                    callId: call.id,
+                    success: false,
+                    error: 'Duplicate tool call: an identical submission is already in-flight.',
+                };
+            }
+            // 'new' — proceed; store the key so _fail/_cancel can markFailed.
+            this._idKeyMap.set(call, idKey);
+        }
+        const record = {
+            callId: call.id,
+            toolName: call.name,
+            phases: [],
+            currentPhase: 'received',
+            startedAt: performance.now(),
+            wallStartedAt: Date.now(),
+            cancelled: false,
+        };
+        this.records.set(call.id, record);
+        this._evictOldestCompleted();
+        // Create a per-execution AbortController. cancel() aborts this controller;
+        // the pipeline loop checks controller.signal.aborted at every boundary.
+        // The outer context.cancellation.signal is also respected via a forwarding listener.
+        const controller = new AbortController();
+        this.controllers.set(call.id, controller);
+        const cancelSignal = controller.signal;
+        // Forward outer cancellation into our local controller
+        const forwardAbort = () => controller.abort(context.cancellation.reason);
+        if (context.cancellation.signal.aborted) {
+            controller.abort(context.cancellation.reason);
+        }
+        else {
+            context.cancellation.signal.addEventListener('abort', forwardAbort, { once: true });
+        }
+        const budgetEnabled = this.config.enableBudgetEnforcement === true;
+        const pipeline = [
+            ['validated', validatePhase, true],
+            ['prehooked', prehookPhase, this.config.enableHooks],
+            ['permissioned', permissionPhase, this.config.enablePermissions],
+            ['budget-entry', (c, t, ctx, r) => budgetPhase(c, t, ctx, r, 'entry'), budgetEnabled],
+            ['executing', (c, t, ctx, r) => executePhase(c, t, ctx, r, this.config), true],
+            ['mapped', mapOutputPhase, true],
+            ['budget-exit', (c, t, ctx, r) => budgetPhase(c, t, ctx, r, 'exit'), budgetEnabled],
+            ['posthooked', posthookPhase, this.config.enableHooks],
+        ];
+        const emitterCtx = {
+            sessionId: context.ids.sessionId,
+            traceId: context.ids.traceId,
+            source: 'phased-executor',
+        };
+        for (const [phaseName, phaseFn, enabled] of pipeline) {
+            // --- Cancellation check at every boundary ---
+            if (cancelSignal.aborted) {
+                context.cancellation.signal.removeEventListener('abort', forwardAbort);
+                this.controllers.delete(call.id);
+                return this._cancel(record, call, context, emitterCtx, cancelSignal.reason);
+            }
+            if (!enabled) {
+                continue;
+            }
+            record.currentPhase = phaseName;
+            const phaseResult = await phaseFn(call, tool, context, record);
+            record.phases.push(phaseResult);
+            // --- Emit per-phase event ---
+            if (this.config.enableEvents && context.runtimeBus) {
+                this._emitPhaseEvent(phaseName, phaseResult, call, context, emitterCtx);
+            }
+            // --- Capture execute result ---
+            if (phaseName === 'executing' && phaseResult.toolResult) {
+                record.result = phaseResult.toolResult;
+            }
+            // --- Handle phase failure/abort ---
+            if (!phaseResult.success || phaseResult.abort) {
+                context.cancellation.signal.removeEventListener('abort', forwardAbort);
+                this.controllers.delete(call.id);
+                // Emit typed budget breach event before failing
+                if (phaseResult.budgetExceedReason && this.config.enableEvents && context.runtimeBus) {
+                    this._emitBudgetEvent(phaseResult.budgetExceedReason, phaseResult.budgetMeta ?? {}, phaseName, call, context, emitterCtx);
+                }
+                return this._fail(record, call, context, emitterCtx, phaseResult.error ?? 'Phase failed');
+            }
+        }
+        // --- Final cancellation check before transitioning to succeeded ---
+        context.cancellation.signal.removeEventListener('abort', forwardAbort);
+        if (cancelSignal.aborted) {
+            this.controllers.delete(call.id);
+            return this._cancel(record, call, context, emitterCtx, cancelSignal.reason);
+        }
+        // --- Succeeded ---
+        this.controllers.delete(call.id);
+        record.currentPhase = 'succeeded';
+        const durationMs = performance.now() - record.startedAt;
+        record.completedAt = Date.now();
+        if (this.config.enableEvents && context.runtimeBus) {
+            emitToolSucceeded(context.runtimeBus, emitterCtx, {
+                callId: call.id,
+                turnId: context.ids.turnId,
+                tool: call.name,
+                durationMs,
+            });
+        }
+        context.tasks.onComplete?.(call.id, durationMs);
+        const finalResult = record.result ?? {
+            callId: call.id,
+            success: true,
+        };
+        // --- Idempotency: cache the successful result ---
+        const idKey = this._getIdKey(call);
+        if (idKey && this.config.idempotencyStore) {
+            this.config.idempotencyStore.markComplete(idKey, finalResult);
+        }
+        return finalResult;
+    }
+    /**
+     * Cancel an in-flight tool execution.
+     * Sets a cancelled flag on the record; the next phase boundary will pick it up.
+     */
+    cancel(callId, reason) {
+        const record = this.records.get(callId);
+        if (record && !record.completedAt) {
+            record.cancelled = true;
+            record.cancelledReason = reason;
+            this.controllers.get(callId)?.abort(reason);
+        }
+    }
+    /** Returns the full execution record for a given call id, if any. */
+    getRecord(callId) {
+        return this.records.get(callId);
+    }
+    /** Returns all execution records for in-flight calls. */
+    getActiveRecords() {
+        return Array.from(this.records.values()).filter((r) => !r.completedAt);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Extract the idempotency key previously attached to a call during `execute`.
+     * Returns `undefined` if no idempotency store is configured.
+     */
+    _getIdKey(call) {
+        return this._idKeyMap.get(call);
+    }
+    _fail(record, call, context, emitterCtx, error) {
+        record.currentPhase = 'failed';
+        const durationMs = performance.now() - record.startedAt;
+        record.completedAt = Date.now();
+        if (this.config.enableEvents && context.runtimeBus) {
+            emitToolFailed(context.runtimeBus, emitterCtx, {
+                callId: call.id,
+                turnId: context.ids.turnId,
+                tool: call.name,
+                error,
+                durationMs,
+            });
+        }
+        context.tasks.onError?.(call.id, error);
+        // --- Idempotency: mark failed to allow retry ---
+        const idKey = this._getIdKey(call);
+        if (idKey && this.config.idempotencyStore) {
+            this.config.idempotencyStore.markFailed(idKey);
+        }
+        return {
+            callId: call.id,
+            success: false,
+            error,
+        };
+    }
+    _cancel(record, call, context, emitterCtx, reason) {
+        record.currentPhase = 'cancelled';
+        record.cancelled = true;
+        record.cancelledReason = reason;
+        record.completedAt = Date.now();
+        if (this.config.enableEvents && context.runtimeBus) {
+            emitToolCancelled(context.runtimeBus, emitterCtx, {
+                callId: call.id,
+                turnId: context.ids.turnId,
+                tool: call.name,
+                reason,
+            });
+        }
+        // --- Idempotency: mark failed so the cancelled call can be retried ---
+        const idKey = this._getIdKey(call);
+        if (idKey && this.config.idempotencyStore) {
+            this.config.idempotencyStore.markFailed(idKey);
+        }
+        return {
+            callId: call.id,
+            success: false,
+            error: reason ? `Cancelled: ${reason}` : 'Tool call cancelled',
+        };
+    }
+    /**
+     * Evicts the oldest completed records when the map exceeds MAX_RECORDS.
+     * Only completed records are eligible for eviction.
+     */
+    _evictOldestCompleted() {
+        if (this.records.size <= MAX_RECORDS)
+            return;
+        for (const [id, record] of this.records) {
+            if (record.completedAt) {
+                this.records.delete(id);
+                if (this.records.size <= MAX_RECORDS)
+                    break;
+            }
+        }
+    }
+    _emitBudgetEvent(reason, meta, phase, call, context, emitterCtx) {
+        if (!context.runtimeBus)
+            return;
+        const base = { callId: call.id, turnId: context.ids.turnId, tool: call.name, phase: String(phase) };
+        switch (reason) {
+            case 'BUDGET_EXCEEDED_MS':
+                emitBudgetExceededMs(context.runtimeBus, emitterCtx, {
+                    ...base,
+                    limitMs: meta['limitMs'] ?? 0,
+                    elapsedMs: meta['elapsedMs'] ?? 0,
+                });
+                break;
+            case 'BUDGET_EXCEEDED_TOKENS':
+                emitBudgetExceededTokens(context.runtimeBus, emitterCtx, {
+                    ...base,
+                    limitTokens: meta['limitTokens'] ?? 0,
+                    usedTokens: meta['usedTokens'] ?? 0,
+                });
+                break;
+            case 'BUDGET_EXCEEDED_COST':
+                emitBudgetExceededCost(context.runtimeBus, emitterCtx, {
+                    ...base,
+                    limitCostUsd: meta['limitCostUsd'] ?? 0,
+                    usedCostUsd: meta['usedCostUsd'] ?? 0,
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    _emitPhaseEvent(phase, _result, call, context, emitterCtx) {
+        if (!context.runtimeBus)
+            return;
+        const base = { callId: call.id, turnId: context.ids.turnId, tool: call.name };
+        switch (phase) {
+            case 'validated':
+                emitToolValidated(context.runtimeBus, emitterCtx, base);
+                break;
+            case 'prehooked':
+                emitToolPrehooked(context.runtimeBus, emitterCtx, base);
+                break;
+            case 'permissioned':
+                emitToolPermissioned(context.runtimeBus, emitterCtx, { ...base, approved: _result.success });
+                break;
+            case 'executing':
+                emitToolExecuting(context.runtimeBus, emitterCtx, { ...base, startedAt: Date.now() });
+                break;
+            case 'mapped':
+                emitToolMapped(context.runtimeBus, emitterCtx, base);
+                break;
+            case 'posthooked':
+                emitToolPosthooked(context.runtimeBus, emitterCtx, base);
+                break;
+            default:
+                break;
+        }
+    }
+}

package/dist/_internal/platform/runtime/tools/phases/budget.d.ts

@@ -0,0 +1,21 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.js';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+/**
+ * budget — Budget enforcement phase for the tool execution pipeline.
+ *
+ * This phase is inserted at two points:
+ *  - "entry": just before execute (checks elapsed wall-clock time).
+ *  - "exit": just after mapOutput (checks token and cost budgets).
+ *
+ * When a hard budget is exceeded the phase returns `abort: true` with a
+ * typed `budgetExceedReason` so the executor can surface a diagnostic
+ * event before terminating the pipeline.
+ *
+ * All budget fields are optional in ToolRuntimeContext.budget — an absent
+ * field means "unlimited" and the corresponding check is skipped.
+ */
+/** The point in the pipeline at which the budget check fires. */
+export type BudgetCheckPoint = 'entry' | 'exit';
+export declare function budgetPhase(_call: ToolCall, _tool: Tool, context: ToolRuntimeContext, record: ToolExecutionRecord, checkpoint: BudgetCheckPoint): Promise<PhaseResult>;
+//# sourceMappingURL=budget.d.ts.map

package/dist/_internal/platform/runtime/tools/phases/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/tools/phases/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,4CAA4C,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAsB,WAAW,EAAsB,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AAEnJ;;;;;;;;;;;;;GAaG;AAEH,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,IAAI,EACX,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,mBAAmB,EAC3B,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAAC,WAAW,CAAC,CA8CtB"}

package/dist/_internal/platform/runtime/tools/phases/budget.js

@@ -0,0 +1,87 @@
+export async function budgetPhase(_call, _tool, context, record, checkpoint) {
+    const start = performance.now();
+    const phaseName = checkpoint === 'entry' ? 'budget-entry' : 'budget-exit';
+    const budget = context.budget;
+    // No budget constraints — fast path
+    if (!budget) {
+        return ok(start, phaseName);
+    }
+    const elapsedMs = performance.now() - record.startedAt;
+    // ── Time budget (checked at both entry and exit) ────────────────────────
+    // All budget comparisons use strict > so that a value exactly at the limit is
+    // still allowed — enforcement fires only when the limit is truly exceeded.
+    if (budget.maxMs !== undefined && elapsedMs > budget.maxMs) {
+        return exceed(start, phaseName, 'BUDGET_EXCEEDED_MS', {
+            limitMs: budget.maxMs,
+            elapsedMs,
+        });
+    }
+    // ── Token and cost budgets (only meaningful at exit after execute ran) ──
+    if (checkpoint === 'exit') {
+        // Token budget: the tool result may carry a `tokenCount` annotation.
+        // We check it if present; if absent we skip (cannot enforce unknown usage).
+        const tokenCount = getTokenCount(record);
+        if (budget.maxTokens !== undefined && tokenCount !== undefined && tokenCount > budget.maxTokens) {
+            return exceed(start, phaseName, 'BUDGET_EXCEEDED_TOKENS', {
+                limitTokens: budget.maxTokens,
+                usedTokens: tokenCount,
+            });
+        }
+        // Cost budget: same — only enforce when the tool result carries a cost.
+        const costUsd = getCostUsd(record);
+        if (budget.maxCostUsd !== undefined && costUsd !== undefined && costUsd > budget.maxCostUsd) {
+            return exceed(start, phaseName, 'BUDGET_EXCEEDED_COST', {
+                limitCostUsd: budget.maxCostUsd,
+                usedCostUsd: costUsd,
+            });
+        }
+    }
+    return ok(start, phaseName);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ok(start, phase) {
+    return {
+        phase,
+        success: true,
+        durationMs: performance.now() - start,
+    };
+}
+function exceed(start, phase, reason, meta) {
+    const parts = Object.entries(meta)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+    return {
+        phase,
+        success: false,
+        durationMs: performance.now() - start,
+        error: `Budget exceeded [${reason}]: ${parts}`,
+        abort: true,
+        budgetExceedReason: reason,
+        budgetMeta: meta,
+    };
+}
+/**
+ * Extracts a token count from the tool execution record result, if available.
+ * Tools may annotate their result with `tokenCount` as a numeric field.
+ */
+function getTokenCount(record) {
+    if (!record.result)
+        return undefined;
+    // Double cast needed: ToolResult has no index signature, but tool implementations
+    // may annotate results with extra numeric fields like `tokenCount`.
+    const raw = record.result['tokenCount'];
+    return typeof raw === 'number' ? raw : undefined;
+}
+/**
+ * Extracts a cost annotation from the tool execution record result, if available.
+ * Tools may annotate their result with `costUsd` as a numeric field.
+ */
+function getCostUsd(record) {
+    if (!record.result)
+        return undefined;
+    // Double cast needed: same reason as getTokenCount above.
+    const raw = record.result['costUsd'];
+    return typeof raw === 'number' ? raw : undefined;
+}

package/dist/_internal/platform/runtime/tools/phases/execute.d.ts

@@ -0,0 +1,18 @@
+import type { Tool, ToolCall, ToolResult } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.js';
+import type { ExecutorConfig, PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+/**
+ * execute — Phase 4 of the tool execution pipeline.
+ *
+ * Calls `tool.execute(args)` and injects the callId into the result.
+ * Respects the phase timeout and the budget.maxMs constraint.
+ * Caught errors produce a failed PhaseResult (not thrown) so the
+ * executor can record the failure trace cleanly.
+ *
+ * The resolved args honour any prehook-modified input stored as
+ * `_updatedArgs` on the record.
+ */
+export declare function executePhase(call: ToolCall, tool: Tool, context: ToolRuntimeContext, record: ToolExecutionRecord, config?: ExecutorConfig): Promise<PhaseResult & {
+    toolResult?: ToolResult;
+}>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/_internal/platform/runtime/tools/phases/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/tools/phases/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAC7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AAM3H;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,CA2CpD"}

package/dist/_internal/platform/runtime/tools/phases/execute.js

@@ -0,0 +1,49 @@
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/** Default per-call execution timeout (30 seconds). */
+const DEFAULT_EXECUTE_TIMEOUT_MS = 30_000;
+/**
+ * execute — Phase 4 of the tool execution pipeline.
+ *
+ * Calls `tool.execute(args)` and injects the callId into the result.
+ * Respects the phase timeout and the budget.maxMs constraint.
+ * Caught errors produce a failed PhaseResult (not thrown) so the
+ * executor can record the failure trace cleanly.
+ *
+ * The resolved args honour any prehook-modified input stored as
+ * `_updatedArgs` on the record.
+ */
+export async function executePhase(call, tool, context, record, config) {
+    const start = performance.now();
+    const effectiveArgs = record._updatedArgs ?? call.arguments;
+    // Resolve timeout: per-phase override → budget → default
+    const timeoutMs = config?.phaseTimeouts?.['executing'] ?? context.budget?.maxMs ?? DEFAULT_EXECUTE_TIMEOUT_MS;
+    let timer;
+    try {
+        // Race between the tool and a timeout; clear the timer regardless of outcome
+        const rawResult = await Promise.race([
+            tool.execute(effectiveArgs),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Tool '${call.name}' timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+        clearTimeout(timer);
+        const toolResult = { ...rawResult, callId: call.id };
+        return {
+            phase: 'executing',
+            success: true,
+            durationMs: performance.now() - start,
+            toolResult,
+        };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        const message = summarizeError(err);
+        return {
+            phase: 'executing',
+            success: false,
+            durationMs: performance.now() - start,
+            error: message,
+            abort: true,
+        };
+    }
+}

package/dist/_internal/platform/runtime/tools/phases/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * phases/index.ts — barrel export for all tool execution phase functions.
+ *
+ * Each export is a pure async function conforming to PhaseFunction.
+ * The pipeline is assembled in phased-executor.ts.
+ */
+export { validatePhase } from './validate.js';
+export { prehookPhase } from './prehook.js';
+export { permissionPhase } from './permission.js';
+export { budgetPhase } from './budget.js';
+export { executePhase } from './execute.js';
+export { mapOutputPhase } from './map-output.js';
+export { posthookPhase } from './posthook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/tools/phases/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/tools/phases/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/_internal/platform/runtime/tools/phases/index.js

@@ -0,0 +1,13 @@
+/**
+ * phases/index.ts — barrel export for all tool execution phase functions.
+ *
+ * Each export is a pure async function conforming to PhaseFunction.
+ * The pipeline is assembled in phased-executor.ts.
+ */
+export { validatePhase } from './validate.js';
+export { prehookPhase } from './prehook.js';
+export { permissionPhase } from './permission.js';
+export { budgetPhase } from './budget.js';
+export { executePhase } from './execute.js';
+export { mapOutputPhase } from './map-output.js';
+export { posthookPhase } from './posthook.js';

package/dist/_internal/platform/runtime/tools/phases/map-output.d.ts

@@ -0,0 +1,5 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.js';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+export declare function mapOutputPhase(call: ToolCall, tool: Tool, _context: ToolRuntimeContext, record: ToolExecutionRecord): Promise<PhaseResult>;
+//# sourceMappingURL=map-output.d.ts.map

package/dist/_internal/platform/runtime/tools/phases/map-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-output.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/tools/phases/map-output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,4CAA4C,CAAC;AAEjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAC;AAuC3G,wBAAsB,cAAc,CAClC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAkDtB"}

package/dist/_internal/platform/runtime/tools/phases/map-output.js

@@ -0,0 +1,83 @@
+import { repairToolCall } from '@pellux/goodvibes-sdk/platform/tools/auto-repair';
+import { applyOutputPolicy, getPolicy } from '@pellux/goodvibes-sdk/platform/runtime/tools/output-policy';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/**
+ * mapOutput — Phase 5 of the tool execution pipeline.
+ *
+ * Transforms/annotates the raw tool result before it reaches the LLM:
+ *
+ * 1. Applies auto-repair annotation: if args were repaired during
+ *    execution, prepends a `[Auto-repaired: ...]` note to the output
+ *    so the LLM knows what was corrected.
+ * 2. Applies output policy enforcement: byte limits, truncation, and spill
+ *    handling are applied per tool class via `applyOutputPolicy`.
+ * 3. No-ops cleanly when there is no result to map (defensive guard).
+ */
+/** Type guard — true when `tool` carries phased execution metadata. */
+function isPhasedTool(tool) {
+    return 'category' in tool && typeof tool.category === 'string';
+}
+/**
+ * Maps a PhasedTool category to the ToolClass used by output-policy.
+ * `delegate` has no direct output-policy class; treat as `analyze`.
+ */
+function resolveToolClass(tool) {
+    if (!isPhasedTool(tool))
+        return 'read';
+    switch (tool.category) {
+        case 'read': return 'read';
+        case 'write': return 'write';
+        case 'execute': return 'execute';
+        case 'network': return 'network';
+        case 'delegate': return 'analyze';
+        default: return 'read';
+    }
+}
+export async function mapOutputPhase(call, tool, _context, record) {
+    const start = performance.now();
+    if (!record.result) {
+        // No result to map — this is a no-op (execute phase may have failed)
+        return {
+            phase: 'mapped',
+            success: true,
+            durationMs: performance.now() - start,
+        };
+    }
+    try {
+        // Re-run repair check to determine if the original args were patched
+        const effectiveArgs = record._updatedArgs ?? call.arguments;
+        const repairResult = repairToolCall(call.name, effectiveArgs, tool.definition);
+        if (repairResult.repaired) {
+            const repairNote = `[Auto-repaired: ${repairResult.repairs.join(', ')}]`;
+            if (typeof record.result.output === 'string') {
+                record.result.output = `${repairNote}\n${record.result.output}`;
+            }
+            else {
+                record.result.output = repairNote;
+            }
+        }
+        // Apply output policy enforcement after auto-repair annotation
+        const toolClass = resolveToolClass(tool);
+        const policy = getPolicy(toolClass);
+        const auditedResult = applyOutputPolicy(record.result, policy, _context.overflowHandler);
+        record.result = auditedResult.result;
+        // Surface spill backend in phase metadata when overflow occurred
+        const spillBackend = auditedResult.audit.spillBackend;
+        return {
+            phase: 'mapped',
+            success: true,
+            durationMs: performance.now() - start,
+            ...(spillBackend ? { spillBackend } : {}),
+        };
+    }
+    catch (err) {
+        // Mapping failure is non-fatal — pass through unmapped result
+        const message = summarizeError(err);
+        return {
+            phase: 'mapped',
+            success: true,
+            durationMs: performance.now() - start,
+            error: `Output mapping failed (non-fatal): ${message}`,
+        };
+    }
+}

package/dist/_internal/platform/runtime/tools/phases/permission.d.ts

@@ -0,0 +1,14 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.js';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+/**
+ * permission — Phase 3 of the tool execution pipeline.
+ *
+ * Delegates to PermissionManager.check(). If permission is denied,
+ * the phase aborts and no further phases are run.
+ *
+ * The resolved args used here account for any input updates from the
+ * prehook phase (stored as `_updatedArgs` on the record).
+ */
+export declare function permissionPhase(call: ToolCall, _tool: Tool, context: ToolRuntimeContext, record: ToolExecutionRecord): Promise<PhaseResult>;
+//# sourceMappingURL=permission.d.ts.map