Function build_coding_agent_metadata

libs/code/deepagents_code/config.py:1383–1464

Build the shared coding-agent-v1 trace-metadata block. Implements the `coding-agent-v1` contract (LSEN-277) for Deep Agents Code: one helper that stamps the identity block, plugin/runtime versions, turn markers, and repo/git/cwd attribution. The seven identity/version keys and `thre

(
    *,
    thread_id: str,
    turn_id: str | None,
    turn_number: int | None,
    cwd: str,
    git_branch: str | None,
    sandbox_type: str | None,
    user_id: str | None,
)

def build_coding_agent_metadata(
    *,
    thread_id: str,
    turn_id: str | None,
    turn_number: int | None,
    cwd: str,
    git_branch: str | None,
    sandbox_type: str | None,
    user_id: str | None,
) -> dict[str, Any]:
    """Build the shared coding-agent-v1 trace-metadata block.

    Implements the `coding-agent-v1` contract (LSEN-277) for Deep Agents Code:
    one helper that stamps the identity block, plugin/runtime versions, turn
    markers, and repo/git/cwd attribution. The seven identity/version keys and
    `thread_id` are always present; the optional keys whose value is unknown are
    omitted (per the contract), so callers can pass `None` for any of them.

    Because Deep Agents Code is itself the runtime — there is no separate CLI
    package — `ls_integration_version` and `ls_agent_runtime_version` both come
    from the `deepagents-code` package version (`__version__`). The underlying
    `deepagents` SDK version is surfaced separately as
    `dcode_client_deepagents_version` by `build_stream_config`.

    Scope-restricted contract keys are intentionally NOT produced here:
    `approval_policy` (root/interrupted only) and `ls_subagent_id` /
    `ls_subagent_type` (subagent only). This metadata propagates trace-wide
    through the LangGraph stream config (and, for subagents, the per-key config
    merge of langgraph#7926 / deepagents#3634), so any key placed here lands on
    every descendant run. Emitting a run-type-scoped key would therefore leak it
    onto run types outside its contract `appliesTo` set — a hard validator
    failure — and the LangGraph runtime exposes no clean per-run-type metadata
    seam to scope them. See `build_stream_config` for the full rationale.

    Args:
        thread_id: Stable conversation id; also set as top-level `thread_id`.
        turn_id: Per-turn id (uuid4 / message id), or `None`.
        turn_number: 1-based per-thread turn index, or `None`.
        cwd: Current working directory, or empty string when unavailable.
        git_branch: Current branch name, or `None`.
        sandbox_type: Sandbox provider name, or `None`/`"none"` when inactive.
        user_id: Stable pseudonymous user id, or `None`.

    Returns:
        The contract metadata dict with unknown keys omitted.
    """
    metadata: dict[str, Any] = {
        "ls_agent_kind": CODING_AGENT_KIND,
        "ls_integration": CODING_AGENT_INTEGRATION,
        "ls_agent_runtime": CODING_AGENT_RUNTIME,
        "thread_id": thread_id,
        "ls_trace_schema_version": CODING_AGENT_TRACE_SCHEMA_VERSION,
        "ls_integration_version": __version__,
        "ls_agent_runtime_version": __version__,
    }

    if turn_id:
        metadata["turn_id"] = turn_id