/**
 * Agent 业务模块接入规范 PR-A — 类型定义（registry 子目录）。
 *
 * 本文件是业务模块 import 的**唯一类型入口**：
 *   import { AgentContext, AgentToolResult, ToolDescriptor } from '@modules/agent/registry';
 *
 * 跟现有 backend/src/modules/agent/tools/tool.types.ts 的命名映射:
 *   - ToolInvocation → AgentContext + input (上下文 + 输入拆分)
 *   - ToolResult     → AgentToolResult (语义重命名,字段不变)
 *   - ToolDescriptor → ToolDescriptor (不变,直接 re-export)
 *
 * v1.0 暂时复用 tools/tool.types.ts 的底层类型,避免引入并行类型体系;
 * 30 工具迁完后(PR-B 范围),tool.types.ts 整体迁移到 registry/types.ts,旧路径 deprecate。
 *
 * 详 docs/standards/21-agent-business-module-integration.md §2 / §6.3。
 */

import type {
  ToolDescriptor as LegacyToolDescriptor,
  ToolInvocation as LegacyToolInvocation,
  ToolResult as LegacyToolResult,
} from '../tools/tool.types';

/**
 * Agent 调用业务方法时携带的上下文(v1.0 严格 6 字段;扩展条件见 standards/21 §3.3 + §9)。
 *
 * 业务方法签名约定:
 *   async <name>ForAgent(input: <DTO>, ctx: AgentContext): Promise<<ResultDTO>>
 *
 * 缺字段(locale / permissionMode / planMode / permissions / dept+region)由业务方法
 * 通过 ctx.sessionId 二次查 session 自行补齐;升级触发条件详 standards/21 §9。
 */
export interface AgentContext {
  readonly userId: string;
  readonly organizationId: string;
  readonly surface: 'web' | 'desktop' | 'mobile' | 'teams' | 'cli';
  readonly sessionId: string;
  readonly turnId: string;
  readonly trace: { traceId: string };
}

/**
 * 业务方法直接返回的结果类型(业务方法 return,包装层负责转 AgentToolResult)。
 *
 * 注: 业务方法**不应直接构造 ok=false / errorMessage**, 通过 throw NestJS HttpException
 * 让包装层异常三档接管(详 standards/21 §3.6 + §1.3 + PR-A 后续包装层实现)。
 */
export interface AgentToolResult {
  readonly ok: boolean;
  readonly output?: unknown;
  readonly errorMessage?: string;
}

/**
 * ToolDescriptor — 工具元数据契约(直接 re-export 现网类型,字段语义不变)。
 *
 * v1.0 字段:
 *   - name: snake_case <domain>_<action> 两段制
 *   - description: 人读描述(LLM tool-use prompt)
 *   - inputSchema: 扁平 3 类型 (string/number/boolean) + JSON.parse 过渡 (详 §4)
 *   - availability.surface/permissions/requiredCapabilities
 *   - writeAction / controlTool / dispatchKey
 *
 * v1.1 拟加字段 (升级触发详 standards/21 §9):
 *   - destructive (强制二次确认 + sensitive_fields redact)
 *   - maxBatchSize (destructive 批量限制)
 */
export type ToolDescriptor = LegacyToolDescriptor;

/**
 * @AgentTool() 装饰器参数 — 业务方法上贴的元数据声明。
 *
 * 跟 ToolDescriptor 同形态,但语义不同:
 *   - ToolDescriptor 是 ToolRegistry 内部的运行时元数据
 *   - AgentToolMetadata 是装饰器收集的"业务方法 → tool 映射"声明
 *
 * 包装层在启动期把 AgentToolMetadata + service 实例 + 方法名 → 拼出 ToolDescriptor。
 */
export type AgentToolMetadata = ToolDescriptor;

/**
 * Legacy 类型再导出 — 业务模块**禁止**直接 import,仅用于 registry 内部迁移期。
 * @internal
 */
export type LegacyToolInvocationType = LegacyToolInvocation;
export type LegacyToolResultType = LegacyToolResult;