Jidoka.AgentView behaviour (Jidoka v0.8.0-beta.1)

Surface-neutral UI projection contract for a Jidoka agent.

AgentView is not a Phoenix view and does not render HTML. It is a small application-facing projection that LiveView, CLI examples, channels, tests, or jobs can use to keep UI state separate from the durable agent runtime.

The struct is projection-only. It stores no pid, transcript persistence, provider client, process state, or adapter data.

Summary

Types

input()

status()

t()

Callbacks

agent_id(input)

agent_module(input)

conversation_id(input)

prepare(input)

runtime_context(input)

Functions

after_turn(view, arg)

Applies a Jidoka runtime result to view data.

apply_event(view, event)

Applies a streamed Jidoka runtime event to view data.

before_turn(view, message)

Applies optimistic user-message state before an agent turn starts.

default_agent_id(agent, conversation_id)

Derives a runtime agent id from an agent module and conversation id.

default_conversation_id(input)

Derives a conversation id from keyword, atom-key map, or string-key map input.

default_runtime_context(input, conversation_id)

Derives default runtime context from a conversation id.

initial(view_module, input \\ %{}, opts \\ [])

Builds the initial projection for a view module and input.

lifecycle_hooks()

Returns lifecycle hook names supported by the AgentView contract.

new(attrs \\ %{})

Builds an AgentView struct from attributes.

new!(attrs \\ %{})

Builds an AgentView struct from attributes and raises on invalid input.

normalize_id(value, default \\ "default")

Normalizes arbitrary text into a stable lower-snake id.

request_id()

Generates a request id suitable for UI-initiated turns.

run(view_module, view, message, opts \\ [])

Runs one turn for a view module and maps the runtime result back into view data.

schema()

Returns the Zoi schema for AgentView.

visible_messages(view)

Returns visible messages for a view.

Types

input()

@type input() :: term()

status()

@type status() :: :idle | :running | :error | :interrupted | :handoff

t()

@type t() :: %Jidoka.AgentView{
  agent_id: binary(),
  conversation_id: binary(),
  error: nil | nil | any(),
  error_text: nil | nil | binary(),
  events: [map()],
  metadata: map(),
  outcome: nil | nil | any(),
  runtime_context: map(),
  status: (:idle | :running | :error | :interrupted | :handoff) | binary(),
  streaming_message: nil | nil | map(),
  visible_messages: [map()]
}

Callbacks

agent_id(input)

@callback agent_id(input()) :: String.t()

agent_module(input)

@callback agent_module(input()) :: module() | Jidoka.Agent.Spec.t() | Jidoka.Turn.Plan.t()

conversation_id(input)

@callback conversation_id(input()) :: String.t()

prepare(input)

@callback prepare(input()) :: :ok | {:error, term()}

runtime_context(input)

@callback runtime_context(input()) :: map()

Functions

after_turn(view, arg)

@spec after_turn(t(), Jidoka.run_result()) :: t()

Applies a Jidoka runtime result to view data.

apply_event(view, event)

@spec apply_event(t(), Jidoka.Event.t() | map()) :: t()

Applies a streamed Jidoka runtime event to view data.

Content deltas update streaming_message; non-delta events are appended to events as compact debug projections.

before_turn(view, message)

@spec before_turn(t(), String.t()) :: t()

Applies optimistic user-message state before an agent turn starts.

default_agent_id(agent, conversation_id)

@spec default_agent_id(term(), String.t()) :: String.t()

Derives a runtime agent id from an agent module and conversation id.

default_conversation_id(input)

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

Derives a conversation id from keyword, atom-key map, or string-key map input.

default_runtime_context(input, conversation_id)

@spec default_runtime_context(term(), String.t()) :: map()

Derives default runtime context from a conversation id.

initial(view_module, input \\ %{}, opts \\ [])

@spec initial(module(), input(), keyword()) :: {:ok, t()} | {:error, term()}

Builds the initial projection for a view module and input.

lifecycle_hooks()

@spec lifecycle_hooks() :: [atom()]

Returns lifecycle hook names supported by the AgentView contract.

new(attrs \\ %{})

@spec new(keyword() | map()) :: {:ok, t()} | {:error, term()}

Builds an AgentView struct from attributes.

new!(attrs \\ %{})

@spec new!(keyword() | map()) :: t()

Builds an AgentView struct from attributes and raises on invalid input.

normalize_id(value, default \\ "default")

@spec normalize_id(term(), String.t()) :: String.t()

Normalizes arbitrary text into a stable lower-snake id.

request_id()

@spec request_id() :: String.t()

Generates a request id suitable for UI-initiated turns.

run(view_module, view, message, opts \\ [])

@spec run(module(), t(), String.t(), keyword()) :: t()

Runs one turn for a view module and maps the runtime result back into view data.

schema()

@spec schema() :: Zoi.schema()

Returns the Zoi schema for AgentView.

visible_messages(view)

@spec visible_messages(t()) :: [map()]

Returns visible messages for a view.