codex_sdk: repair gaps from the typed plugin API review

Fix any remaining typed plugin API, documentation, or test issues and rerun
the full Phase F quality floor.

Author: nshkrdotcom

README.md

@@ -370,6 +370,30 @@ the under-development approval features only inside a temporary `CODEX_HOME`, so
 live command/file/permissions approval flows without mutating your real Codex settings or writing
 inside this repository.
 
+Raw versus typed plugin calls:
+
+```elixir
+alias Codex.AppServer
+alias Codex.Protocol.Plugin
+
+{:ok, raw} =
+  AppServer.plugin_read(conn, "/tmp/marketplace.json", "demo-plugin")
+
+{:ok, %Plugin.ReadResponse{plugin: plugin}} =
+  AppServer.request_typed(
+    conn,
+    "plugin/read",
+    %Plugin.ReadParams{
+      marketplace_path: "/tmp/marketplace.json",
+      plugin_name: "demo-plugin"
+    },
+    Plugin.ReadResponse
+  )
+
+IO.inspect(raw["plugin"]["apps"], label: "raw apps")
+IO.inspect(plugin.apps, label: "typed apps")
+```
+
 App-server v2 input blocks support `text`, `image`, `localImage`, `skill`, and `mention`.
 Legacy app-server v1 conversation flows are available via `Codex.AppServer.V1`.
 

guides/11-typed-plugin-api.md

