Flow Hooks

import { FlowCtxOf, FlowHooksOf, Provider } from '@frontmcp/sdk';

const { Stage, Will, Did, Around } = FlowHooksOf('tools:call-tool');

@Provider({ name: 'my-hooks' })
class MyHooks {
  @Will('execute')
  async beforeExecute(ctx: FlowCtxOf<'tools:call-tool'>) {
    ctx.logger.info('Before tool execution');
  }

  @Did('execute')
  async afterExecute(ctx: FlowCtxOf<'tools:call-tool'>) {
    ctx.logger.info('After tool execution');
  }
}

const { Will } = FlowHooksOf('tools:call-tool');

@Provider({ name: 'validation-hooks' })
class ValidationHooks {
  @Will('execute', { priority: 10 })
  async requireArguments(ctx: FlowCtxOf<'tools:call-tool'>) {
    const { arguments: toolArguments } = ctx.state.required.input;
    if (!toolArguments || Object.keys(toolArguments).length === 0) {
      throw new InvalidInputError('Arguments are required');
    }
  }

  @Will('execute', { priority: 20 })
  async logStart(ctx: FlowCtxOf<'tools:call-tool'>) {
    ctx.logger.info(`Starting tool: ${ctx.state.required.input.name}`);
  }
}

@Will('execute', { priority: 10 }) // Executes first
@Will('execute', { priority: 20 }) // Executes second

@Will('execute', {
  filter: (ctx) => ctx.state.required.input.name === 'sensitive_tool'
})
async logSensitiveAccess(ctx: FlowCtxOf<'tools:call-tool'>) {
  ctx.logger.warn('Accessing sensitive tool');
}

const { Did } = FlowHooksOf('tools:call-tool');

@Provider({ name: 'audit-hooks' })
class AuditHooks {
  @Did('execute')
  async auditToolCall(ctx: FlowCtxOf<'tools:call-tool'>) {
    const { input, toolContext } = ctx.state.required;
    await ctx.get(AuditService).log({
      tool: input.name,
      timestamp: new Date(),
      output: toolContext.output,
    });
  }
}

const { Around } = FlowHooksOf('tools:call-tool');

@Provider({ name: 'caching-hooks' })
class CachingHooks {
  private readonly cache = new Map<string, unknown>();

  @Around('execute')
  async cacheResults(ctx: FlowCtxOf<'tools:call-tool'>, next: () => Promise<void>) {
    const { name, arguments: toolArguments } = ctx.state.required.input;
    const cacheKey = `${name}:${JSON.stringify(toolArguments)}`;
    const cached = this.cache.get(cacheKey);

    if (cached !== undefined) {
      ctx.state.required.toolContext.output = cached;
      return; // Skip actual execution
    }

    await next(); // Execute the stage

    this.cache.set(cacheKey, ctx.state.required.toolContext.output);
  }
}

const { Stage } = FlowHooksOf('tools:call-tool');

@Provider({ name: 'maintenance-hooks' })
class MaintenanceHooks {
  @Stage('execute', {
    filter: (ctx) => ctx.state.required.input.name === 'export_report',
  })
  async answerDuringMaintenance(ctx: FlowCtxOf<'tools:call-tool'>) {
    // Runs before the tool's own execute step, which ctx.respond() then skips
    ctx.respond({ content: [{ type: 'text', text: 'Reports are paused for maintenance.' }] });
  }
}

interface HookOptions<Ctx = unknown> {
  priority?: number;                              // Execution order (lower = first)
  filter?: (ctx: Ctx) => boolean | Promise<boolean>; // Conditional execution
  appliesTo?: 'own-app' | 'uncovered-apps';        // Reach of an app plugin's hook (default 'own-app')
}

@App({
  name: 'my-app',
  providers: [AuditHooks, CachingHooks],
  tools: [MyTool],
})
class MyApp {}

@Plugin({
  name: 'audit-plugin',
  providers: [AuditHooks],
})
class AuditPlugin {}

@FrontMcp({
  info: { name: 'my-server', version: '1.0.0' },
  apps: [MyApp],
  providers: [AuditHooks],
})
export default class Server {}

@Provider({ name: 'request-trace', scope: ProviderScope.CONTEXT })
class RequestTrace {
  readonly steps: string[] = [];

  @Will('execute')
  record(ctx: FlowCtxOf<'tools:call-tool'>) {
    this.steps.push(`tool:${ctx.state.tool?.name}`);
  }
}

@Tool({ name: 'get_ticket', inputSchema: {} })
class GetTicketTool extends ToolContext {
  @Will('execute')
  async recordAccess() {
    this.logger.info('get_ticket called');
  }

  async execute() {
    return { ok: true };
  }
}

@Tool({ name: 'transfer', inputSchema: { account: z.string(), amount: z.number() } })
class TransferTool extends ToolContext {
  // Runs before the tool is authorized or its instance is built
  @ToolHook.Will('checkToolAuthorization')
  static refuseFrozen(flowCtx: FlowCtxOf<'tools:call-tool'>) {
    const account = flowCtx.state.input?.arguments?.['account'];
    if (frozenAccounts.has(String(account))) throw new UnauthorizedError('the account is frozen');
  }

