codex_sdk: add the typed plugin app-server API

Land typed plugin params, responses, and request helpers while keeping the raw
wrappers stable.

Author: nshkrdotcom

README.md

@@ -19,6 +19,8 @@ An idiomatic Elixir SDK for embedding OpenAI's Codex agent in your workflows and
 - `guides/01-getting-started.md` - first threads, turns, and sessions
 - `guides/02-architecture.md` - transport layering and ownership boundaries
 - `guides/03-api-guide.md` - public modules and common call patterns
+- `guides/05-app-server-transport.md` - direct app-server requests and host controls
+- `guides/11-typed-plugin-api.md` - typed plugin params, responses, and migration notes
 - `guides/07-models-and-reasoning.md` - shared catalog projections and reasoning controls
 - `guides/08-configuration-defaults.md` - config precedence and default resolution
 
@@ -340,7 +342,9 @@ App-server-only APIs include:
 - `Codex.AppServer.model_list/2`, `config_read/2`, `config_write/4`, `config_batch_write/3`, `config_requirements/1`
 - `Codex.AppServer.experimental_feature_list/2`, `experimental_feature_enablement_set/2`
 - `Codex.AppServer.fs_read_file/2`, `fs_write_file/3`, `fs_create_directory/3`, `fs_get_metadata/2`, `fs_read_directory/2`, `fs_remove/3`, `fs_copy/4`
-- `Codex.AppServer.plugin_list/2`, `plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
+- raw plugin wrappers: `Codex.AppServer.plugin_list/2`, `plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
+- typed plugin wrappers: `Codex.AppServer.plugin_list_typed/2`, `plugin_read_typed/3`, `plugin_install_typed/4`, `plugin_uninstall_typed/3`
+- `Codex.AppServer.request_typed/5` with `Codex.Protocol.Plugin.*` params/response modules
 - `Codex.AppServer.skills_config_write/3`, `collaboration_mode_list/1`, `apps_list/2`
 - `Codex.AppServer.turn_interrupt/3`
 - `Codex.AppServer.thread_shell_command/3` (thread-bound `!` workflow)
@@ -351,14 +355,16 @@ App-server-only APIs include:
 
 On app-server transport, thread options now forward current upstream routing fields such as
 `ephemeral`, `service_name`, and `service_tier`; turn options can override `service_tier`
-per `Codex.Thread.run/3`. Plugin response maps also preserve newer upstream auth metadata such
-as `needsAuth`, and subscriptions adapt `mcpServer/startupStatus/updated` into typed
-`Codex.Events` structs.
+per `Codex.Thread.run/3`. Raw plugin response maps still preserve newer upstream auth metadata
+such as `needsAuth`, while the typed plugin API projects those payloads into
+`Codex.Protocol.Plugin.*` structs and preserves unknown upstream fields in `extra` maps.
+Subscriptions adapt `mcpServer/startupStatus/updated` into typed `Codex.Events` structs.
 
 Runnable app-server demos now include `examples/live_app_server_filesystem.exs` for `fs/*`
 and `examples/live_app_server_plugins.exs` for `plugin/list` + `plugin/read` using a disposable
 repo-local marketplace fixture plus an isolated temporary `CODEX_HOME`, rather than your real
-plugin config; that example now also prints `needsAuth` when the connected build includes it.
+plugin config; that example now uses the typed plugin wrappers and prints derived
+`needs_auth` state from the typed app summaries while the raw wrappers remain available.
 `examples/live_app_server_approvals.exs` uses the same child-process isolation pattern to enable
 the under-development approval features only inside a temporary `CODEX_HOME`, so it can exercise
 live command/file/permissions approval flows without mutating your real Codex settings or writing

docs/python-parity-checklist.md

