Add typed Actor I/O contracts: get_input(model)

[vdusek]

Add typed, backward-compatible I/O contracts to Actor: a Pydantic-validating get_input overload, a canonical set_output, and a code-first input/output base.

Problem

get_input() -> Any (_actor.py:705) and push_data(dict | list[dict]) (_actor.py:644) are untyped; the SDK never validates against .actor/input_schema.json, and there's no notion of an output schema at all. Without typed I/O the SDK can't generate tool descriptors or validate machine-generated input before spending a paid run.

Proposed design

Backward-compatible overloads — the -> Any default is unchanged:

@overload
async def get_input(self) -> Any: ...                  # unchanged default
@overload
async def get_input(self, model: type[T]) -> T: ...    # new: validates with Pydantic

async def set_output(self, value: Any, *, model: type[BaseModel] | None = None) -> None:
    """Write a canonical OUTPUT record (KVS) — a stable place for agents to read a tool's result."""

Add a code-first ActorInput / ActorOutput base that can emit input_schema.json (single source of truth: code → schema, instead of today's schema → manual Pydantic in docs/03_guides/11_pydantic.mdx).

Acceptance criteria

• get_input(model: type[T]) -> T overload validating via Pydantic, keeping the -> Any default.
• Actor.set_output(value, *, model=None) writing a canonical OUTPUT KVS record.
• Code-first ActorInput / ActorOutput base that can emit input_schema.json.
• No existing public signature changes; untyped get_input() keeps returning Any.

Risk: Low for the read/validate overloads; medium for code→schema generation (must match the platform's input-schema dialect exactly).

[janbuchar]

Where does the OUTPUT requirement come from? I wondered about this for a long time, but it surprises me that you suggest to fix it here and now.

[vdusek]

claude made it up probably 🙁