import { AIError } from "../errors/ai-error.mjs";
import { Usage } from "../contracts/result/usage.type.mjs";
import { BaseReport } from "../contracts/result/base-report.type.mjs";
import { ToolConfig, ToolContext } from "../contracts/tool.contract.mjs";
import { StandardSchemaV1 } from "@standard-schema/spec";

//#region ../ai/src/tool/tool.d.ts
/**
 * Result returned by `ToolContract.invoke()`.
 *
 * **Canonical destructure:** `const { data, usage, report, error }` —
 * matches every other executable (`AgentResult`, `WorkflowResult`,
 * `SupervisorResult`) so parent agents can treat every tool dispatch
 * uniformly.
 *
 * **Shape.** `data` / `error` carry the outcome; `usage` and `report`
 * are always present. For leaf tools, `usage` is zero and `report`
 * is a framework-synthesized {@link BaseReport} (`type: "tool"`,
 * `children: []`, real timing) so parents never have to nil-check.
 * For composites wrapped via `asTool()`, `usage` and `report` mirror
 * the inner primitive's — the nested tree lives in `report.children`.
 *
 * @example
 * const result = await myTool.invoke({ city: "Cairo" });
 * if (result.error) console.error(result.error.message);
 * else console.log(result.data, result.report.duration);
 */
type ToolInvokeResult<TOutput> = {
  /** Successfully-returned output. Undefined if execution or validation failed. */data?: TOutput; /** Typed AI error produced by validation or execute(), if any. */
  error?: AIError; /** Rolled-up usage (zero for leaf tools, populated for composites). */
  usage: Usage; /** Recursive execution report — `report.children` carries nested executables. */
  report: BaseReport;
};
/**
 * A `ToolConfig` augmented with a safe `invoke()` entry point for the agent runtime.
 *
 * @example
 * const wrapped: ToolContract<{ city: string }, { temp: number }> = tool(contract);
 * const result = await wrapped.invoke({ city: "Cairo" });
 */
interface ToolContract<TInput = unknown, TOutput = unknown> extends ToolConfig<TInput, TOutput> {
  /**
   * Agent-runtime entry point. Validates raw input against the tool's schema,
   * calls execute(), catches errors, and reports duration.
   * Never throws — errors surface in the returned `error` field as
   * typed `AIError` subclasses.
   *
   * The optional second argument is a `ToolContext` (Phase 5 /
   * decisions §35) — when supplied, threaded into `execute(input, ctx)`
   * so tools can write system-only side data into `ctx.artifacts`.
   * Standalone callers may omit it; the framework supplies a
   * degraded `{ artifacts: {} }` so single-arg legacy handlers keep
   * working unchanged.
   *
   * @example
   * const result = await myTool.invoke(rawLLMArgs);
   * if (result.error) handleError(result.error);
   */
  invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>>;
}
declare function tool<TInput, TOutput>(contract: ToolConfig<TInput, TOutput>): ToolContract<TInput, TOutput>;
//#endregion
export { ToolContract, ToolInvokeResult, tool };
//# sourceMappingURL=tool.d.mts.map