@@ -12,6 +12,7 @@ This checklist tracks coverage of Python Codex SDK features in the Elixir port.
 | Error taxonomy coverage | `python/errors_transport.jsonl` | `Codex.ErrorTest` | ✅ Implemented | Typed transport errors mirror Python exit diagnostics. |
 | Telemetry lifecycle events | _N/A_ | `Codex.TelemetryTest` | ✅ Implemented | Thread start/stop/exception events and default logger attached via telemetry. |
 | Schema-backed typed protocol helpers | _N/A_ | `Codex.Protocol.RequestUserInputTest`, `Codex.Protocol.CollaborationModeTest`, `Codex.Protocol.RateLimitTest` | ✅ Implemented | Phase E moved these dynamic boundaries onto local `Zoi` schemas while keeping the public structs and preserving future-compatible keys for evolving wire surfaces. |
+| Typed app-server plugin API | app-server plugin protocol (`plugin/list`, `plugin/read`, `plugin/install`, `plugin/uninstall`) | `Codex.Protocol.PluginTest`, `Codex.AppServer.ApiTest` | ✅ Implemented | Phase F adds local `Codex.Protocol.Plugin.*` params/responses, `Codex.AppServer.request_typed/5`, typed wrapper functions beside the raw wrappers, `needsAuth` support on typed app summaries, and `extra` preservation for upstream fields beyond the current Python generation. |
 
 Update this table as fixtures land and Elixir parity tests are implemented.
 

examples/README.md

@@ -97,7 +97,7 @@ The `live_*.exs` scripts hit the live Codex CLI (no OPENAI_API_KEY needed if you
 - `examples/live_oauth_login.exs` — native OAuth status/login/refresh demo using an isolated temporary `CODEX_HOME` by default; prints the browser URL before waiting, supports `--browser`, `--device`, and `--no-browser`, and can optionally show memory-mode app-server auth via `--app-server-memory`
 - `examples/live_app_server_basic.exs` — minimal turn + skills/models/thread list over `codex app-server`
 - `examples/live_app_server_filesystem.exs` — end-to-end `fs/*` app-server demo (write/read/list/metadata/copy/remove); self-skips when the connected CLI build does not advertise those legacy parity methods
-- `examples/live_app_server_plugins.exs` — provisions a disposable local marketplace under the system temp directory, launches `codex app-server` with an isolated temporary `CODEX_HOME`, then exercises `plugin/list` + `plugin/read` without mutating your real `$CODEX_HOME` or requiring a preinstalled plugin; prints `needsAuth` when available and self-skips when the connected CLI build does not advertise `plugin/read`
+- `examples/live_app_server_plugins.exs` — provisions a disposable local marketplace under the system temp directory, launches `codex app-server` with an isolated temporary `CODEX_HOME`, then exercises the typed `plugin_list_typed/2` + `plugin_read_typed/3` wrappers without mutating your real `$CODEX_HOME` or requiring a preinstalled plugin; prints derived `needs_auth` state from typed app summaries and self-skips when the connected CLI build does not advertise `plugin/read`
 - `examples/live_app_server_streaming.exs` — streamed turn over app-server (prints deltas + completion)
 - `examples/live_app_server_approvals.exs` — demonstrates command/file approvals, opts into app-server `experimentalApi`, provisions a disposable temp workspace plus temporary `CODEX_HOME`, enables the under-development approval feature flags only inside that isolated home, and prints a structured-grant fallback plus guardian/request-resolution events when live permissions requests still do not appear
 - `examples/live_app_server_mcp.exs` — lists MCP servers and prints original vs sanitized qualified tool names

examples/live_app_server_plugins.exs

@@ -3,6 +3,8 @@ Mix.Task.run("app.start")
 defmodule CodexExamples.LiveAppServerPlugins do
   @moduledoc false
 
+  alias Codex.Protocol.Plugin
+
   def main(_argv) do
     case run() do
       :ok ->
@@ -33,12 +35,12 @@ defmodule CodexExamples.LiveAppServerPlugins do
                ) do
           try do
             with :ok <- ensure_plugin_read_supported(conn),
