codex_sdk: add local plugin authoring support

Land local manifest, marketplace, writer, and scaffold support without blurring
runtime verification boundaries.

Author: nshkrdotcom

README.md

@@ -21,6 +21,8 @@ An idiomatic Elixir SDK for embedding OpenAI's Codex agent in your workflows and
 - `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/13-plugin-authoring.md` - local manifest writes, scaffold helpers, and scope rules
+- `guides/14-plugin-marketplaces.md` - local marketplace modeling, merge behavior, and verification workflows
 - `guides/07-models-and-reasoning.md` - shared catalog projections and reasoning controls
 - `guides/08-configuration-defaults.md` - config precedence and default resolution
 
@@ -36,6 +38,7 @@ An idiomatic Elixir SDK for embedding OpenAI's Codex agent in your workflows and
 - **Approval Hooks & Sandbox Policies**: Dynamic or static approval flows with registry-backed persistence.
 - **Collaboration & Personality Controls**: Collaboration modes, personality overrides, and web search mode toggles.
 - **Tooling & MCP Integration**: Built-in registry for Codex tool manifests, MCP client helpers, and elicitation handling.
+- **Local Plugin Authoring**: Schema-backed local manifest and marketplace models, deterministic JSON writers, and scaffold helpers that do not depend on app-server `fs/*`.
 - **Observability-Ready**: Telemetry spans, OTLP exporters gated by environment flags, usage stats, and rate limit snapshots.
 - **Realtime API Support**: Full integration with OpenAI Realtime API for bidirectional voice interactions with WebSocket streaming.
 - **Voice Pipeline**: Non-realtime STT -> Workflow -> TTS pipeline with streaming audio support and multi-turn conversations.
@@ -345,6 +348,8 @@ App-server-only APIs include:
 - 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
