# Provider SDK Extensions Guide

Phase 3 keeps an explicit optional layer for provider-native surfaces above
ASM's normalized kernel.

## Kernel Versus Extension Split

Normalized kernel surfaces stay where they already belong:

- `ASM`
- `ASM.Stream`
- `ASM.Result`
- `ASM.ProviderRegistry`

Those APIs continue to own:

- provider selection
- lane selection
- normalized event/result projection
- session/run orchestration

Provider-native extension discovery now lives under
`ASM.Extensions.ProviderSDK`.

Schema ownership follows the same split:

- ASM owns orchestration, provider-option, event, and remote-node envelopes.
- provider-native runtime and protocol schemas stay local to the owning SDK
  repo.
- `NimbleOptions` can still front the public ASM keyword API, but `Zoi` is the
  canonical schema layer underneath new dynamic boundaries.

## Dependency Model

ASM keeps `cli_subprocess_core` required and all provider SDK packages
optional.

- depending only on `:agent_session_manager` gives you the common ASM surface
- adding `:claude_agent_sdk` or `:codex_sdk` activates the matching SDK lane
  and the matching provider-native namespace when it is loadable locally
- adding `:gemini_cli_sdk` or `:amp_sdk` activates only SDK lane/runtime-kit
  availability today; Gemini and Amp still have no separate ASM native
  namespace
- declaring the optional dependency is the only client-app activation step;
  ASM performs discovery and activation automatically

ASM handles those optional dependencies through runtime-checked module loading
and explicit extension/backend boundaries. The kernel never relies on
compile-time warning suppression to reference provider SDK packages.

## Why This Is Separate

`ASM.ProviderRegistry` keeps normalized discovery on its existing surfaces:

- `provider_info/1`: `available_lanes`, `core_capabilities`, `sdk_capabilities`
- `lane_info/2`: `preferred_lane`, `backend`
- `resolve/2`: effective `lane`, `backend`

`ASM.Extensions.ProviderSDK` reports provider-native extension facts:

- explicit optional namespace modules
- provider-native capability inventory
- whether the backing SDK package is loadable locally

That keeps lane discovery and provider-native surface discovery from collapsing
into one API.

## Discovery API

```elixir
alias ASM.Extensions.ProviderSDK

ProviderSDK.extensions()
ProviderSDK.available_extensions()

{:ok, claude_extension} = ProviderSDK.extension(:claude)
{:ok, active_claude_extensions} = ProviderSDK.available_provider_extensions(:claude)
{:ok, codex_extensions} = ProviderSDK.provider_extensions(:codex)
{:ok, codex_native_caps} = ProviderSDK.provider_capabilities(:codex)
{:ok, gemini_report} = ProviderSDK.provider_report(:gemini)

report = ProviderSDK.capability_report()
```

Current built-in namespaces:

- `ASM.Extensions.ProviderSDK.Claude`
- `ASM.Extensions.ProviderSDK.Codex`

These root modules are the namespace anchors for optional provider-native
helpers.

Activation-aware discovery follows a separate rule:

- `extensions/0` is the static Claude/Codex native-extension catalog
- `provider_extensions/1` is the static native-extension catalog for one
  provider
- `available_extensions/0` reports which of those namespaces are active for the
  currently installed optional deps
- `available_provider_extensions/1` reports the active native-extension subset
  for one provider
- `provider_report/1` and `capability_report/0` always include all ASM
  providers, including Gemini and Amp, and show whether each provider SDK
  runtime is available plus any active native namespace inventory
- `registered_namespaces` and `registered_extensions` keep the static catalog
  visible even when a provider currently composes only through the common
  surface
- Gemini and Amp may therefore report `sdk_available?: true` with
  `namespaces: []`, because they currently compose only through the common ASM
  surface

Claude now exposes an explicit bridge into the SDK-local control family:

- `ASM.Extensions.ProviderSDK.Claude.sdk_options/2`
- `ASM.Extensions.ProviderSDK.Claude.sdk_options_for_session/3`
- `ASM.Extensions.ProviderSDK.Claude.start_client/3`
- `ASM.Extensions.ProviderSDK.Claude.start_client_for_session/4`

Those helpers do not redefine Claude control semantics. They only:

- derive `ClaudeAgentSDK.Options` from ASM-style config or session defaults
- preserve ASM execution-surface placement on the resulting SDK options
- keep Claude-native options in a separate `native_overrides` bag
- start `ClaudeAgentSDK.Client` when callers explicitly opt into the SDK-local
  control family

Example:

```elixir
alias ASM.Extensions.ProviderSDK.Claude

asm_opts = [
  provider: :claude,
  cwd: File.cwd!(),
  execution_environment: [permission_mode: :plan],
  model: "sonnet",
  execution_surface: [
    surface_kind: :ssh_exec,
    transport_options: [destination: "buildbox-a", port: 2222]
  ]
]

native_overrides = [
  enable_file_checkpointing: true,
  thinking: %{type: :adaptive}
]

{:ok, client} =
  Claude.start_client(
    asm_opts,
    native_overrides,
    control_request_timeout_ms: 5_000
  )

:ok = ClaudeAgentSDK.Client.set_permission_mode(client, :plan)
```

The normalized ASM APIs stay unchanged. Only the optional extension crosses
into the Claude-native client surface.

Codex now exposes a similarly narrow bridge into the SDK-local app-server
entry path:

- `ASM.Extensions.ProviderSDK.Codex.codex_options/2`
- `ASM.Extensions.ProviderSDK.Codex.codex_options_for_session/3`
- `ASM.Extensions.ProviderSDK.Codex.thread_options/2`
- `ASM.Extensions.ProviderSDK.Codex.thread_options_for_session/3`
- `ASM.Extensions.ProviderSDK.Codex.connect_app_server/3`
- `ASM.Extensions.ProviderSDK.Codex.connect_app_server_for_session/4`

Those helpers do not re-model app-server, MCP, realtime, or voice as ASM
kernel APIs. They only:

- derive `Codex.Options` from ASM-style config or session defaults
- derive `Codex.Thread.Options` from ASM-style config or session defaults
- preserve ASM execution-surface placement on `Codex.Options`
- keep Codex-native global or thread-only fields in explicit override bags
- start `Codex.AppServer` when callers explicitly opt into the SDK-local
  app-server family

Example:

```elixir
alias ASM.Extensions.ProviderSDK.Codex
alias Codex, as: CodexSDK

{:ok, conn} =
  Codex.connect_app_server(
    [
      provider: :codex,
      model: "gpt-5.4",
      reasoning_effort: :high,
      execution_environment: [permission_mode: :default],
      execution_surface: [
        surface_kind: :ssh_exec,
        transport_options: [destination: "codex-host-1"],
        lease_ref: "lease-42"
      ]
    ],
    [model_personality: :pragmatic],
    experimental_api: true
  )

{:ok, thread_opts} =
  Codex.thread_options(
    [
      provider: :codex,
      cwd: "/repo",
      execution_environment: [permission_mode: :default],
      approval_timeout_ms: 45_000,
      output_schema: %{"type" => "object"}
    ],
    transport: {:app_server, conn},
    personality: :pragmatic
  )

{:ok, codex_opts} =
  Codex.codex_options(
    [provider: :codex, model: "gpt-5.4"],
    model_personality: :pragmatic
  )

{:ok, thread} = CodexSDK.start_thread(codex_opts, thread_opts)
```

ASM intentionally does not normalize Codex `:auto` onto `Codex.Thread.Options`
because the current Codex workspace-write auto-edit path dirties repo roots
with a `.codex` artifact. Keep ASM's Codex bridge on `:default` or `:bypass`,
or use `codex_sdk` directly when you explicitly need provider-native
workspace-write behavior.

## Optional-Loading Rules

- discovery calls are always available from ASM
- each extension reports `sdk_available?`
- `sdk_available?` only means the backing SDK package is loadable locally
- `provider_capabilities/1` reports only active native capabilities for the
  current dependency set
- richer provider-native APIs still live in the provider SDK repos
- ASM does not re-model those richer APIs in the kernel
- the Claude bridge keeps ASM config and Claude-native config in separate
  arguments on purpose
- local `:core` and local `:sdk` lanes preserve the same normalized
  `execution_surface` contract; `execution_mode: :remote_node`
  remains a separate ASM-only rule
- ASM-derived fields such as `:cwd`, `:execution_environment`, `:model`,
  `:max_turns`, and `:timeout_ms` must stay in ASM config and are rejected
  from `native_overrides`
- the Codex bridge follows the same rule for ASM-derived fields such as
  `:model`, `:reasoning_effort`, `:cwd`, `:approval_timeout_ms`, and
  `:output_schema`
- the Codex bridge is intentionally useful only at the app-server entry seam;
  the actual app-server, MCP, realtime, and voice APIs remain in `codex_sdk`

## Current Native Capability Inventory

Claude namespace:

- `:control_client`
- `:control_protocol`
- `:hooks`
- `:permission_callbacks`

Codex namespace:

- `:app_server`
- `:mcp`
- `:realtime`
- `:voice`

These are capability labels for discovery and documentation only in this
foundation slice. They are not new normalized kernel APIs.
## Session-Control Extensions

Provider SDK extensions may now publish optional callbacks and capability markers for:

- session history listing
- exact or latest-session resume
- pause
- operator intervention

Those extensions are only valid when the provider runtime can back them with a real native surface.
ASM now keeps the provider-native recovery handles in session/run state so a caller can choose exact
resume before it falls back to replaying prompts.