@spec agent(keyword() | map()) :: {:ok, Jidoka.Agent.Spec.t()} | {:error, term()}

Builds a validated agent definition.

Use this when constructing an agent from data at runtime, in tests, or from tooling that does not use the Spark DSL. The returned Agent.Spec is immutable definition data: it contains the agent id, model, instructions, controls, operations, context schema, result schema, and memory policy. It is not a process, session, provider client, or live capability bundle.

@spec agent!(keyword() | map()) :: Jidoka.Agent.Spec.t()

Builds a validated agent definition and raises when validation fails.

This is useful for compile-time examples, tests, and boot-time application setup where invalid agent data should fail fast.

@spec await(
  Jidoka.Chat.Request.t() | Jidoka.Stream.t(),
  keyword()
) :: term()

Waits for a chat request or stream to finish.

This returns the same normalized result shape as chat/3, including session results when the request target is a Jidoka.Session.

@spec await_agent(
  server_ref(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Awaits terminal Jido status for a process-hosted Jidoka agent.

This helper is only for process-hosted agents started through Jido. It is not needed for direct turn/3 or chat/3 calls.

@spec chat(chat_input(), String.t(), runtime_opts()) ::
  {:ok, String.t()}
  | {:ok, Jidoka.Session.t(), String.t()}
  | {:hibernate, Jidoka.Runtime.AgentSnapshot.t()}
  | {:hibernate, Jidoka.Session.t(), Jidoka.Runtime.AgentSnapshot.t()}
  | {:error, term()}

Runs one turn and returns final assistant text.

chat/3 is the ergonomic path for product code that only needs the final assistant answer. For caller-managed sessions, the updated session is returned alongside the text so durable state is not lost.

Use turn/3 when callers need the full Turn.Result, event journal, agent state, operation results, stream events, or hibernation snapshot.

@spec chat_async(chat_input(), String.t(), runtime_opts()) ::
  {:ok, Jidoka.Chat.Request.t()} | {:error, term()}

Starts one chat request asynchronously and returns a request handle.

This is the UI-friendly companion to chat/3. Pass stream: true to stream request-scoped Jidoka.Event values to the caller mailbox while the task is running. Use stream/2 to enumerate those events and await/2 to collect the final normalized chat result.

@spec error_to_map(term()) :: map()

Converts a Jidoka error or arbitrary error term into a display-oriented map.

Values likely to contain credentials are sanitized before being returned.

@spec export(
  module() | Jidoka.Agent.Spec.t() | Jidoka.Turn.Plan.t() | keyword() | map(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Exports an agent definition to a portable JSON or YAML document string.

Export writes data that can be passed back into import/2. Runtime-only values are not serialized. If a context or result schema is present, provide a registry ref with context_schema_ref: or result_schema_ref: so the exported document can be resolved by the importing application.

@spec format_error(term()) :: String.t()

Formats a Jidoka error or arbitrary error term for display.

This is intended for UI/logging boundaries that need a concise message rather than a full Splode error struct.

@spec handoff(String.t()) :: Jidoka.Handoff.OwnerStore.owner() | nil

Returns the current handoff owner for a conversation, if one has been recorded.

Handoffs are durable routing data. They indicate which agent should own future turns for a conversation after a handoff operation succeeds.

@spec import(
  String.t(),
  keyword()
) :: {:ok, Jidoka.Agent.Spec.t()} | {:error, term()}

Imports a JSON or YAML agent document string into Jidoka.Agent.Spec.

Import is intentionally string-only at the facade. File loading, registries, and trust boundaries belong to the caller; Jidoka owns parsing, normalization, schema validation, and data-safe conversion into Agent.Spec.

@spec inspect(
  term(),
  keyword()
) :: term()

Returns a stable inspection view for an agent, plan, turn, snapshot, journal, or other Jidoka data value.

inspect/2 is the human-facing debug surface. It favors grouped, readable maps over raw structs.

@spec normalize_error(term(), keyword() | map()) :: Exception.t()

Normalizes any error term into a Splode-backed Jidoka.Error exception.

Prefer returning normalized errors from facade boundaries so callers see a consistent error shape even when the underlying cause came from a provider, store, control, or runtime capability.

@spec plan(plan_input()) :: {:ok, Jidoka.Turn.Plan.t()} | {:error, term()}

Compiles an agent definition into executable turn data.

Turn.Plan is still pure data. It contains no live capabilities, processes, provider clients, or credentials. Use it when you want to inspect or cache the normalized runtime contract before executing a turn.

@spec plan!(plan_input()) :: Jidoka.Turn.Plan.t()

Compiles an agent definition into executable turn data and raises on failure.

This mirrors plan/1, but is intended for setup paths where invalid agent data should stop execution immediately.

@spec preflight(plan_input() | module(), request_input(), runtime_opts()) ::
  {:ok, Jidoka.Inspection.Preflight.t()} | {:error, term()}

Assembles the prompt for a turn without calling an LLM or tools.

Use preflight to debug prompt assembly, tool metadata, memory injection, and request normalization before running live effects.

@spec project(term()) :: term()

Projects a Jidoka data contract into a stable inspection map.

project/1 is the data-facing companion to inspect/2. It returns compact, deterministic maps that are useful for tests, golden files, traces, and UI rendering.

@spec reset_handoff(String.t()) :: :ok

Clears the current handoff owner for a conversation.

Use this when an application wants to return routing control to its default agent selection logic.

@spec resume(
  Jidoka.Runtime.AgentSnapshot.t() | keyword() | map() | String.t(),
  runtime_opts()
) ::
  run_result()

Resumes from a durable agent snapshot.

The snapshot may be an AgentSnapshot struct, map-shaped snapshot data, or the opaque string returned by Jidoka.Runtime.AgentSnapshot.serialize/1. Resume continues through the same harness boundary as turn/3, so callers provide the same runtime capabilities plus any required approval response.

@spec session(Jidoka.Session.agent_input(), keyword() | String.t()) ::
  {:ok, Jidoka.Session.t()} | {:error, term()}

Starts a durable Jidoka session for an agent, spec, or plan.

A session stores semantic conversation state, the latest turn result, hibernation snapshots, and replay data. Use it when a caller needs durable multi-turn behavior instead of a one-off turn/3.

@spec session(Jidoka.Session.agent_input(), String.t(), keyword()) ::
  {:ok, Jidoka.Session.t()} | {:error, term()}

Starts a durable Jidoka session with an explicit session id.

Prefer this arity when the caller already has an application-level conversation id and wants Jidoka session state to be addressable by that id.

@spec start_agent(
  module() | Jido.Agent.t(),
  keyword()
) :: DynamicSupervisor.on_start_child()

Starts a Jidoka DSL agent under the default Jidoka.Jido process tree.

The started process is a Jido.AgentServer; incoming Jidoka turn signals are routed to the Runic harness and the result is written back to Jido agent state.

@spec stop_agent(
  pid() | String.t(),
  keyword()
) :: :ok | {:error, :not_found}

Stops a process-hosted Jidoka agent by pid or registered Jido agent id.

@spec stream(
  Jidoka.Chat.Request.t(),
  keyword()
) :: Jidoka.Stream.t()

Builds a request-scoped event stream for an async chat request.

The stream consumes events already emitted to the caller mailbox and stops at :turn_finished, :turn_failed, or :turn_hibernated.

@spec turn(runnable_input(), request_input(), runtime_opts()) :: run_result()

Runs one agent turn through the Jidoka Runic spine.

This is the stable core runtime entrypoint. It accepts an Agent.Spec or Turn.Plan, normalizes the request, runs pure workflow planning, interprets external effects through explicit runtime capabilities, and returns a typed result or snapshot.

Use turn/3 for deterministic tests with injected capabilities, live ReqLLM calls, process-hosted agents, controls, tools, hibernation, streaming, and trace/event inspection.

@spec whereis(
  String.t(),
  keyword()
) :: pid() | nil

Looks up a running Jidoka agent process by registered Jido agent id.

This is intentionally a process-hosting helper. It does not build specs, create sessions, or run turns.