@pellux/goodvibes-tui 0.18.4

package/src/runtime/tools/phases/budget.ts

@@ -0,0 +1,130 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { BudgetExceedReason, PhaseResult, ToolExecutionPhase, 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 async function budgetPhase(
+  _call: ToolCall,
+  _tool: Tool,
+  context: ToolRuntimeContext,
+  record: ToolExecutionRecord,
+  checkpoint: BudgetCheckPoint,
+): Promise<PhaseResult> {
+  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: number, phase: ToolExecutionPhase): PhaseResult {
+  return {
+    phase,
+    success: true,
+    durationMs: performance.now() - start,
+  };
+}
+
+function exceed(
+  start: number,
+  phase: ToolExecutionPhase,
+  reason: BudgetExceedReason,
+  meta: Record<string, number>,
+): PhaseResult {
+  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: ToolExecutionRecord): number | undefined {
+  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 as unknown as Record<string, unknown>)['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: ToolExecutionRecord): number | undefined {
+  if (!record.result) return undefined;
+  // Double cast needed: same reason as getTokenCount above.
+  const raw = (record.result as unknown as Record<string, unknown>)['costUsd'];
+  return typeof raw === 'number' ? raw : undefined;
+}

package/src/runtime/tools/phases/execute.ts

@@ -0,0 +1,69 @@
+import type { Tool, ToolCall, ToolResult } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { ExecutorConfig, PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+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: ToolCall,
+  tool: Tool,
+  context: ToolRuntimeContext,
+  record: ToolExecutionRecord,
+  config?: ExecutorConfig,
+): Promise<PhaseResult & { toolResult?: ToolResult }> {
+  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: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    // Race between the tool and a timeout; clear the timer regardless of outcome
+    const rawResult = await Promise.race([
+      tool.execute(effectiveArgs),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`Tool '${call.name}' timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+    clearTimeout(timer);
+
+    const toolResult: 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/src/runtime/tools/phases/index.ts

@@ -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.ts';
+export { prehookPhase } from './prehook.ts';
+export { permissionPhase } from './permission.ts';
+export { budgetPhase } from './budget.ts';
+export { executePhase } from './execute.ts';
+export { mapOutputPhase } from './map-output.ts';
+export { posthookPhase } from './posthook.ts';

package/src/runtime/tools/phases/map-output.ts

@@ -0,0 +1,98 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import { repairToolCall } from '@pellux/goodvibes-sdk/platform/tools/auto-repair';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+import type { PhasedTool } from '@pellux/goodvibes-sdk/platform/runtime/tools/adapter';
+import type { ToolClass } from '@pellux/goodvibes-sdk/platform/runtime/tools/output-policy';
+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: Tool): tool is PhasedTool {
+  return 'category' in tool && typeof (tool as PhasedTool).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: Tool): ToolClass {
+  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: ToolCall,
+  tool: Tool,
+  _context: ToolRuntimeContext,
+  record: ToolExecutionRecord,
+): Promise<PhaseResult> {
+  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/src/runtime/tools/phases/permission.ts

@@ -0,0 +1,133 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+import {
+  emitPermissionDecision,
+  emitPermissionRequested,
+} from '../../emitters/permissions.ts';
+import type { PermissionCheckResult } from '@pellux/goodvibes-sdk/platform/permissions/types';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+/**
+ * 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 async function permissionPhase(
+  call: ToolCall,
+  _tool: Tool,
+  context: ToolRuntimeContext,
+  record: ToolExecutionRecord,
+): Promise<PhaseResult> {
+  const start = performance.now();
+
+  // Use updated args from prehook if present
+  const effectiveArgs = record._updatedArgs ?? call.arguments;
+
+  const resolvePermissionResult = async (): Promise<PermissionCheckResult> => {
+    const manager = context.permissionManager as unknown as {
+      checkDetailed?: (toolName: string, args: Record<string, unknown>) => Promise<PermissionCheckResult>;
+      check?: (toolName: string, args: Record<string, unknown>) => Promise<boolean>;
+      getCategory: (toolName: string) => string;
+    };
+
+    if (typeof manager.checkDetailed === 'function') {
+      return manager.checkDetailed(call.name, effectiveArgs);
+    }
+
+    if (typeof manager.check === 'function') {
+      const approved = await manager.check(call.name, effectiveArgs);
+      return {
+        approved,
+        persisted: false,
+        sourceLayer: approved ? 'config_policy' : 'user_prompt',
+        reasonCode: approved ? 'config_allow' : 'user_denied',
+        analysis: {
+          classification: 'generic',
+          riskLevel: 'medium',
+          summary: `Permission ${approved ? 'approved' : 'denied'} for ${call.name}`,
+          reasons: [],
+        },
+      };
+    }
+
+    throw new Error('PermissionManager is missing both checkDetailed() and check()');
+  };
+
+  try {
+    if (context.runtimeBus) {
+      const analysis = await resolvePermissionResult();
+      emitPermissionRequested(context.runtimeBus, {
+        sessionId: context.ids.sessionId,
+        traceId: context.ids.traceId,
+        source: 'permission-manager',
+      }, {
+        callId: call.id,
+        tool: call.name,
+        args: effectiveArgs,
+        category: context.permissionManager.getCategory(call.name),
+        classification: analysis.analysis.classification,
+        riskLevel: analysis.analysis.riskLevel,
+        summary: analysis.analysis.summary,
+        reasons: analysis.analysis.reasons,
+      });
+
+      emitPermissionDecision(context.runtimeBus, {
+        sessionId: context.ids.sessionId,
+        traceId: context.ids.traceId,
+        source: 'permission-manager',
+      }, {
+        callId: call.id,
+        tool: call.name,
+        approved: analysis.approved,
+        source: 'permission-manager',
+        sourceLayer: analysis.sourceLayer,
+        persisted: analysis.persisted,
+        reasonCode: analysis.reasonCode,
+        classification: analysis.analysis.classification,
+        riskLevel: analysis.analysis.riskLevel,
+        summary: analysis.analysis.summary,
+      });
+
+      if (!analysis.approved) {
+        return {
+          phase: 'permissioned',
+          success: false,
+          durationMs: performance.now() - start,
+          error: `Permission denied for tool '${call.name}'`,
+          abort: true,
+        };
+      }
+    } else {
+      const analysis = await resolvePermissionResult();
+      if (!analysis.approved) {
+        return {
+          phase: 'permissioned',
+          success: false,
+          durationMs: performance.now() - start,
+          error: `Permission denied for tool '${call.name}'`,
+          abort: true,
+        };
+      }
+    }
+
+    return {
+      phase: 'permissioned',
+      success: true,
+      durationMs: performance.now() - start,
+    };
+  } catch (err) {
+    const message = summarizeError(err);
+    return {
+      phase: 'permissioned',
+      success: false,
+      durationMs: performance.now() - start,
+      error: `Permission check threw: ${message}`,
+      abort: true,
+    };
+  }
+}

package/src/runtime/tools/phases/posthook.ts

@@ -0,0 +1,57 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+/**
+ * posthook — Phase 6 of the tool execution pipeline.
+ *
+ * Fires `Post:tool:<toolName>` hook via the HookDispatcher.
+ *
+ * Post-hooks are non-blocking in the following sense: a hook failure does
+ * NOT fail the tool call. The phase always returns success=true so the
+ * executor can proceed to `succeeded`. Hook errors are captured in the
+ * PhaseResult.error field for observability without aborting the call.
+ */
+export async function posthookPhase(
+  call: ToolCall,
+  _tool: Tool,
+  context: ToolRuntimeContext,
+  record: ToolExecutionRecord,
+): Promise<PhaseResult> {
+  const start = performance.now();
+
+  try {
+    await context.hookDispatcher.fire({
+      path: `Post:tool:${call.name}`,
+      phase: 'Post',
+      category: 'tool',
+      specific: call.name,
+      sessionId: context.ids.sessionId,
+      timestamp: Date.now(),
+      payload: {
+        callId: call.id,
+        toolName: call.name,
+        args: record._updatedArgs ?? call.arguments,
+        result: record.result,
+        success: record.result?.success ?? false,
+      },
+      agentId: context.agent?.agentId,
+    });
+
+    return {
+      phase: 'posthooked',
+      success: true,
+      durationMs: performance.now() - start,
+    };
+  } catch (err) {
+    // Post-hook failure must not fail the tool call
+    const message = summarizeError(err);
+    return {
+      phase: 'posthooked',
+      success: true,
+      durationMs: performance.now() - start,
+      error: `Post-hook threw (non-fatal): ${message}`,
+    };
+  }
+}

package/src/runtime/tools/phases/prehook.ts

@@ -0,0 +1,68 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+
+/**
+ * prehook — Phase 2 of the tool execution pipeline.
+ *
+ * Fires `Pre:tool:<toolName>` hook via the HookDispatcher.
+ * If the hook returns a `deny` decision, execution is aborted.
+ * If the hook returns `updatedInput`, the record's args are updated
+ * in-place so subsequent phases see the modified arguments.
+ *
+ * Hook failures (network, timeout, etc.) are treated as allow to avoid
+ * blocking tool execution on non-critical infrastructure errors.
+ */
+export async function prehookPhase(
+  call: ToolCall,
+  _tool: Tool,
+  context: ToolRuntimeContext,
+  record: ToolExecutionRecord,
+): Promise<PhaseResult> {
+  const start = performance.now();
+
+  try {
+    const hookResult = await context.hookDispatcher.fire({
+      path: `Pre:tool:${call.name}`,
+      phase: 'Pre',
+      category: 'tool',
+      specific: call.name,
+      sessionId: context.ids.sessionId,
+      timestamp: Date.now(),
+      payload: {
+        callId: call.id,
+        toolName: call.name,
+        args: call.arguments,
+      },
+      agentId: context.agent?.agentId,
+    });
+
+    if (hookResult.decision === 'deny') {
+      return {
+        phase: 'prehooked',
+        success: false,
+        durationMs: performance.now() - start,
+        error: hookResult.reason ?? 'Pre-hook denied tool execution',
+        abort: true,
+      };
+    }
+
+    // Allow hooks to modify input arguments for subsequent phases
+    if (hookResult.updatedInput) {
+      record._updatedArgs = hookResult.updatedInput;
+    }
+
+    return {
+      phase: 'prehooked',
+      success: true,
+      durationMs: performance.now() - start,
+    };
+  } catch (_err) {
+    // Hook infrastructure failure — allow execution to proceed
+    return {
+      phase: 'prehooked',
+      success: true,
+      durationMs: performance.now() - start,
+    };
+  }
+}

package/src/runtime/tools/phases/validate.ts

@@ -0,0 +1,53 @@
+import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ToolRuntimeContext } from '../context.ts';
+import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
+
+/**
+ * validate — Phase 1 of the tool execution pipeline.
+ *
+ * Performs lightweight pre-flight checks:
+ * - The call has a non-empty id
+ * - The call has a non-empty tool name
+ * - Args is a plain object (not null)
+ * - The tool object is present
+ *
+ * Heavy schema validation (JSON Schema against parameters) is intentionally
+ * left to a future tier — this phase acts as a guard against programmer
+ * errors and malformed LLM payloads.
+ */
+export async function validatePhase(
+  call: ToolCall,
+  tool: Tool,
+  _context: ToolRuntimeContext,
+  _record: ToolExecutionRecord,
+): Promise<PhaseResult> {
+  const start = performance.now();
+
+  if (!call.id || call.id.trim().length === 0) {
+    return result(start, false, 'Tool call is missing a valid id');
+  }
+
+  if (!call.name || call.name.trim().length === 0) {
+    return result(start, false, 'Tool call is missing a tool name');
+  }
+
+  if (call.arguments === null || typeof call.arguments !== 'object' || Array.isArray(call.arguments)) {
+    return result(start, false, `Tool call args must be a plain object, got: ${typeof call.arguments}`);
+  }
+
+  if (!tool || typeof tool.execute !== 'function') {
+    return result(start, false, `Tool '${call.name}' is not a valid tool implementation`);
+  }
+
+  return result(start, true);
+}
+
+function result(start: number, success: boolean, error?: string): PhaseResult {
+  return {
+    phase: 'validated',
+    success,
+    durationMs: performance.now() - start,
+    error,
+    abort: success ? undefined : true,
+  };
+}