group_fqcd_jr/app/api/schemas/agent_runs.py

from typing import Any

from pydantic import BaseModel, ConfigDict, Field


class AgentRunCreateRequest(BaseModel):
    model_config = ConfigDict(extra="forbid")

    agent_type: str
    message: str = Field(min_length=1)
    session_id: str
    idempotency_key: str = Field(min_length=16, max_length=128)


class AgentRunAcceptedResponse(BaseModel):
    run_id: str
    trace_id: str
    status: str
    status_url: str
    events_url: str


class AgentRunAcceptedEnvelope(BaseModel):
    """`POST /api/v1/agent-runs` 的 202 响应（文档 §3.3 + §6.2）。

    文档 §6.2 明确给出的是 `{data:{run_id,trace_id,status,status_url,events_url}, meta:{trace_id}}`
    信封，§3.3 又规定"业务接口不得增加其他顶层字段"。此前这里返回的是平铺对象，接入方按
    文档取 `data.run_id` 会拿到空值——这是接入者第一步就会踩到的契约偏差，因此补齐信封。

    `data` 内的字段名与语义与改动前完全一致，客户端只是多读一层 `data`；
    `meta.trace_id` 是**本次请求**的 trace，`data.trace_id` 是运行自身的 trace（两者通常相同）。
    """

    data: AgentRunAcceptedResponse
    meta: dict[str, str]


class AgentRunStatusResponse(BaseModel):
    run_id: str
    trace_id: str
    status: str
    agent_type: str
    session_id: str
    result: dict[str, Any] | None = None
    error_code: str | None = None
    created_at: str
    completed_at: str | None = None


class AgentRunStatusEnvelope(BaseModel):
    """`GET /api/v1/agent-runs/{run_id}` 的成功响应（文档 §3.3 + §6.3）。

    单资源信封只多一层 `{data, meta}`：`data` 里的字段名与语义**与改动前完全一致**，
    客户端除多读一层 `data` 外不需要任何适配。
    """

    data: AgentRunStatusResponse
    meta: dict[str, str]