/**
 * Shared tool types
 *
 * Return format aligned with OpenClaw SDK's AgentToolResult:
 * @see https://docs.openclaw.ai (Plugin SDK → Building Plugins)
 * @see docs/reference/openclaw/v2026.3.23/dist/plugin-sdk/src/agents/tools/common.d.ts
 */

export interface ToolParams {
  [key: string]: unknown;
}

/** SDK-compatible tool result (matches AgentToolResult structure) */
export interface ToolResult {
  content: Array<{ type: 'text'; text: string }>;
  /** Optional details for rich media. Matches OpenClaw AgentToolResult<TDetails>. */
  details?: {
    media?: { mediaUrls: string[] };
    [key: string]: unknown;
  };
}

export type ToolUpdateCallback = (partialResult: ToolResult) => void;

export interface ToolDescriptor {
  name: string;
  label: string;
  description: string;
  parameters: {
    type: 'object';
    properties: Record<string, {
      type: string;
      description: string;
      enum?: string[];
      default?: unknown;
    }>;
    required: string[];
  };
  /**
   * Execute the tool.
   *
   * OpenClaw runtime usually calls:
   *   tool.execute(toolCallId, params, signal, onUpdate)
   *
   * Older adapters used:
   *   tool.execute(toolCallId, params, onUpdate, ctx, signal)
   *
   * The wider signature lets streaming tools normalize both shapes while
   * existing 2-param tools continue to work unchanged.
   *
   * @see docs/reference/openclaw/v2026.3.23/dist/pi-embedded-CswW9luA.js L169823
   */
  execute: (
    _id: unknown,
    params: ToolParams,
    signalOrUpdate?: AbortSignal | ToolUpdateCallback,
    onUpdateOrContext?: ToolUpdateCallback | unknown,
    legacySignal?: AbortSignal,
  ) => Promise<ToolResult>;
}

export type ToolFactory = () => ToolDescriptor;

/** Helper: create a successful text result in SDK format */
export function toolResult(text: string): ToolResult {
  return { content: [{ type: 'text', text }] };
}