@spec actions() :: [module()]

Returns the list of actions from all attached plugins.

@spec agent_id(run_id()) :: String.t()

Returns the stable Jido agent id for a workflow run.

@spec applied_runnable_keys(Jido.Agent.t()) :: MapSet.t(String.t())

Returns runnable keys whose dispatch results have been applied to the run.

@spec apply_pending_results(
  storage_config(),
  Jido.Agent.t(),
  Jido.Agent.t(),
  keyword()
) ::
  {:ok, apply_many_update()} | {:error, term()}

Applies every completed dispatch result that is still pending for the workflow run.

This is the restart recovery boundary for lost live wakeups: both agents can be rebuilt from durable journals, pending completed attempts can be derived again, and each missing workflow application is appended to the run thread with the current workflow-agent revision as the append fence.

@spec apply_result(
  storage_config(),
  Jido.Agent.t(),
  Squidie.Runtime.DispatchProtocol.ActionAttempt.t(),
  keyword()
) :: {:ok, apply_update()} | {:error, term()}

Records that a durable dispatch completion has been applied to the workflow run.

The dispatch attempt must be completed, belong to the workflow agent's run, and reference a planned runnable that has not already been applied. Stale workflow-agent callers race at the run-thread append boundary and receive {:error, :conflict} from the journal.

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

Returns the union of all capabilities from all mounted plugin instances.

Capabilities are atoms describing what the agent can do based on its mounted plugins.

Example

MyAgent.capabilities()
# => [:messaging, :channel_management, :chat, :embeddings]

@spec category() :: String.t() | nil

Returns the agent's category.

@spec cmd(Jido.Agent.t(), Jido.Agent.action()) :: Jido.Agent.cmd_result()

Execute actions against the agent: (agent, action) -> {agent, directives}

This is the core operation. Actions modify state and may perform required work; directives are runtime-owned external effects. Execution is delegated to the configured strategy (default: Direct).

Action Formats

• MyAction - Action module with no params
• {MyAction, %{param: 1}} - Action with params
• {MyAction, %{param: 1}, %{context: data}} - Action with params and context
• {MyAction, %{param: 1}, %{}, [timeout: 1000]} - Action with opts
• %Instruction{} - Full instruction struct
• [...] - List of any of the above (processed in sequence)

Options

The optional third argument opts is a keyword list merged into all instructions:

• :timeout - Maximum time (in ms) for each action to complete
• :max_retries - Maximum retry attempts on failure
• :backoff - Initial backoff time in ms (doubles with each retry)

Examples

{agent, directives} = Squidie.Runtime.WorkflowAgent.cmd(agent, MyAction)
{agent, directives} = Squidie.Runtime.WorkflowAgent.cmd(agent, {MyAction, %{value: 42}})
{agent, directives} = Squidie.Runtime.WorkflowAgent.cmd(agent, [Action1, Action2])

# With per-call options (merged into all instructions)
{agent, directives} = Squidie.Runtime.WorkflowAgent.cmd(agent, MyAction, timeout: 5000)

@spec description() :: String.t() | nil

Returns the agent's description.

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

Returns the agent's name.

@spec new(keyword() | map()) :: Jido.Agent.t()

Creates a new agent with optional initial state.

The agent is fully initialized including strategy state. For the default Direct strategy, this is a no-op. For custom strategies, any state initialization is applied (but directives are only processed by AgentServer).

Examples

agent = Squidie.Runtime.WorkflowAgent.new()
agent = Squidie.Runtime.WorkflowAgent.new(id: "custom-id")
agent = Squidie.Runtime.WorkflowAgent.new(state: %{counter: 10})

@spec pending_dispatches(Jido.Agent.t(), Jido.Agent.t()) :: [map()]

Lists planned runnables that still need dispatch scheduling.

@spec pending_results(Jido.Agent.t(), Jido.Agent.t()) :: [
  Squidie.Runtime.DispatchProtocol.ActionAttempt.t()
]

Lists completed dispatch results that still need workflow application.

@spec planned_runnable_keys(Jido.Agent.t()) :: [String.t()]

Returns runnable keys planned by the workflow thread.

@spec planned_runnables(Jido.Agent.t()) :: [map()]