-                 {:ok, %{"marketplaces" => marketplaces} = list_result} <-
+                 {:ok, %Plugin.ListResponse{marketplaces: marketplaces} = list_result} <-
                    call_with_timeout(
                      fn ->
                        request_or_skip(
-                         Codex.AppServer.plugin_list(conn, cwds: [fixture.repo_root]),
-                         "plugin"
+                         Codex.AppServer.plugin_list_typed(conn, cwds: [fixture.repo_root]),
+                         "plugin/list"
                        )
                      end,
                      10_000,
@@ -47,13 +49,13 @@ defmodule CodexExamples.LiveAppServerPlugins do
                  {:ok, marketplace, plugin_summary} <-
                    pick_demo_plugin(marketplaces, list_result, fixture),
                  marketplace_path when is_binary(marketplace_path) <-
-                   Map.get(marketplace, "path"),
-                 plugin_name when is_binary(plugin_name) <- Map.get(plugin_summary, "name"),
-                 {:ok, %{"plugin" => plugin_detail}} <-
+                   marketplace.path,
+                 plugin_name when is_binary(plugin_name) <- plugin_summary.name,
+                 {:ok, %Plugin.ReadResponse{plugin: plugin_detail}} <-
                    call_with_timeout(
                      fn ->
                        request_or_skip(
-                         Codex.AppServer.plugin_read(conn, marketplace_path, plugin_name),
+                         Codex.AppServer.plugin_read_typed(conn, marketplace_path, plugin_name),
                          "plugin/read"
                        )
                      end,
@@ -230,9 +232,13 @@ defmodule CodexExamples.LiveAppServerPlugins do
     end
   end
 
-  defp pick_demo_plugin(marketplaces, %{"remoteSyncError" => remote_sync_error}, fixture)
+  defp pick_demo_plugin(
+         marketplaces,
+         %Plugin.ListResponse{remote_sync_error: remote_sync_error},
+         fixture
+       )
        when is_list(marketplaces) do
-    case Enum.find(marketplaces, &(Map.get(&1, "path") == fixture.marketplace_path)) do
+    case Enum.find(marketplaces, &(&1.path == fixture.marketplace_path)) do
       nil when is_binary(remote_sync_error) and remote_sync_error != "" ->
         {:skip,
          "plugin/list did not surface the temporary marketplace and reported remoteSyncError: #{remote_sync_error}"}
@@ -241,8 +247,8 @@ defmodule CodexExamples.LiveAppServerPlugins do
         {:skip,
          "plugin/list did not surface the temporary repo-local marketplace; this build may lack repo marketplace discovery parity"}
 
-      %{"plugins" => plugins} = marketplace when is_list(plugins) ->
-        case Enum.find(plugins, &(Map.get(&1, "name") == fixture.plugin_name)) do
+      %Plugin.Marketplace{plugins: plugins} = marketplace ->
+        case Enum.find(plugins, &(&1.name == fixture.plugin_name)) do
           nil ->
             {:skip,
              "plugin/list returned the temporary marketplace but not the expected demo plugin"}
@@ -254,48 +260,44 @@ defmodule CodexExamples.LiveAppServerPlugins do
   end
 
   defp pick_demo_plugin(marketplaces, _response, fixture) when is_list(marketplaces) do
-    pick_demo_plugin(marketplaces, %{}, fixture)
+    pick_demo_plugin(marketplaces, %Plugin.ListResponse{}, fixture)
   end
 
-  defp print_plugin_detail(%{} = plugin, fixture) do
-    summary = Map.get(plugin, "summary") || %{}
-    interface = Map.get(summary, "interface") || %{}
-    skills = Map.get(plugin, "skills") || []
-    apps = Map.get(plugin, "apps") || []
-    mcp_servers = Map.get(plugin, "mcpServers") || Map.get(plugin, "mcp_servers") || []
-
-    needs_auth =
-      Map.get(summary, "needsAuth") ||
-        Map.get(summary, "needs_auth") ||
-        Map.get(plugin, "needsAuth") ||
-        Map.get(plugin, "needs_auth")
+  defp print_plugin_detail(%Plugin.Detail{} = plugin, fixture) do
+    summary = plugin.summary
+    interface = summary.interface
+    skills = plugin.skills
+    apps = plugin.apps
+    mcp_servers = plugin.mcp_servers
+    needs_auth = Enum.any?(apps, & &1.needs_auth)
 
     IO.puts("""
     App-server plugin/read demo completed.
       fixture_root: #{fixture.temp_root}
       app_server_cwd: #{fixture.repo_root}
       isolated_codex_home: #{fixture.codex_home}
-      marketplace: #{Map.get(plugin, "marketplaceName")}
-      marketplace_path: #{Map.get(plugin, "marketplacePath")}
-      id: #{Map.get(summary, "id")}
-      name: #{Map.get(summary, "name")}
-      display_name: #{Map.get(interface, "displayName") || Map.get(summary, "name")}
-      installed: #{inspect(Map.get(summary, "installed"))}
-      enabled: #{inspect(Map.get(summary, "enabled"))}
-      install_policy: #{inspect(Map.get(summary, "installPolicy"))}
-      auth_policy: #{inspect(Map.get(summary, "authPolicy"))}
+      marketplace: #{plugin.marketplace_name}
+      marketplace_path: #{plugin.marketplace_path}
+      id: #{summary.id}
+      name: #{summary.name}
+      display_name: #{(interface && interface.display_name) || summary.name}
+      installed: #{inspect(summary.installed)}
+      enabled: #{inspect(summary.enabled)}
+      install_policy: #{inspect(summary.install_policy)}
+      auth_policy: #{inspect(summary.auth_policy)}
       needs_auth: #{inspect(needs_auth)}
     """)
 
     IO.puts("""
     Note: this example launches `codex app-server` with an isolated child `cwd` and
     temporary `CODEX_HOME`, so it never touches your real Codex config. Because it only
     exercises `plugin/list` + `plugin/read` and does not install the plugin, `installed`
-    and `enabled` should usually remain false. When upstream includes `needsAuth`, that
-    field is surfaced verbatim so you can see whether an install would require auth.
+    and `enabled` should usually remain false. The typed response projects app auth
+    requirements onto `needs_auth` while still preserving unknown upstream fields in
+    each struct's `extra` map.
     """)
 
-    if description = Map.get(plugin, "description") do
+    if description = plugin.description do
       IO.puts("Description:\n#{description}\n")
     end
 
@@ -305,7 +307,7 @@ defmodule CodexExamples.LiveAppServerPlugins do
       IO.puts("  (none)")
     else
       Enum.each(skills, fn skill ->
-        IO.puts("  - #{skill["name"]}: #{skill["description"]}")
+        IO.puts("  - #{skill.name}: #{skill.description}")
       end)
     end
 
@@ -316,7 +318,7 @@ defmodule CodexExamples.LiveAppServerPlugins do
     else
       Enum.each(apps, fn app ->
         IO.puts(
-          "  - #{app["name"] || app["id"]} (id=#{app["id"]}, installUrl=#{inspect(app["installUrl"])})"
+          "  - #{app.name || app.id} (id=#{app.id}, installUrl=#{inspect(app.install_url)}, needs_auth=#{inspect(app.needs_auth)})"
         )
       end)
     end

guides/01-getting-started.md

@@ -156,6 +156,12 @@ permissions approvals, `mcpServer/startupStatus/updated`, guardian review notifi
 `service_name`, and `service_tier` are forwarded on app-server transport, and
 per-turn `service_tier` can be passed to `Codex.Thread.run/3`.
 
+The plugin APIs now have both raw and typed forms. Use the raw wrappers when you
+want the original response maps, or `Codex.AppServer.plugin_list_typed/2`,
+`plugin_read_typed/3`, and `Codex.AppServer.request_typed/5` with
+`Codex.Protocol.Plugin.*` when you want typed structs with preserved `extra`
+metadata.
+
 When you need the managed app-server child to run against a temporary repo or
 isolated `CODEX_HOME`, pass `cwd:` and `process_env:` to
 `Codex.AppServer.connect/2`. Thread working directories are still configured per

guides/02-architecture.md

@@ -25,6 +25,8 @@ historical mailbox-facing session API on top of `CliSubprocessCore.RawSession`.
 The app-server path is the parity transport for upstream v2 features such as `fs/*`, `plugin/read`,
 `thread/shellCommand`, structured `item/permissions/requestApproval` responses,
 `mcpServer/startupStatus/updated`, guardian review notifications, and `serverRequest/resolved`.
+Typed plugin params and responses live locally under `Codex.Protocol.Plugin.*`;
+they do not move into the shared runtime-core repos.
 
 Transport selection is per-thread via `Codex.Thread.Options.transport`:
 

guides/03-api-guide.md

@@ -255,14 +255,18 @@ plugin, and thread-shell helpers:
 - `experimental_feature_list/2` and `experimental_feature_enablement_set/2`
 - `fs_read_file/2`, `fs_write_file/3`, `fs_create_directory/3`, `fs_get_metadata/2`,
   `fs_read_directory/2`, `fs_remove/3`, `fs_copy/4`
-- `plugin_list/2`, `plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
+- raw plugin wrappers: `plugin_list/2`, `plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
+- typed plugin wrappers: `plugin_list_typed/2`, `plugin_read_typed/3`,
+  `plugin_install_typed/4`, `plugin_uninstall_typed/3`
+- `request_typed/5` for `Codex.Protocol.Plugin.*` request/response structs
 - `thread_shell_command/3`
 
 Current app-server lifecycle fields are also forwarded through the high-level
 transport: `ephemeral`, `service_name`, and `service_tier` on thread options,
 plus per-turn `service_tier` on `Codex.Thread.run/3` / `run_streamed/3`.
 `plugin_install/4` and `plugin_uninstall/3` accept `force_remote_sync: true`,
-and raw plugin maps preserve newer upstream fields such as `needsAuth`.
+raw plugin maps preserve newer upstream fields such as `needsAuth`, and the
+typed plugin structs preserve forward-compatible fields in `extra` maps.
 
 `experimental_feature_enablement_set/2` forwards the supplied `enablement` map
 without a local allowlist and lets the connected server validate the active

guides/04-examples.md

@@ -1443,12 +1443,11 @@ end, including base64 round-tripping, and self-skips when the connected build no
 longer advertises those legacy parity methods. `live_app_server_plugins.exs`
 creates a disposable repo-local marketplace and plugin bundle under the system
 temp directory, launches `codex app-server` with an isolated child `cwd` plus a
-temporary `CODEX_HOME`, then demonstrates `plugin/list` discovery followed by
-`plugin/read` detail loading without mutating your real Codex config. Because
+temporary `CODEX_HOME`, then demonstrates the typed `plugin_list_typed/2` and
+`plugin_read_typed/3` wrappers without mutating your real Codex config. Because
 the example never installs or enables that temporary plugin in the isolated home,
-`installed` and `enabled` are expected to remain `false`, `needsAuth` is printed
-when the connected build includes it, and no prior Codex login or plugin install
-is required.
+`installed` and `enabled` are expected to remain `false`, typed app summaries are
+used to derive `needs_auth`, and no prior Codex login or plugin install is required.
 `live_app_server_approvals.exs` demonstrates command/file approvals, uses granular
 `request_permissions: true` for live permissions requests on an `experimental_api: true`
 connection, provisions a disposable temp workspace plus temporary `CODEX_HOME`, enables the