@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 entry to the JSON config, then reload resources so the new model is immediately available.

Options:

• :id (required) — user alias (e.g. "sonnet")
• :model (required) — provider model identifier (e.g. "claude-sonnet-4-6")
• :provider (required) — key referencing an entry in the providers map
• :scope — :local (default, .planck/) or :global (~/.planck/)
• :default — set as default_model (default: true)
• :params — inference parameters map (e.g. %{"temperature" => 0.7})

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

Persist a provider entry to the JSON config and API key to .env, then reload resources.

Options:

• :id (required) — provider key written to providers map (e.g. "anthropic", "nvidia")
• :type (required) — "anthropic", "openai", or "google"
• :base_url — for OpenAI-compatible endpoints
• :identifier — uppercase tag for env var derivation ("NVIDIA" → NVIDIA_API_KEY)
• :has_api_key — set false for keyless local servers; default true
• :api_key — written to <scope>/.env
• :scope — :local (default, .planck/) or :global (~/.planck/)

@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 register_tool(Planck.Agent.Tool.t()) :: :ok

Register a local-node tool globally. Available to all new sessions.

If a tool with the same name is already registered it is replaced. Registered tools shadow sidecar tools and built-ins of the same name. See the tool-shadowing guide for details.

@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 Planck.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!()).
• tools: — extra Planck.Agent.Tool.t() list available only for this session. These shadow registered and built-in tools of the same name.

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

Remove a globally registered tool by name. No-op if not found.