One-shot requests

What you will learn

This notebook covers the smallest useful Jido.Harness workflow: inspect the registered providers, perform a non-billable readiness check, and make one blocking request.

By the end you will have:

• inspected normalized provider metadata and readiness;
• made one provider request;
• received a Jido.Harness.RunResult instead of provider-specific JSON;
• inspected the canonical event types behind the final response.

Read the getting-started guide and normalization guide for the corresponding API contracts.

The final request invokes a real provider CLI and may consume API or subscription usage. Review provider, prompt, and cwd before evaluating that cell.

Install the local package

Open this notebook from the source checkout with Elixir 1.19 or a compatible later version. The relative dependency path uses its saved location. Configure the Livebook runtime's PATH before starting provider cells; see Runtime environment.

Mix.install([
  {:jido_harness, path: Path.expand("../..", __DIR__)}
])

defmodule JidoHarnessLivebook do
  def completed!({:ok, %{status: :completed} = result}), do: result

  def completed!({:ok, result}) do
    raise result.error || "provider run finished with status #{inspect(result.status)}"
  end

  def completed!({:error, %_{} = error}), do: raise(error)
  def completed!({:error, error}), do: raise("provider run failed: #{inspect(error)}")
end

Choose a provider and request

Edit these values before continuing. The timeout on Jido.Harness.run/3 bounds the caller's wait; it does not kill a run if the wait expires.

provider = :codex
cwd = Path.expand("../..", __DIR__)
prompt = "Reply with exactly: harness-ready"
runtime_timeout_ms = 300_000
await_timeout = 320_000

%{provider: provider, cwd: cwd, prompt: prompt, runtime_timeout_ms: runtime_timeout_ms, await_timeout: await_timeout}

Discover capabilities

providers/0 is local metadata. status/1 checks installation, version, authentication evidence, normalized capabilities, and ACP executable availability without sending a prompt.

Jido.Harness.providers()
|> Enum.map(fn spec ->
  %{
    provider: spec.provider,
    executable: spec.executable,
    normalized_options: spec.normalized_options,
    acp_agent: spec.acp_agent
  }
end)

{:ok, provider_status} = Jido.Harness.status(provider)
ready? = Jido.Harness.ProviderStatus.ready?(provider_status)

unless ready? do
  raise """
  #{provider} is not ready in this Livebook runtime.
  executable: #{inspect(provider_status.executable)}
  error: #{inspect(provider_status.error)}
  PATH: #{System.get_env("PATH")}
  """
end

%{
  ready?: ready?,
  installed?: provider_status.installed,
  compatible?: provider_status.compatible,
  authenticated?: provider_status.authenticated,
  version: provider_status.version,
  capabilities: provider_status.capabilities,
  acp_agent: provider_status.acp_agent,
  session_ready?: provider_status.session_ready
}

Run one request

The result is provider-neutral. Provider-specific records that do not have a canonical mapping remain available as :provider_event events.

result =
  Jido.Harness.run(
    provider,
    %{prompt: prompt, cwd: cwd, runtime_timeout_ms: runtime_timeout_ms},
    await_timeout: await_timeout
  )
  |> JidoHarnessLivebook.completed!()

%{
  run_id: result.run_id,
  provider: result.provider,
  provider_session_id: result.provider_session_id,
  status: result.status,
  text: result.text,
  text_truncated?: result.text_truncated?,
  usage: result.usage,
  event_types: Enum.map(result.events, & &1.type)
}

Use Jido.Harness.Run instead when the caller must stream, cancel, or reattach to work by ID.

Jido.Harness.Run.prune(result.run_id)