feat(sdk): add reasoning effort to the Core Agent

[xTRam1]

Summary

Lets SDK callers opt into GPT-5.2's reasoning levels on the Core Agent — none / low / medium / high — mirroring the picker the web UI added on v2 of the agent step. The wire field is the same reasoningMode on NaradaGenerationRequest that the backend (caddie/cloud/src/ecs/ai/agents/core_agent.py:46-66) already honors only for CoreAgent; this PR just exposes it on the SDK surface.

⚠️ Stacked on top of #87. Base branch is lerdogan/python-agent-trace, not main. Once #87 merges, GitHub auto-rebases this onto main.

What changes

New enum in narada-core

# packages/narada-core/src/narada_core/models.py
class ReasoningEffort(StrEnum):
    """Amount of reasoning the Core Agent applies before responding."""
    NONE = "none"
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

Re-exported from the narada and narada-pyodide package roots so callers write:

from narada import Agent, ReasoningEffort

agent() and dispatch_request() gain reasoning=

The new keyword serializes to body["reasoningMode"] only when set — absent on the wire when None, so older backends without the field keep working.

response = await window.agent(
    prompt="Prove sqrt(2) is irrational.",
    agent=Agent.CORE_AGENT,
    reasoning=ReasoningEffort.HIGH,
)

Type-level enforcement

The user asked for "a typing scheme that is enforced by typing that the user cannot pass in reasoning if the agent type is not CoreAgent". Two paired @overload signatures encode it:

• One overload requires agent: Literal[Agent.CORE_AGENT] and accepts reasoning: ReasoningEffort | None = None.
• The other accepts the wider agent: Agent | str = Agent.OPERATOR and has no reasoning parameter.

So this fails Pyright's overload match:

await window.agent(
    prompt="x",
    agent=Agent.OPERATOR,
    reasoning=ReasoningEffort.HIGH,  # Pyright: No overload matches this call
)

The runtime ValueError in dispatch_request() covers the path where users pass agent="..." as a string (overload narrowing doesn't reach into string-form), and any caller without a type checker:

raise ValueError(
    "`reasoning` is only supported with `agent=Agent.CORE_AGENT` "
    f"(got agent={agent!r})"
)

Internal forwarding pyright: ignores

The agent() impl forwards to dispatch_request(), but the impl signature is wider than any single overload (agent: Agent | str, reasoning: ReasoningEffort | None, output_schema: type[BaseModel] | None). Two narrow pyright: ignore[reportCallIssue] / [reportArgumentType] comments on the inner forward line — the public agent() overloads above already give callers correct return-type narrowing, so the bypass is on a single internal hop, not the user-facing API. Comments explain why inline.

Tests

packages/narada-pyodide/tests/test_reasoning.py — 8 new tests:

• Body wiring (3): assert reasoningMode is present in the posted JSON when reasoning is set, absent when None, and that each of the four levels round-trips as the expected lowercase string.
• Runtime validation (3): dispatch_request() and agent() both raise ValueError with a clear message when reasoning is paired with a non-CoreAgent enum, and the string-agent bypass path is covered too.
• Enum (2): values match the backend Literal["none","low","medium","high"]; StrEnum JSON-encodes inline.

The pyodide package owns the runnable test harness in this repo today; the impl in the sibling narada package shares the same body wiring and runtime check, so coverage here exercises both paths.

Version bumps (coupled)

• narada-core: 0.0.18 → 0.0.19
• narada-pyodide: 0.0.45a2 → 0.0.46a1
• narada: 0.1.43 → 0.1.44

The bumps cascade because all three packages co-import narada-core, and any caller pulling the new ReasoningEffort symbol needs the matching pin. Aligned with the bump pattern from #87.

Test plan

Local verification (done):

• uv sync — workspace builds cleanly with the new versions
• uv pip uninstall narada && uv run --package narada-pyodide pytest packages/narada-pyodide/tests/ — 67 passed (8 new + 59 existing); follows the pattern in packages/narada-pyodide/tests/README.md
• uvx pyright --pythonpath .venv/bin/python --pythonversion 3.12 packages/narada/src/narada/window.py packages/narada-pyodide/src/narada/window.py — same error count as origin/lerdogan/python-agent-trace baseline (7, all pre-existing)
• uv run ruff format --check packages/ — clean
• uv run ruff check packages/ — clean
• Smoke import check: from narada import Agent, ReasoningEffort and Agent.CORE_AGENT both resolve

Staging verification (pending):

• Publish all three packages to PyPI (narada-core@0.0.19, narada-pyodide@0.0.46a1, narada@0.1.44) after merge
• Run an end-to-end script from a Pyodide environment with reasoning=ReasoningEffort.HIGH against staging Core Agent; verify the observability dashboard shows the reasoning mode and OpenAI token counts include reasoning tokens

Example

from narada import Agent, Narada, ReasoningEffort

narada = Narada()
window = narada.open_local_window()

response = await window.agent(
    prompt="Solve this calculus problem step by step.",
    agent=Agent.CORE_AGENT,
    reasoning=ReasoningEffort.HIGH,
    timeout=120,
)
print(response.text)

This will hit the backend's CoreAgent.resolve_llm_options() path (caddie/cloud/src/ecs/ai/agents/core_agent.py:46-66), which builds an OpenAI Responses API call with reasoning={"effort": "high", "summary": "auto"}. The token-based credit pricing already includes reasoning tokens, so no usage-tracking changes were needed.