+- local authoring facade: `Codex.Plugins` with `new_manifest/1`, `new_marketplace/1`,
+  `write_manifest/3`, `write_marketplace/3`, `add_marketplace_plugin/3`, and `scaffold/1`
 - `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)
@@ -370,6 +375,26 @@ 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.
 
+Local plugin authoring is a separate surface from those runtime wrappers:
+
+```elixir
+{:ok, scaffold} =
+  Codex.Plugins.scaffold(
+    cwd: "/repo/root",
+    plugin_name: "demo-plugin",
+    with_marketplace: true,
+    skill: [name: "hello-world", description: "Greets the user"]
+  )
+
+{:ok, marketplace} = Codex.Plugins.read_marketplace(scaffold.marketplace_path)
+```
+
+Use `Codex.Plugins.*` to create and update `.codex-plugin/plugin.json`,
+`.agents/plugins/marketplace.json`, and minimal local plugin trees with normal
+Elixir file IO. Use `Codex.AppServer.plugin_*` later if you want runtime
+verification against a running `codex app-server`. Normal authoring flows do not
+route through app-server `fs/*`.
+
 Raw versus typed plugin calls:
 
 ```elixir
@@ -583,6 +608,9 @@ mix run examples/conversation_and_resume.exs save-resume
 # Concurrency + collaboration demos
 mix run examples/concurrency_and_collaboration.exs parallel lib/codex/thread.ex lib/codex/exec.ex
 
+# Local plugin authoring scaffold (writes to a disposable temp repo)
+mix run examples/plugin_scaffold.exs
+
 # Auto-run tool bridging (forwards outputs/failures to codex exec)
 mix run examples/tool_bridging_auto_run.exs
 
@@ -598,6 +626,9 @@ mix run examples/live_telemetry_stream.exs
 # Live CLI demo (requires authenticated codex CLI or CODEX_API_KEY)
 mix run examples/live_cli_demo.exs "What is the capital of France?"
 
+# Live app-server plugin verification against a disposable local scaffold
+mix run examples/live_app_server_plugins.exs
+
 # Live Codex CLI passthrough helpers
 mix run examples/live_cli_passthrough.exs completion zsh
 

examples/README.md

@@ -97,7 +97,8 @@ 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 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/plugin_scaffold.exs` — local plugin authoring walkthrough using `Codex.Plugins.scaffold/1`; writes a disposable manifest, optional skill, and marketplace entry under the system temp directory and prints the resulting paths
+- `examples/live_app_server_plugins.exs` — provisions a disposable local plugin fixture through `Codex.Plugins.scaffold/1`, 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

@@ -92,45 +92,6 @@ defmodule CodexExamples.LiveAppServerPlugins do
     codex_home = Path.join(home_root, ".codex")
     marketplace_name = "codex-sdk-demo-marketplace-#{suffix}"
     plugin_name = "codex-sdk-demo-plugin-#{suffix}"
-    plugin_root = Path.join(repo_root, "plugins/#{plugin_name}")
-    marketplace_path = Path.join(repo_root, ".agents/plugins/marketplace.json")
-
-    marketplace_json = """
-    {
-      "name": "#{marketplace_name}",
-      "interface": {
-        "displayName": "Codex SDK Demo Marketplace"
-      },
-      "plugins": [
-        {
-          "name": "#{plugin_name}",
-          "source": {
-            "source": "local",
-            "path": "./plugins/#{plugin_name}"
-          },
-          "policy": {
-            "installation": "AVAILABLE",
-            "authentication": "ON_INSTALL"
-          },
-          "category": "Design"
-        }
-      ]
-    }
-    """
-
-    plugin_json = """
-    {
-      "name": "#{plugin_name}",
-      "description": "Local Codex SDK demo plugin loaded from a disposable fixture",
-      "interface": {
-        "displayName": "Codex SDK Demo Plugin",
-        "shortDescription": "Disposable plugin fixture for plugin/read parity checks",
-        "longDescription": "This plugin bundle is created under the system temp directory so the example can exercise plugin/list and plugin/read without mutating your real Codex home.",
-        "developerName": "OpenAI",
-        "category": "Productivity"
-      }
-    }
-    """
 
     app_json = """
     {
@@ -154,23 +115,28 @@ defmodule CodexExamples.LiveAppServerPlugins do
 
     with :ok <- File.mkdir_p(Path.join(repo_root, ".git")),
          :ok <- File.mkdir_p(codex_home),
-         :ok <- File.mkdir_p(Path.join(repo_root, ".agents/plugins")),
-         :ok <- File.mkdir_p(Path.join(plugin_root, ".codex-plugin")),
-         :ok <- File.mkdir_p(Path.join(plugin_root, "skills/thread-summarizer")),
-         :ok <- File.write(marketplace_path, marketplace_json),
-         :ok <- File.write(Path.join(plugin_root, ".codex-plugin/plugin.json"), plugin_json),
-         :ok <-
-           File.write(
-             Path.join(plugin_root, "skills/thread-summarizer/SKILL.md"),
-             """
-             ---
-             name: thread-summarizer
-             description: Summarize email threads
-             ---
-
-             # Thread Summarizer
-             """
+         {:ok, scaffold} <-
+           Codex.Plugins.scaffold(
+             cwd: repo_root,
+             plugin_name: plugin_name,
+             with_marketplace: true,
+             marketplace_name: marketplace_name,
+             marketplace_display_name: "Codex SDK Demo Marketplace",
+             category: "Design",
+             skill: [name: "thread-summarizer", description: "Summarize email threads"],
+             manifest: [
+               description: "Local Codex SDK demo plugin loaded from a disposable fixture",
+               interface: [
+                 display_name: "Codex SDK Demo Plugin",
+                 short_description: "Disposable plugin fixture for plugin/read parity checks",
+                 long_description:
+                   "This plugin bundle is created under the system temp directory so the example can exercise plugin/list and plugin/read without mutating your real Codex home.",
+                 developer_name: "OpenAI",
+                 category: "Productivity"
+               ]
+             ]
            ),
+         plugin_root = scaffold.plugin_root,
          :ok <- File.write(Path.join(plugin_root, ".app.json"), app_json),
          :ok <- File.write(Path.join(plugin_root, ".mcp.json"), mcp_json) do
       {:ok,
@@ -180,7 +146,7 @@ defmodule CodexExamples.LiveAppServerPlugins do
          home_root: home_root,
          codex_home: codex_home,
          marketplace_name: marketplace_name,
-         marketplace_path: marketplace_path,
+         marketplace_path: scaffold.marketplace_path,
          plugin_name: plugin_name
        }}
     else

examples/plugin_scaffold.exs

@@ -0,0 +1,44 @@
+Mix.Task.run("app.start")
+
+defmodule CodexExamples.PluginScaffold do
+  @moduledoc false
+
+  def main(_argv) do
+    temp_root =
+      Path.join(System.tmp_dir!(), "codex_plugin_scaffold_#{System.unique_integer([:positive])}")
+
+    repo_root = Path.join(temp_root, "repo")
+
+    File.mkdir_p!(Path.join(repo_root, ".git"))
+
+    case Codex.Plugins.scaffold(
+           cwd: repo_root,
+           plugin_name: "demo-plugin",
+           with_marketplace: true,
+           skill: [name: "hello-world", description: "Greets the user"]
+         ) do
+      {:ok, result} ->
+        IO.puts("""
+        Local plugin scaffold completed.
+          temp_root: #{temp_root}
+          repo_root: #{repo_root}
+          plugin_root: #{result.plugin_root}
+          manifest_path: #{result.manifest_path}
+          marketplace_path: #{result.marketplace_path}
+          skill_paths: #{Enum.join(result.skill_paths, ", ")}
+        """)
+
+        IO.puts("""
+        This example uses local file IO only. It does not launch `codex app-server`
+        and it does not route authoring through `fs/*`. Use
+        `examples/live_app_server_plugins.exs` later if you want runtime
+        verification against a running app-server.
+        """)
+
+      {:error, reason} ->
+        Mix.raise("Plugin scaffold example failed: #{inspect(reason)}")
+    end
+  end
+end
+
+CodexExamples.PluginScaffold.main(System.argv())

guides/02-architecture.md

@@ -27,6 +27,9 @@ The app-server path is the parity transport for upstream v2 features such as `fs
 `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.
+Local manifest, marketplace, and scaffold authoring live separately under
+`Codex.Plugins.*`; those helpers use direct local file IO and are not disguised
+app-server filesystem wrappers.
 
 Transport selection is per-thread via `Codex.Thread.Options.transport`:
 

guides/03-api-guide.md

@@ -11,6 +11,7 @@ Complete API documentation for all modules in the Elixir Codex SDK.
 | `Codex.Transport` | Transport behaviour for turn execution |
 | `Codex.AppServer` | Stateful app-server JSON-RPC connection + v2 request APIs |
 | `Codex.AppServer.V1` | Legacy app-server compatibility helpers for v1 conversation APIs |
+| `Codex.Plugins` | Local plugin authoring helpers for manifests, marketplaces, and scaffolds |
 | `Codex.Subagents` | Deterministic host-side discovery, inspection, and await helpers for subagent threads |
 | `Codex.OAuth` | Native OAuth login, refresh, status, logout, and host-managed login helpers |
 | `Codex.Agent` | Reusable agent definition (instructions, tools, hooks) |
@@ -272,6 +273,48 @@ typed plugin structs preserve forward-compatible fields in `extra` maps.
 without a local allowlist and lets the connected server validate the active
 feature keys.
 
+Local plugin authoring is intentionally separate from that runtime transport
+surface. Use `Codex.Plugins` when you want to create or update:
+
+- `.codex-plugin/plugin.json`
+- `.agents/plugins/marketplace.json`
+- minimal local plugin directory scaffolds
+
+`Codex.Plugins` uses normal Elixir file IO, deterministic JSON writes, and
+schema-backed validation. It does not require a running Codex subprocess and it
+does not route normal authoring flows through app-server `fs/*`.
+
+## Codex.Plugins
+
+Primary local authoring entry points:
+
+- `new_manifest/1` and `validate_manifest/1`
+- `new_marketplace/1` and `validate_marketplace/1`
+- `read_manifest/1` and `read_marketplace/1`
+- `write_manifest/3` and `write_marketplace/3`
+- `add_marketplace_plugin/3`
+- `scaffold/1`
+
+Minimal local scaffold:
+
+```elixir
+{:ok, result} =
+  Codex.Plugins.scaffold(
+    cwd: "/repo/root",
+    plugin_name: "demo-plugin",
+    with_marketplace: true,
+    skill: [name: "hello-world", description: "Greets the user"]
+  )
+
+result.plugin_root
+result.manifest_path
+result.marketplace_path
+```
+
+See `guides/13-plugin-authoring.md` and
+`guides/14-plugin-marketplaces.md` for the path rules, merge behavior, and the
+authoring-versus-runtime split.
+
 ## Codex.Subagents
 
 `Codex.Subagents` wraps the deterministic pieces of a subagent workflow that

guides/04-examples.md

@@ -23,10 +23,11 @@ so it does not mutate your real login state unless you opt into that explicitly.
 11. [Live Usage & Compaction](#live-usage--compaction)
 12. [Live Exec Controls](#live-exec-controls)
 13. [Live Telemetry Stream](#live-telemetry-stream)
-14. [Additional Live Examples](#additional-live-examples)
-15. [App-server Transport](#app-server-transport)
-16. [Realtime Voice Interactions](#realtime-voice-interactions)
-17. [Voice Pipeline](#voice-pipeline)
+14. [Local Plugin Authoring](#local-plugin-authoring)
+15. [Additional Live Examples](#additional-live-examples)
+16. [App-server Transport](#app-server-transport)
+17. [Realtime Voice Interactions](#realtime-voice-interactions)
+18. [Voice Pipeline](#voice-pipeline)
 
 ---
 
@@ -1405,6 +1406,33 @@ mix run examples/live_telemetry_stream.exs
 
 Auth falls back to your Codex CLI login when `CODEX_API_KEY` is not set.
 
+## Local Plugin Authoring
+
+Local plugin authoring is file-oriented and separate from app-server runtime
+verification.
+
+Use `Codex.Plugins.scaffold/1` when you want a minimal local plugin tree plus
+an optional marketplace entry:
+
+```elixir
+{:ok, scaffold} =
+  Codex.Plugins.scaffold(
+    cwd: "/repo/root",
+    plugin_name: "demo-plugin",
+    with_marketplace: true,
+    skill: [name: "hello-world", description: "Greets the user"]
+  )
+
+{:ok, manifest} = Codex.Plugins.read_manifest(scaffold.manifest_path)
+{:ok, marketplace} = Codex.Plugins.read_marketplace(scaffold.marketplace_path)
+```
+
+Runnable local example:
+
+```bash
+mix run examples/plugin_scaffold.exs
+```
+
 ## Additional Live Examples
 
 - `examples/live_cli_passthrough.exs` — direct wrappers for `completion`, `features`, `login status`, and arbitrary raw `codex` argv
@@ -1441,11 +1469,11 @@ mix run examples/live_thread_management.exs
 `live_app_server_filesystem.exs` demonstrates the thin `fs/*` wrappers end to
 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 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,
+first uses `Codex.Plugins.scaffold/1` to author a disposable repo-local plugin
+fixture under the system temp directory, then launches `codex app-server` with
+an isolated child `cwd` plus a temporary `CODEX_HOME`, and finally verifies the
+result with typed `plugin_list_typed/2` and `plugin_read_typed/3`. Because the
+example never installs or enables that temporary plugin in the isolated home,
 `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