@spec available_models() :: [Planck.AI.Model.t()]

Return models available for use (providers with API keys configured).

@spec close_session(session_id()) :: :ok | {:error, term()}

Close a session. Stops the agent team and the session GenServer. The SQLite file is retained for later resumption.

@spec config() :: Planck.Headless.Config.t()

Return the resolved configuration.

@spec configure_model(keyword()) :: :ok | {:error, term()}

Persist a model configuration to the JSON config and .env files, then reload resources so the new model is immediately available.

Options:

• :provider (required) — e.g. :anthropic, :ollama
• :model_id (required) — model identifier string
• :scope — :local (default, .planck/) or :global (~/.planck/)
• :api_key — written to <scope>/.env for cloud providers
• :base_url — stored in models config entry for local providers
• :default — set as default_provider/default_model (default: true)

@spec delete_session(session_id()) :: :ok

Close a session and permanently delete its SQLite file from disk.

Stops all running agents and the Session GenServer if active, then removes the .db file. This operation is irreversible.

@spec get_team(String.t()) :: {:ok, Planck.Agent.Team.t()} | {:error, :not_found}

Look up a team by alias.

@spec list_sessions() :: [
  %{session_id: String.t(), name: String.t(), active: boolean()}
]

List all sessions on disk — active and inactive — with their id, name, and whether they are currently running.

@spec list_teams() :: [
  %{alias: String.t(), name: String.t() | nil, description: String.t() | nil}
]

List all registered teams with alias, name, and description.

@spec nudge(session_id()) :: :ok | {:error, term()}

Nudge the orchestrator to act on its existing message history without adding a new user message. Used after session resume when a recovery context is already present and just needs to be acted upon.

Returns :ok if the orchestrator was nudged, {:error, reason} otherwise.

@spec prompt(session_id(), String.t()) :: :ok | {:error, term()}

Send a user prompt to the orchestrator of a session.

@spec reload_resources() :: :ok

Reload tools, skills, teams, and the compactor from disk. In-flight sessions keep their original resources.

@spec resume_session(
  String.t(),
  keyword()
) :: {:ok, session_id()} | {:error, term()}

Resume a session by session_id or by name. Reconstructs the team, restores message history, and injects a recovery context if prior work was in-flight.

@spec rewind_to_message(session_id(), pos_integer(), String.t()) ::
  :ok | {:error, term()}

Edit a previous user message: rewind the orchestrator to strictly before the given DB row id (truncates both the SQLite session and in-memory history via Agent.rewind_to_message/2), then re-prompt with new_text.

@spec start_session(keyword()) :: {:ok, session_id()} | {:error, term()}

Start a new session. Returns {:ok, session_id}.

Options

• template: — team alias, path to a TEAM.json directory, or nil for the default dynamic team (lone orchestrator built from config defaults).
• name: — session name; auto-generated as <adjective>-<noun> if absent.
• cwd: — working directory for the session (default: File.cwd!()).