@forge-sdk/tool

import * as api from '@forge-sdk/tool';

export interface ApprovalHandler {
  /**
   * Checks whether a tool call should be approved, denied, or modified.
   *
   * @param call - The tool call to evaluate.
   * @param tier - The tool's tier classification.
   * @returns A ToolApproval indicating the decision.
   */
  check(call: ToolCall, tier: ToolTier): Promise<ToolApproval>;
}

export class AutoApprove implements ApprovalHandler {
  async check(_call: ToolCall, _tier: ToolTier): Promise<ToolApproval>;
}

export class DenyAll implements ApprovalHandler {
  constructor(reason: string);
  async check(_call: ToolCall, _tier: ToolTier): Promise<ToolApproval>;
}

export class TierBasedApproval implements ApprovalHandler {
  async check(call: ToolCall, tier: ToolTier): Promise<ToolApproval>;
}

export class ToolBuilder {
  constructor(name: string);
  description(desc: string): this;
  tier(tier: ToolTier): this;
  parameters(schema: JsonSchema): this;
  executor(executor: ToolExecutor): this;
  handler(handler: (call: ToolCall) => ToolResult | Promise<ToolResult>): this;
  build(): [ToolDefinition, ToolExecutor | undefined];
}

export const ForgeToolErrorCode /* type inferred in source */;

export type ForgeToolErrorCodeType = (typeof ForgeToolErrorCode)[keyof typeof ForgeToolErrorCode];

export class ForgeToolError extends Error {
  readonly code: ForgeToolErrorCodeType;
  readonly toolName?: string;
  static toolNotFound(name: string): ForgeToolError;
  static executionFailed(name: string, reason: string): ForgeToolError;
  static approvalDenied(name: string, reason: string): ForgeToolError;
  static schemaValidation(name: string, path: string, reason: string): ForgeToolError;
  static invalidTier(name: string, expected: string, actual: string): ForgeToolError;
  static registryError(reason: string): ForgeToolError;
}

export interface ToolExecutor {
  /** The name of the tool this executor handles. */
  readonly name: string;

  /**
   * Executes the tool with the given call arguments.
   *
   * @param call - The tool call containing the call ID, tool name, and JSON arguments.
   * @returns A ToolResult with the execution output.
   * @throws {ForgeToolError} If the tool logic fails.
   */
  execute(call: ToolCall): Promise<ToolResult>;
}

export class FnToolExecutor implements ToolExecutor {
  readonly name: string;
  constructor(
    name: string,
    handler: (call: ToolCall) => ToolResult | Promise<ToolResult>
  );
  async execute(call: ToolCall): Promise<ToolResult>;
}

export async function executeToolCall(
  call: ToolCall,
  definition: ToolDefinition,
  executor: ToolExecutor,
  approvalHandler: ApprovalHandler
): Promise<ToolResult>;

export { ForgeToolError, ForgeToolErrorCode, type ForgeToolErrorCodeType } from './error.js';

export {
  ExecutionContext,
  type TierClassification,
  classifyTier,
  tierRequiresAuthorization,
  executionContextFor,
} from './tiers.js';

export { type ToolExecutor, FnToolExecutor, executeToolCall } from './execution.js';

export { type ApprovalHandler, AutoApprove, DenyAll, TierBasedApproval } from './approval.js';

export { ToolBuilder } from './definition.js';

export { ToolRegistry } from './registry.js';

export class ToolRegistry {
  register(definition: ToolDefinition, executor: ToolExecutor): void;
  get(name: string): [ToolDefinition, ToolExecutor] | undefined;
  list(): ToolDefinition[];
  definitions(): ToolDefinition[];
  get size(): number;
  get isEmpty(): boolean;
  remove(name: string): [ToolDefinition, ToolExecutor] | undefined;
  contains(name: string): boolean;
}

export const ExecutionContext /* type inferred in source */;

export type ExecutionContext = (typeof ExecutionContext)[keyof typeof ExecutionContext];

export interface TierClassification {
  /** The name of the tool that was classified. */
  readonly toolName: string;
  /** The tool's tier classification. */
  readonly tier: ToolTier;
  /** Whether this tool requires Arsenal ACT authorization before execution. */
  readonly requiresAuthorization: boolean;
  /** The execution context (sandbox or host) for this tool. */
  readonly executionContext: ExecutionContext;
}

export function classifyTier(toolName: string, tier: ToolTier): TierClassification;

export function tierRequiresAuthorization(tier: ToolTier): boolean;

export function executionContextFor(tier: ToolTier): ExecutionContext;