SDK / ctx contract

Runtime context passed to every tool and every workflow.

The attributes below are the whole surface the code sees, and their reach is not uniform: ctx.workspace, ctx.notify and ctx.stt are None on every binary this project ships, and ctx.mail raises outside the desktop application. Each service page states its own reach. Use type hints to get IDE autocomplete::

@tool("greet", "Greet a known user.", action="read_personal")
async def greet(ctx: Ctx, name: str) -> dict:
    user = await ctx.memory.recall(f"user.{name}")
    ...

Services

Service	Type	Summary
ctx.llm	LlmProxy	ctx.llm - LLM backend access.
ctx.memory	MemoryInterface	Tri-mode memory: episodic events, semantic key-value, procedural triggers.
ctx.tools	ToolProxy	Tool invocation surface - native registry + MCP routing.
ctx.mail	MailInterface	Durable, at-least-once inter-agent messaging surface.
ctx.datasources	DatasourcesInterface	Runtime access to the YAML datasources the context was given.
ctx.templates	TemplatesInterface	Runtime Jinja2 template rendering.
ctx.secrets	SecretsInterface	Read-only access to the credentials the context was granted.
ctx.events	EventsInterface	Public typed events for streaming, ReAct observability, error reporting.
ctx.logger	Logger	ctx.logger - structured logging via stdlib logging.
ctx.profile	ProfileInterface | None	User profile surface.
ctx.workspace	WorkspaceContext	Snapshot of the workspace at task start.
ctx.stt	SttInterface	Audio transcription surface backed by apollia-stt.
ctx.notify	NotifyInterface	Notification surface (desktop, webhook, future channels).
ctx.budget	BudgetView	Runtime step budget tracking, read-only from the agent's perspective.
ctx.is_resumed	bool	True when this run resumes a task that paused on a human.
ctx.input_response	InputResponse | None	The operator's response to the pause being resumed, None on a first run. See apollia.hitl.

See also Content types and helpers for the multi-modal message shapes.