import type { z } from "zod";

import type { JsonValue } from "../domain/jsonValue.js";
import type { ToolEffects } from "./toolEffects.js";

/** Caller-visible MCP execution hints. */
interface ToolAnnotations {
  readonly readOnlyHint: boolean;
  readonly destructiveHint: boolean;
  readonly idempotentHint: boolean;
  readonly openWorldHint: boolean;
}

/** One validated example request for an MCP tool contract. */
export interface ToolExample {
  readonly title: string;
  readonly input: Readonly<Record<string, JsonValue>>;
}

/** Canonical adapter families responsible for public MCP tools. */
export const TOOL_KINDS = [
  "official-proxy",
  "enhanced",
  "native-provider",
  "artifact-provider",
  "managed-provider",
  "android-provider",
  "firmware-provider",
  "browser-provider",
  "electron-provider",
  "runtime-provider",
  "application",
  "session",
] as const;

/** Adapter family responsible for implementing a public MCP tool. */
export type ToolKind = (typeof TOOL_KINDS)[number];

/** Single source of truth for a public MCP tool. */
export interface ToolContract<
  Name extends string = string,
  InputSchema extends z.ZodType<Readonly<Record<string, unknown>>> = z.ZodType<
    Readonly<Record<string, unknown>>
  >,
  OutputSchema extends z.ZodType<Readonly<Record<string, unknown>>> = z.ZodType<
    Readonly<Record<string, unknown>>
  >,
> {
  readonly name: Name;
  readonly title: string;
  readonly description: string;
  readonly kind: ToolKind;
  readonly inputSchema: InputSchema;
  readonly outputSchema: OutputSchema;
  readonly effects: ToolEffects;
  readonly annotations: ToolAnnotations;
  readonly examples: readonly ToolExample[];
}