  // Rewrites the arguments before the tool is looked up
  @ToolHook.Did('parseInput')
  static normalize(flowCtx: FlowCtxOf<'tools:call-tool'>) {
    const input = flowCtx.state.required.input;
    const account = String(input.arguments?.['account'] ?? '').trim();
    flowCtx.state.set('input', { ...input, arguments: { ...input.arguments, account } });
  }

  async execute({ account, amount }: { account: string; amount: number }) {
    return { account, amount };
  }
}

import { FlowCtxOf, ToolHook } from '@frontmcp/sdk';

const { Will } = ToolHook;

class InspectHooks {
  @Will('execute')
  async inspect(ctx: FlowCtxOf<'tools:call-tool'>) {
    // Flow state, typed per flow
    const { name, arguments: toolArguments } = ctx.state.required.input;

    // The flow's logger
    ctx.logger.info(`Calling ${name}`, toolArguments);

    // A provider registered on the server
    await ctx.get(AuditService).record(name);
  }
}

@Will('execute')
async validateInput(ctx: FlowCtxOf<'tools:call-tool'>) {
  // Throwing stops execution and reports error
  throw new InvalidInputError('Validation failed');
}

@Around('execute')
async errorHandler(ctx: FlowCtxOf<'tools:call-tool'>, next: () => Promise<void>) {
  try {
    await next();
  } catch (error) {
    ctx.logger.error('Execution failed', { error });
    // Rethrow to keep the failure; returning instead would handle it
    throw error;
  }
}

import {
  App,
  FlowCtxOf,
  FlowHooksOf,
  FrontMcp,
  Plugin,
  Provider,
  RateLimitError,
  Tool,
  ToolContext,
  z,
} from '@frontmcp/sdk';

const { Will, Did, Around } = FlowHooksOf('tools:call-tool');

type ToolFlow = FlowCtxOf<'tools:call-tool'>;

// Audit hook provider: the Will and Did hooks of one call share its start time through the flow instance
@Provider({ name: 'audit-hooks' })
class AuditHooks {
  private readonly startTimes = new WeakMap<ToolFlow, number>();
  private auditLog: Array<{ tool: string; timestamp: Date; duration: number }> = [];

  @Will('execute', { priority: 0 })
  async recordStart(ctx: ToolFlow) {
    this.startTimes.set(ctx, Date.now());
  }

  @Did('execute', { priority: 1000 })
  async recordEnd(ctx: ToolFlow) {
    const duration = Date.now() - (this.startTimes.get(ctx) ?? Date.now());
    const toolName = ctx.state.required.input.name;

    this.auditLog.push({
      tool: toolName,
      timestamp: new Date(),
      duration,
    });

    ctx.logger.info(`Tool ${toolName} completed in ${duration}ms`);
  }

  getAuditLog() {
    return this.auditLog;
  }
}

// Rate limiting hook
@Provider({ name: 'rate-limit-hooks' })
class RateLimitHooks {
  private calls = new Map<string, number[]>();
  private maxCallsPerMinute = 60;

  @Will('execute', { priority: 5 })
  async checkRateLimit(ctx: ToolFlow) {
    const toolName = ctx.state.required.input.name;
    const now = Date.now();
    const oneMinuteAgo = now - 60000;

    const recentCalls = (this.calls.get(toolName) || [])
      .filter(t => t > oneMinuteAgo);

    if (recentCalls.length >= this.maxCallsPerMinute) {
      throw new RateLimitError(60);
    }

    recentCalls.push(now);
    this.calls.set(toolName, recentCalls);
  }
}

// Caching hook
@Provider({ name: 'cache-hooks' })
class CacheHooks {
  private cache = new Map<string, { value: unknown; expires: number }>();
  private ttl = 60000; // 1 minute

  @Around('execute', {
    filter: (ctx) => ctx.state.tool?.metadata.annotations?.idempotentHint === true
  })
  async cacheIdempotent(ctx: ToolFlow, next: () => Promise<void>) {
    const { name: toolName, arguments: toolArguments } = ctx.state.required.input;
    const cacheKey = `${toolName}:${JSON.stringify(toolArguments)}`;
    const toolContext = ctx.state.required.toolContext;

    const cached = this.cache.get(cacheKey);
    if (cached && cached.expires > Date.now()) {
      ctx.logger.debug('Cache hit', { toolName });
      toolContext.output = cached.value;
      return;
    }

    await next();

    this.cache.set(cacheKey, {
      value: toolContext.output,
      expires: Date.now() + this.ttl,
    });
  }
}

// Plugin bundling hooks
@Plugin({
  name: 'observability',
  description: 'Audit logging, rate limiting, and caching',
  providers: [AuditHooks, RateLimitHooks, CacheHooks],
})
class ObservabilityPlugin {}

// Sample tool
@Tool({
  name: 'get_data',
  inputSchema: { key: z.string() },
  annotations: { idempotentHint: true },
})
class GetDataTool extends ToolContext {
  async execute(input: { key: string }) {
    return { data: `Value for ${input.key}` };
  }
}

// App using plugin
@App({
  name: 'data-app',
  plugins: [ObservabilityPlugin],
  tools: [GetDataTool],
})
class DataApp {}

@FrontMcp({
  info: { name: 'Observable Server', version: '1.0.0' },
  apps: [DataApp],
})
export default class ObservableServer {}