@@ -37,6 +37,22 @@ alias Codex.Protocol.Plugin
   )
 ```
 
+Raw and typed usage can live side by side:
+
+```elixir
+alias Codex.AppServer
+alias Codex.Protocol.Plugin
+
+{:ok, raw} =
+  AppServer.plugin_read(conn, "/tmp/marketplace.json", "demo-plugin")
+
+{:ok, %Plugin.ReadResponse{plugin: plugin}} =
+  AppServer.plugin_read_typed(conn, "/tmp/marketplace.json", "demo-plugin")
+
+IO.inspect(raw["plugin"]["apps"], label: "raw apps")
+IO.inspect(plugin.apps, label: "typed apps")
+```
+
 ## Typed Params
 
 Typed plugin params own app-server wire encoding:
@@ -91,5 +107,10 @@ upstream JSON shape directly. Use the typed wrappers when you want:
 - preserved `extra` metadata
 - repo-local parse errors instead of raw validation internals
 
+Nested response validation failures also stay on the outer response contract.
+For example, an invalid `plugin/list` payload still returns
+`{:error, {:invalid_plugin_list_response, details}}` instead of leaking nested
+schema exceptions.
+
 The typed plugin models remain local to `codex_sdk`; they are not moved into the
 shared runtime-core repos.

lib/codex/app_server.ex

@@ -208,9 +208,8 @@ defmodule Codex.AppServer do
   def request_typed(conn, method, params, response_module, opts \\ [])
       when is_pid(conn) and is_binary(method) and is_atom(response_module) and is_list(opts) do
     with {:ok, encoded_params} <- encode_typed_request_params(method, params),
-         {:ok, result} <- Connection.request(conn, method, encoded_params, opts),
-         {:ok, typed_response} <- parse_typed_response(response_module, result) do
-      {:ok, typed_response}
+         {:ok, result} <- Connection.request(conn, method, encoded_params, opts) do
+      parse_typed_response(response_module, result)
     end
   end
 
@@ -891,12 +890,14 @@ defmodule Codex.AppServer do
   """
   @spec plugin_list(connection(), keyword()) :: {:ok, map()} | {:error, term()}
   def plugin_list(conn, opts \\ []) when is_pid(conn) and is_list(opts) do
-    params = %Plugin.ListParams{
-      cwds: Keyword.get(opts, :cwds),
-      force_remote_sync: Plugin.Helpers.raw_true?(Keyword.get(opts, :force_remote_sync))
-    }
-
-    Connection.request(conn, "plugin/list", Plugin.ListParams.to_map(params), timeout_ms: 30_000)
+    with {:ok, params} <-
+           encode_plugin_request_params(
+             "plugin/list",
+             cwds: Keyword.get(opts, :cwds),
+             force_remote_sync: Keyword.get(opts, :force_remote_sync)
+           ) do
+      Connection.request(conn, "plugin/list", params, timeout_ms: 30_000)
+    end
   end
 
   @doc """
@@ -922,18 +923,15 @@ defmodule Codex.AppServer do
   def plugin_install(conn, marketplace_path, plugin_name, opts \\ [])
       when is_pid(conn) and is_binary(marketplace_path) and is_binary(plugin_name) and
              is_list(opts) do
-    params = %Plugin.InstallParams{
-      marketplace_path: marketplace_path,
-      plugin_name: plugin_name,
-      force_remote_sync: Plugin.Helpers.raw_true?(Keyword.get(opts, :force_remote_sync))
-    }
-
-    Connection.request(
-      conn,
-      "plugin/install",
-      Plugin.InstallParams.to_map(params),
-      timeout_ms: 30_000
-    )
+    with {:ok, params} <-
+           encode_plugin_request_params(
+             "plugin/install",
+             marketplace_path: marketplace_path,
+             plugin_name: plugin_name,
+             force_remote_sync: Keyword.get(opts, :force_remote_sync)
+           ) do
+      Connection.request(conn, "plugin/install", params, timeout_ms: 30_000)
+    end
   end
 
   @doc """
@@ -965,14 +963,14 @@ defmodule Codex.AppServer do
   @spec plugin_read(connection(), String.t(), String.t()) :: {:ok, map()} | {:error, term()}
   def plugin_read(conn, marketplace_path, plugin_name)
       when is_pid(conn) and is_binary(marketplace_path) and is_binary(plugin_name) do
-    params = %Plugin.ReadParams{marketplace_path: marketplace_path, plugin_name: plugin_name}
-
-    Connection.request(
-      conn,
-      "plugin/read",
-      Plugin.ReadParams.to_map(params),
-      timeout_ms: 30_000
-    )
+    with {:ok, params} <-
+           encode_plugin_request_params(
+             "plugin/read",
+             marketplace_path: marketplace_path,
+             plugin_name: plugin_name
+           ) do
+      Connection.request(conn, "plugin/read", params, timeout_ms: 30_000)
+    end
   end
 
   @doc """
@@ -1003,17 +1001,14 @@ defmodule Codex.AppServer do
   @spec plugin_uninstall(connection(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}
   def plugin_uninstall(conn, plugin_id, opts \\ [])
       when is_pid(conn) and is_binary(plugin_id) and is_list(opts) do
-    params = %Plugin.UninstallParams{
-      plugin_id: plugin_id,
-      force_remote_sync: Plugin.Helpers.raw_true?(Keyword.get(opts, :force_remote_sync))
-    }
-
-    Connection.request(
-      conn,
-      "plugin/uninstall",
-      Plugin.UninstallParams.to_map(params),
-      timeout_ms: 30_000
-    )
+    with {:ok, params} <-
+           encode_plugin_request_params(
+             "plugin/uninstall",
+             plugin_id: plugin_id,
+             force_remote_sync: Keyword.get(opts, :force_remote_sync)
+           ) do
+      Connection.request(conn, "plugin/uninstall", params, timeout_ms: 30_000)
+    end
   end
 
   @doc """
@@ -1327,14 +1322,23 @@ defmodule Codex.AppServer do
   defp encode_command_exec_delta(delta) when is_binary(delta), do: Base.encode64(delta)
   defp encode_command_exec_delta(delta), do: delta
 
+  defp encode_plugin_request_params(method, params) when is_binary(method) and is_list(params) do
+    params
+    |> normalize_plugin_request_params(method)
+    |> then(&encode_typed_request_params(method, &1))
+  end
+
   defp encode_typed_request_params(method, nil) do
     case typed_params_module(method) do
       nil ->
         {:ok, %{}}
 
-      module when is_atom(module) ->
-        with {:ok, typed_params} <- apply(module, :parse, [%{}]) do
-          {:ok, apply(module, :to_map, [typed_params])}
+      module when is_atom(module) and not is_nil(module) ->
+        parser = :erlang.make_fun(module, :parse, 1)
+        encoder = :erlang.make_fun(module, :to_map, 1)
+
+        with {:ok, typed_params} <- parser.(%{}) do
+          {:ok, encoder.(typed_params)}
         end
     end
   end
@@ -1352,9 +1356,12 @@ defmodule Codex.AppServer do
       nil ->
         {:ok, Params.normalize_map(params)}
 
-      module when is_atom(module) ->
-        with {:ok, typed_params} <- apply(module, :parse, [params]) do
-          {:ok, apply(module, :to_map, [typed_params])}
+      module when is_atom(module) and not is_nil(module) ->
+        parser = :erlang.make_fun(module, :parse, 1)
+        encoder = :erlang.make_fun(module, :to_map, 1)
+
+        with {:ok, typed_params} <- parser.(params) do
+          {:ok, encoder.(typed_params)}
         end
     end
   end
@@ -1375,6 +1382,9 @@ defmodule Codex.AppServer do
         {:error, {:invalid_typed_response_module, response_module}}
     end
   rescue
+    error in [CliSubprocessCore.Schema.Error] ->
+      {:error, {error.tag, error.details}}
+
     error in [ArgumentError, RuntimeError] ->
       {:error, {:invalid_typed_response, response_module, error}}
   end
@@ -1385,6 +1395,17 @@ defmodule Codex.AppServer do
   defp typed_params_module("plugin/uninstall"), do: Plugin.UninstallParams
   defp typed_params_module(_method), do: nil
 
+  defp normalize_plugin_request_params(params, method)
+       when method in ["plugin/list", "plugin/install", "plugin/uninstall"] and is_list(params) do
+    if Keyword.has_key?(params, :force_remote_sync) do
+      Keyword.update!(params, :force_remote_sync, &Plugin.Helpers.raw_true?/1)
+    else
+      params
+    end
+  end
+
+  defp normalize_plugin_request_params(params, _method) when is_list(params), do: params
+
   defp normalize_true(true), do: true
   defp normalize_true("true"), do: true
   defp normalize_true(_), do: nil

lib/codex/protocol/plugin/helpers.ex

@@ -2,6 +2,7 @@ defmodule Codex.Protocol.Plugin.Helpers do
   @moduledoc false
 
   alias CliSubprocessCore.Schema.Conventions
+  alias CliSubprocessCore.Schema.Error, as: SchemaError
   alias Codex.Schema
 
   @spec required_string() :: Zoi.schema()
@@ -60,7 +61,12 @@ defmodule Codex.Protocol.Plugin.Helpers do
   def parse(schema, value, tag, key_mapping, projector) when is_function(projector, 1) do
     case Schema.parse(schema, normalize_input(value, key_mapping), tag) do
       {:ok, parsed} ->
-        {:ok, projector.(parsed)}
+        try do
+          {:ok, projector.(parsed)}
+        rescue
+          error in [SchemaError] ->
+            {:error, {tag, error.details}}
+        end
 
       {:error, {^tag, details}} ->
         {:error, {tag, details}}
@@ -72,6 +78,9 @@ defmodule Codex.Protocol.Plugin.Helpers do
     schema
     |> Schema.parse!(normalize_input(value, key_mapping), tag)
     |> projector.()
+  rescue
+    error in [SchemaError] ->
+      reraise SchemaError, [tag: tag, details: error.details], __STACKTRACE__
   end
 
   @spec split_extra(map(), [String.t()]) :: {map(), map()}

test/codex/app_server/api_test.exs

@@ -4,8 +4,8 @@ defmodule Codex.AppServer.ApiTest do
   alias Codex.AppServer
   alias Codex.AppServer.Connection
   alias Codex.AppServer.Protocol
-  alias Codex.Protocol.Plugin
   alias Codex.Options
+  alias Codex.Protocol.Plugin
   alias Codex.TestSupport.AppServerSubprocess
 
   setup do
@@ -1102,6 +1102,35 @@ defmodule Codex.AppServer.ApiTest do
              Task.await(task, 200)
   end
 
+  test "request_typed/5 remains generic for non-plugin methods with plain params", %{
+    conn: conn,
+    os_pid: os_pid
+  } do
+    task =
+      Task.async(fn ->
+        AppServer.request_typed(
+          conn,
+          "experimentalFeature/list",
+          [cursor: "cur"],
+          Plugin.UninstallResponse,
+          timeout_ms: 30_000
+        )
+      end)
+
+    assert_receive {:app_server_subprocess_send, ^conn, request_line}
+
+    assert {:ok,
+            %{
+              "id" => req_id,
+              "method" => "experimentalFeature/list",
+              "params" => %{"cursor" => "cur"}
+            }} = Jason.decode(request_line)
+
+    send(conn, {:stdout, os_pid, Protocol.encode_response(req_id, %{"data" => []})})
+
+    assert {:ok, %Plugin.UninstallResponse{extra: %{"data" => []}}} = Task.await(task, 200)
+  end
+
   test "request_typed/5 returns adapted parse errors for invalid typed payloads", %{
     conn: conn,
     os_pid: os_pid
@@ -1129,6 +1158,55 @@ defmodule Codex.AppServer.ApiTest do
     assert is_list(details.issues)
   end
 
+  test "request_typed/5 returns adapted parse errors for invalid nested typed payloads", %{
+    conn: conn,
+    os_pid: os_pid
+  } do
+    task =
+      Task.async(fn ->
+        AppServer.request_typed(
+          conn,
+          "plugin/list",
+          %Plugin.ListParams{},
+          Plugin.ListResponse,
+          timeout_ms: 30_000
+        )
+      end)
+
+    assert_receive {:app_server_subprocess_send, ^conn, request_line}
+
+    assert {:ok, %{"id" => req_id, "method" => "plugin/list"}} = Jason.decode(request_line)
+
+    send(
+      conn,
+      {:stdout, os_pid,
+       Protocol.encode_response(req_id, %{
+         "marketplaces" => [
+           %{
+             "name" => "codex-curated",
+             "path" => "/tmp/marketplace.json",
+             "plugins" => [
+               %{
+                 "id" => "demo-plugin@codex-curated",
+                 "name" => "demo-plugin",
+                 "source" => %{"type" => "local", "path" => "/tmp/plugins/demo-plugin"},
+                 "installed" => "yes",
+                 "enabled" => true,
+                 "installPolicy" => "AVAILABLE",
+                 "authPolicy" => "ON_INSTALL"
+               }
+             ]
+           }
+         ]
+       })}
+    )
+
+    assert {:error, {:invalid_plugin_list_response, details}} = Task.await(task, 200)
+    assert is_binary(details.message)
+    assert is_map(details.errors)
+    assert is_list(details.issues)
+  end
+
   test "typed plugin wrappers preserve wire parity and return typed structs", %{
     conn: conn,
     os_pid: os_pid