Returns planned runnable payloads in deterministic order.

@spec plugin_config(module() | {module(), atom()}) :: map() | nil

Returns the configuration for a specific plugin.

Accepts either a module or a {module, as_alias} tuple for multi-instance plugins.

@spec plugin_instances() :: [Jido.Plugin.Instance.t()]

Returns the list of plugin instances attached to this agent.

@spec plugin_routes() :: [{String.t(), module(), integer()}]

Returns the expanded and validated plugin routes.

@spec plugin_schedules() :: [
  Jido.Plugin.Schedules.schedule_spec() | Jido.Agent.Schedules.schedule_spec()
]

Returns the expanded plugin and agent schedules.

@spec plugin_specs() :: [Jido.Plugin.Spec.t()]

Returns the list of plugin specs attached to this agent.

@spec plugin_state(Jido.Agent.t(), module() | {module(), atom()}) :: map() | nil

Returns the state slice for a specific plugin.

Accepts either a module or a {module, as_alias} tuple for multi-instance plugins.

@spec plugins() :: [module()]

Returns the list of plugin modules attached to this agent (deduplicated).

For multi-instance plugins, the module appears once regardless of how many instances are mounted.

Example

MyAgent.plugins()
# => [MyApp.SlackPlugin, MyApp.OpenAIPlugin]

@spec put_checkpoint(storage_config(), Jido.Agent.t(), keyword()) ::
  :ok | {:error, term()}

Stores the current workflow projection as a checkpoint for faster rebuilds.

@spec rebuild(storage_config(), run_id()) :: {:ok, Jido.Agent.t()} | {:error, term()}

Rebuilds a workflow agent for one run from its durable run thread.

@spec schedule_pending_dispatches(
  storage_config(),
  Jido.Agent.t(),
  Jido.Agent.t(),
  keyword()
) ::
  {:ok, dispatch_schedule_update()} | {:error, term()}

Schedules every planned runnable that is missing from the dispatch journal.

This is the restart recovery boundary for the crash window between durable workflow planning and durable dispatch scheduling. The workflow agent derives missing planned runnables from the run-thread projection, and the dispatch agent appends their :attempt_scheduled entries with its current dispatch thread revision as the append fence.

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

Returns the merged schema (base + plugin schemas).

@spec set(Jido.Agent.t(), map() | keyword()) :: Jido.Agent.agent_result()

Updates the agent's state by merging new attributes.

Uses deep merge semantics - nested maps are merged recursively.

Examples

{:ok, agent} = Squidie.Runtime.WorkflowAgent.set(agent, %{status: :running})
{:ok, agent} = Squidie.Runtime.WorkflowAgent.set(agent, counter: 5)

@spec signal_types() :: [String.t()]

Returns all expanded route signal types from plugin routes.

These are the fully-prefixed signal types that the agent can handle.

Example

MyAgent.signal_types()
# => ["slack.post", "slack.channels.list", "openai.chat"]

@spec status(Jido.Agent.t()) :: atom()

Returns the workflow projection status.

@spec strategy() :: module()

Returns the execution strategy module for this agent.

@spec strategy_opts() :: keyword()

Returns the strategy options for this agent.

@spec strategy_snapshot(Jido.Agent.t()) :: Jido.Agent.Strategy.Snapshot.t()

Returns a stable, public view of the strategy's execution state.

Use this instead of inspecting agent.state.__strategy__ directly. Returns a Jido.Agent.Strategy.Snapshot struct with:

• status - Coarse execution status
• done? - Whether strategy reached terminal state
• result - Main output if any
• details - Additional strategy-specific metadata

@spec tags() :: [String.t()]

Returns the agent's tags.

@spec validate(
  Jido.Agent.t(),
  keyword()
) :: Jido.Agent.agent_result()

Validates the agent's state against its schema.

Options

• :strict - When true, only schema-defined fields are kept (default: false)

Examples

{:ok, agent} = Squidie.Runtime.WorkflowAgent.validate(agent)
{:ok, agent} = Squidie.Runtime.WorkflowAgent.validate(agent, strict: true)

@spec vsn() :: String.t() | nil

Returns the agent's version.