@pellux/goodvibes-tui 0.18.11 → 0.18.12

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

@@ -1,130 +0,0 @@
-import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
-import type { ToolRuntimeContext } from '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-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

@@ -1,69 +0,0 @@
-import type { Tool, ToolCall, ToolResult } from '@pellux/goodvibes-sdk/platform/types/tools';
-import type { ToolRuntimeContext } from '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-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

@@ -1,13 +0,0 @@
-/**
- * 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 '@pellux/goodvibes-sdk/platform/runtime/tools/phases/validate';
-export { prehookPhase } from '@pellux/goodvibes-sdk/platform/runtime/tools/phases/prehook';
-export { permissionPhase } from '@pellux/goodvibes-sdk/platform/runtime/tools/phases/permission';
-export { budgetPhase } from '@pellux/goodvibes-sdk/platform/runtime/tools/phases/budget';
-export { executePhase } from '@pellux/goodvibes-sdk/platform/runtime/tools/phases/execute';
-export { mapOutputPhase } from '@pellux/goodvibes-sdk/platform/runtime/tools/phases/map-output';
-export { posthookPhase } from '@pellux/goodvibes-sdk/platform/runtime/tools/phases/posthook';

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

@@ -1,98 +0,0 @@
-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 '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-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

@@ -1,133 +0,0 @@
-import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
-import type { ToolRuntimeContext } from '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-import type { PhaseResult, ToolExecutionRecord } from '@pellux/goodvibes-sdk/platform/runtime/tools/types';
-import {
-  emitPermissionDecision,
-  emitPermissionRequested,
-} from '@pellux/goodvibes-sdk/platform/runtime/emitters/permissions';
-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

@@ -1,57 +0,0 @@
-import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
-import type { ToolRuntimeContext } from '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-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

@@ -1,68 +0,0 @@
-import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
-import type { ToolRuntimeContext } from '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-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

@@ -1,53 +0,0 @@
-import type { Tool, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
-import type { ToolRuntimeContext } from '@pellux/goodvibes-sdk/platform/runtime/tools/context';
-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,
-  };
-}