@ory/codex 0.11.1 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +75 -195
  2. package/dist/cli/main.js +16 -13
  3. package/dist/cli/setup.js +86 -13
  4. package/dist/handlers.d.ts +2 -2
  5. package/dist/handlers.js +2 -2
  6. package/dist/types.d.ts +3 -2
  7. package/marketplace/plugins/ory-codex/.codex-plugin/plugin.json +1 -0
  8. package/package.json +3 -2
package/README.md CHANGED
@@ -1,157 +1,101 @@
1
1
  # Ory Agent Plugin: Codex
2
2
 
3
- [Ory](https://ory.com) bundled into [Codex](https://github.com/openai/codex): skills that scaffold Ory authentication into your codebase, a local Ory stack you can spin up in one command, and (when pointed at an Ory project) authentication, authorization, and audit for every tool Codex runs.
3
+ Security and developer experience for [Codex](https://github.com/openai/codex), powered by [Ory](https://ory.com).
4
4
 
5
- You don't need an Ory account or any prior Ory experience to start.
5
+ **Security.** Codex runs real actions on your machine — editing files, running shell commands, calling APIs. The plugin gives every session a verifiable identity (you sign in once; Codex and any sub-agents it spawns each get their own), checks every tool call against permissions you control, and records each decision as an audit trace you can ship to your observability stack. It starts in watch mode so nothing is blocked on day one, and if Ory is ever unreachable it steps aside rather than locking you out.
6
6
 
7
- ## New to Ory?
7
+ **Developer experience.** A single command installs the plugin and walks you through connecting — choose Ory Network, a local Docker stack, or audit-only, and it wires up the project, sign-in client, login, and permissions for you. It also helps you build Ory into your own app: ask in plain language to scaffold login, registration, and recovery pages, run a local Ory, or manage identities and permissions through the bundled MCP server.
8
8
 
9
- [Ory](https://www.ory.com/docs/) is an open-source identity and access platform — it provides login, registration, sessions, social sign-in, multi-factor auth, and fine-grained permissions, so you don't have to build any of that yourself. Two things make it easy to try with no prior experience:
9
+ ## What you'll need
10
10
 
11
- - **Ory Elements** are prebuilt, themeable UI components for the auth pages (login, registration, recovery, settings). The scaffolding skills wire them into your app for you.
12
- - **The local Ory stack** is a complete Ory running on your laptop in Docker — no account, no signup, no API key. Everything in the Quickstart below works against it, fully offline.
11
+ - [Codex](https://github.com/openai/codex), installed and signed in
12
+ - Node.js **22 or newer**
13
+ - [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
14
+ - macOS or Linux (Windows works via WSL2)
13
15
 
14
- This plugin does two independent things, and you can use either on its own:
16
+ ## Get started
15
17
 
16
- 1. **Build auth into your app.** Have Codex scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This is the Quickstart below — it needs nothing but Docker.
17
- 2. **Govern the agent itself.** Authenticate Codex's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See [Agent security](#agent-security).
18
-
19
- If you're just exploring, do the Quickstart first.
20
-
21
- ## Prerequisites
22
-
23
- - [Codex](https://github.com/openai/codex) installed and signed in
24
- - Node.js **≥ 22**
25
- - [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
26
- - macOS or Linux. Windows works via WSL2.
27
-
28
- ## Install
29
-
30
- No prior `npm install` required:
18
+ Run one command. It installs the plugin and walks you through connecting:
31
19
 
32
20
  ```bash
33
- npx -y -p @ory/codex ory-codex install # registers the Ory marketplace + plugin with `codex`
34
- npx -y -p @ory/codex ory-codex uninstall # removes both
21
+ npx -y -p @ory/codex ory-codex install
35
22
  ```
36
23
 
37
- Then confirm everything landed:
24
+ This registers the Ory plugin with Codex (hooks, skills, and a bundled Ory tool server) and then asks how you want to connect — **press Enter for the default**:
25
+
26
+ - **Ory Network** *(default)* — sign in, or create a free account, in your browser. The project, keys, permissions, and login are all set up for you. Nothing to configure by hand.
27
+ - **Local** — run a complete Ory on your laptop with Docker. No account, no signup, no keys. Great for trying it out.
28
+ - **Audit-only** — skip Ory entirely and just log what Codex does.
29
+
30
+ That's it. Confirm everything landed with:
38
31
 
39
32
  ```bash
40
33
  npx -y -p @ory/codex ory-codex status
41
34
  ```
42
35
 
43
- `status` is the single source of truth — it prints configuration, user and agent identity, per-tool permission coverage, plugin + skill registration, and a tail of recent debug logs. Unconfigured fields show inline as `(unset)`.
44
-
45
- ## Quickstart (≈ 3 minutes)
46
-
47
- From any project where you'd like Ory authentication, inside Codex:
48
-
49
- 1. **Start a local Ory instance.** Ask Codex *"start the local Ory stack"* or pick `ory-local-up` from the `/skills` menu.
50
-
51
- A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
52
-
53
- 2. **Scaffold Ory into your project.** Ask Codex *"add Ory auth to this app"* or pick `ory-auth-setup` from `/skills`.
54
-
55
- Codex installs Ory Elements, wires the SDK, generates the login / registration / recovery / verification / settings pages, and sets up session middleware. It targets the local stack from step 1, so no signup or API key is needed.
56
-
57
- 3. **Sign in.** Start your app, visit the login page Codex added, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, with zero configuration.
58
-
59
- 4. **Turn on Ory login for the Codex session itself.** *(Optional but recommended.)* Out of the box the plugin only governs your *app*. To also attach an Ory identity to *Codex's* session — so every tool call is attributed to you, not a fallback `session:<id>` subject — opt in to the user-login flow:
36
+ `status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, and recent activity. Anything not set up yet shows as `(unset)`.
60
37
 
61
- ```bash
62
- export ORY_USER_LOGIN=true
63
- export ORY_OAUTH2_CLIENT_ID=<value printed by `local up`>
64
- ```
38
+ > **First launch: trust the Ory hooks.** Codex treats a freshly installed plugin's hooks as untrusted, so your first Codex session asks you to review and trust them. Sign-in and per-tool checks only start running once you do. In the TUI, that first check kicks in on your opening turn.
65
39
 
66
- User login is off by default. Both exports above are printed in the `local up` banner — copy them straight from there. `ORY_OAUTH2_CLIENT_ID` is required whenever `ORY_USER_LOGIN` is on: it identifies the public OAuth2 client the PKCE browser flow exchanges for a token. With both set, the next Codex session opens an Ory login in your browser; sign in with the same seeded credentials from step 1, and the token is reused on subsequent sessions until it expires. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
40
+ Re-run install with `--reconfigure` to change your connection later, or `--no-configure` to skip the wizard and connect by hand.
67
41
 
68
- That's the full Ory DX path. Stop here if you're just evaluating the plugin. Continue to [Agent security](#agent-security) when you're ready to enforce.
42
+ ## What you get
69
43
 
70
- ## What's included
44
+ Once connected, every tool Codex runs is governed by Ory — three things happen automatically:
71
45
 
72
- ### Skills for scaffolding Ory into your application
46
+ - **Who's driving.** You sign in once in your browser (a standard secure browser sign-in — no tokens to copy around). Codex itself registers its own identity automatically the first time it runs. The "who acted on whose behalf" trail stays queryable later.
47
+ - **What it's allowed to do.** Before a tool runs, Ory checks whether it's permitted. It starts in **watch mode** — nothing is blocked, you just *see* what would be — so it never gets in your way on day one.
48
+ - **A record of everything.** Every decision (allowed, denied, skipped) is logged as a trace you can send to Jaeger, Honeycomb, Grafana, or just a file.
73
49
 
74
- Codex surfaces the skill catalog in `/skills` and auto-invokes by description. Ask Codex in natural language or invoke a skill directly:
50
+ If Ory is ever unreachable, the plugin gets out of the way and lets Codex keep working — so it can't lock you out. That also means enforcement is only as strong as the permissions you grant.
75
51
 
76
- **Start here — add Ory auth to your app:**
52
+ ### See what's happening
77
53
 
78
- - **`ory-auth-setup`** — full project setup. Install the Ory CLI, create an Ory Network project (or use the local one), add Ory Elements, configure the SDK, build the auth pages, wire session middleware.
79
- - **`ory-login-flow`** — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
80
- - **`ory-social-login`** — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
81
- - **`ory-local-dev`** — drive the local Ory stack from within Codex to prototype and test without a remote project.
54
+ Everything the plugin does is observable out of the box — no configuration required:
82
55
 
83
- **Going further:**
56
+ - **Status at a glance.** `npx -y -p @ory/codex ory-codex status` shows what's configured, who's signed in, how many built-in tools your permissions cover, and the most recent tool-call activity.
57
+ - **Live traces.** Every tool call is recorded as an OpenTelemetry-style span. Watch them stream as the agent works:
84
58
 
85
- - **`ory-permissions-onboarding`** — bootstrap permissions for built-in tools, switch between observe and enforce mode, troubleshoot denials.
86
- - **`ory-build-integration`** — pull the runnable subset of an `ory/integrates` template (webhook / config / http-event) into your own app and wire it to your Ory project — no contribution/registry concerns.
87
- - **`ory-contribute-integration`** — author a brand-new integration as a contribution to `ory/integrates`, including `registry.entry.yaml`, the `Maintained by:` footer, DCO sign-off, and registry regeneration.
88
- - **`ory-e2b-sandbox`** — scaffold an [E2B](https://e2b.dev) sandbox template that boots with this plugin preinstalled and registered, so every sandbox session is gated by Ory auth, permissions, and tracing without any per-sandbox setup.
89
- - **`ory-build-agent`** — drop `@ory/argus` directly into a custom agent you own (Claude Agent SDK, OpenAI Agents SDK, Mastra, Vercel AI SDK, PydanticAI, LangGraph, Mistral AI, or Salesforce Agentforce) so the user is authenticated, every tool call is authorized against Ory Permissions, and the lifecycle emits trace spans.
90
- - **`ory-temporal-worker`** — scaffold a [Temporal](https://temporal.io) TypeScript worker per the [official local-dev guide](https://docs.temporal.io/develop/typescript/set-up-your-local-typescript), with every Activity gated by an Ory permission check, the worker's agent identity resolved via DCR, and the full lifecycle emitting trace spans.
59
+ ```bash
60
+ npx -y -p @ory/codex ory-codex watch
61
+ ```
91
62
 
92
- ### Ory MCP server
63
+ Spans are also written to `~/.config/ory-agent-plugins/codex/ory-agent-trace.ndjson` (NDJSON, one span per line) — tail that file, or point `OTEL_EXPORTER_OTLP_ENDPOINT` at a collector to ship them straight to Jaeger, Honeycomb, or Grafana.
64
+ - **Debug log.** For a verbose play-by-play, set `ORY_AGENT_DEBUG=true`; structured logs land in `~/.config/ory-agent-plugins/codex/ory-agent-debug.log`.
93
65
 
94
- Bundled and registered automatically. Exposes the Ory CLI and the Ory Network REST API as MCP tools so Codex can manage identities, OAuth2 clients, projects, permissions, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.
66
+ ### Ready to enforce?
95
67
 
96
- ### Local Ory stack
68
+ When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
97
69
 
98
- From Codex's `/skills` menu:
99
-
100
- ```
101
- ory-local-up # start a local Ory instance in Docker
102
- ory-local-down # tear it all down
103
- ory-temporal-up # start a local Temporal dev server (for ory-temporal-worker)
70
+ ```bash
71
+ npx -y -p @ory/codex ory-codex permissions enforce
104
72
  ```
105
73
 
106
- Or via the CLI: `npx -y -p @ory/codex ory-codex local up | down`.
107
-
108
- `ory-local-up` runs a complete Ory on your laptop: the Ory APIs (Identities, OAuth2, Permissions) at `http://localhost:4000`, a login UI on `:4455` (not :3000, to avoid Next.js port conflicts), and Jaeger (the trace viewer) on `:16686`. A test user identity is seeded and its credentials are printed for you. Use it to:
74
+ Now a denied tool is actually blocked and Codex shows why. Go back to watch mode anytime with `permissions observe`. Use `permissions status` to see what's covered and `permissions bootstrap` to (re-)grant the built-in tools — or just ask Codex in chat, e.g. *"grant me use of the shell tool."*
109
75
 
110
- - **Learn Ory hands-on** without signing up for a hosted project.
111
- - **Prototype** flows (login, social, MFA, recovery, permissions) against a real Ory backend.
112
- - **Test** an auth integration end-to-end before pushing anything to a real environment.
113
- - **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
76
+ ## Also: add login to your own app
114
77
 
115
- ## Pointing at a real Ory project
78
+ Beyond securing Codex, the plugin helps you build Ory into whatever you're working on. Ask Codex *"add Ory login to this app"* — or pick `ory-auth-setup` from the `/skills` menu — and it scaffolds the login, registration, recovery, and settings pages (using [Ory Elements](https://github.com/ory/elements)) wired to a local Ory, so no signup or keys are needed. Start that local Ory with the `ory-local-up` skill (it prints a test email + password to sign in with) and tear it down with `ory-local-down`.
116
79
 
117
- The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project (Ory's managed cloud), point the plugin at it with a single configure command. **The plugin requires `--oauth2-client-id` whenever `--project-url` is provided** — register the client first (see [Register the user OAuth2 client](#register-the-user-oauth2-client) below), then run:
118
-
119
- ```bash
120
- npx -y -p @ory/codex ory-codex configure \
121
- --project-url https://<id>.projects.oryapis.com \
122
- --oauth2-client-id <public OAuth2 client id>
123
- ```
80
+ Bundled **skills** (ask in plain language, or pick from `/skills`) cover more: `ory-auth-setup`, `ory-login-flow`, `ory-social-login` (Google, GitHub, Apple…), `ory-permissions-onboarding`, and playbooks for wiring Ory into your own agents, E2B sandboxes, or Temporal workers. A built-in **Ory tool server** lets Codex manage identities, projects, and permissions straight from chat.
124
81
 
125
- - **`--project-url`** points the plugin at your project. The **agent identity** (machine credentials for Codex's outgoing Ory API calls) is created automatically on first run via OAuth2 Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) against the project's `/oauth2/register` endpoint — no manual step required for that one.
126
- - **`--oauth2-client-id`** is required because the **user** PKCE browser flow (triggered by `ORY_USER_LOGIN=true`) cannot self-register — you must register a public OAuth2 client ahead of time and supply its id here. The configure command refuses to save a project URL without it, so you don't end up with a silently-broken setup later. See [Register the user OAuth2 client](#register-the-user-oauth2-client) below for the exact CLI / Console steps.
127
- - **`--api-key ory_pat_...`** is optional — pass it only if you want to override the auto-registered agent identity with a static personal access token (operator override; rarely needed).
82
+ ## Configure by hand (CI / advanced)
128
83
 
129
- If you only want audit logging (no auth or permission checks), substitute `--audit-only` — the OAuth2 client id is not required in that mode:
84
+ The guided setup covers most people. For scripted or CI setups, or to point at an existing Ory Network project, connect directly. Settings are saved to `~/.config/ory-agent-plugins/config.json` and shared across all your Ory agent plugins; environment variables win when both are set.
130
85
 
131
86
  ```bash
132
- npx -y -p @ory/codex ory-codex configure --audit-only
87
+ npx -y -p @ory/codex ory-codex configure \
88
+ --project-url https://<slug>.projects.oryapis.com \
89
+ --oauth2-client-id <sign-in client id> \
90
+ --user-login
133
91
  ```
134
92
 
135
- The same settings can be supplied via environment variables (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, `ORY_AGENT_API_KEY`) — env vars take precedence over the config file when both are set, which is what most CI / scripted setups want.
136
-
137
- Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine.
138
-
139
- Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked. You can stay in pass-through mode indefinitely if you only want the DX features.
140
-
141
- ### Register the user OAuth2 client
142
-
143
- If you plan to turn on `ORY_USER_LOGIN=true` (recommended — it's what attributes every tool call to *you* rather than a fallback `session:<id>` subject), your hosted Ory project needs a **public** OAuth2 client (no client secret) registered ahead of time. The local stack provisions this for you automatically; against a hosted project you have to register it once yourself.
144
-
145
- The client must list **all four** loopback ports as redirect URIs:
93
+ Codex's own identity registers itself automatically on first run — nothing to create. The `--oauth2-client-id` is the one piece browser sign-in needs; the guided setup makes it for you, or see below to do it by hand. For logging-only with no checks, use `--audit-only`.
146
94
 
147
- - `http://127.0.0.1:47823/callback`
148
- - `http://127.0.0.1:47824/callback`
149
- - `http://127.0.0.1:47825/callback`
150
- - `http://127.0.0.1:47826/callback`
95
+ <details>
96
+ <summary>Create the sign-in client by hand</summary>
151
97
 
152
- The plugin walks the four ports at runtime so the login can survive any one of them being occupied — Ory rejects the callback if the port it lands on isn't on the registered list, so register all four.
153
-
154
- Create the client with the [Ory CLI](https://www.ory.com/docs/guides/cli/installation):
98
+ The guided setup normally does this. To do it yourself, create a **public** OAuth2 client (no secret) listing all four loopback URLs — the plugin tries each in turn at runtime so sign-in survives a busy port, and Ory only accepts a callback on a URL you registered:
155
99
 
156
100
  ```bash
157
101
  ory create oauth2-client --project <project-id> \
@@ -166,104 +110,40 @@ ory create oauth2-client --project <project-id> \
166
110
  --redirect-uri http://127.0.0.1:47826/callback
167
111
  ```
168
112
 
169
- …or in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", set "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, paste the four redirect URIs above). Then persist the issued id with the configure command (preferred — survives across sessions):
170
-
171
- ```bash
172
- npx -y -p @ory/codex ory-codex configure \
173
- --project-url https://<id>.projects.oryapis.com \
174
- --oauth2-client-id <client-id from the step above>
175
- ```
176
-
177
- …or set it in the environment alongside `ORY_USER_LOGIN`:
178
-
179
- ```bash
180
- export ORY_USER_LOGIN=true
181
- export ORY_OAUTH2_CLIENT_ID=<client-id from the step above>
182
- ```
183
-
184
- Headless / CI runs that already hold a session token can skip this entirely by setting `ORY_USER_SESSION_TOKEN` instead — no browser flow runs, so no OAuth2 client is needed.
185
-
186
- ## Agent security
187
-
188
- Once the plugin is pointed at an Ory project (local or hosted), Codex's session and every tool call can be governed by Ory.
189
-
190
- - **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is enabled (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted token thereafter). The Codex process (the **agent**) gets its own OAuth2 identity, self-registered via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run.
191
- - **Authorization.** Before any tool runs, the plugin checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relations) against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
192
- - **Audit.** Every decision (allow, deny, fallback) is recorded as a structured trace span: NDJSON file output and/or OTLP/HTTP export to Jaeger, Honeycomb, Grafana, and similar collectors. The user → agent delegation is written to Ory as a relation so *"agent X acting on behalf of user Y"* stays queryable after tokens expire.
193
-
194
- The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your permission grants — grant explicit `use` on the tools each user should be able to run.
113
+ …or in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", set "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, paste the four URLs above). Pass the resulting id to `configure --oauth2-client-id`. Running headless with a session token already? Set `ORY_USER_SESSION_TOKEN` and skip the browser step entirely.
195
114
 
196
- ### Enable enforcement
115
+ </details>
197
116
 
198
- After install the plugin runs in **observe mode**: every tool call is checked against Ory Permissions, but a deny is recorded as a `permission.observe_deny` audit span and the tool runs anyway. This lets you see what *would* be blocked before turning on hard blocking.
117
+ With nothing configured, the plugin still loads and runs in **pass-through mode**: skills, commands, and logging work, but no checks run and nothing is blocked. Perfectly fine if you only want the app-building features.
199
118
 
200
- 1. **Turn on user login.** It's off by default. In your shell:
201
-
202
- ```bash
203
- export ORY_USER_LOGIN=true
204
- export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>
205
- ```
206
-
207
- The next Codex session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
208
-
209
- `ORY_OAUTH2_CLIENT_ID` is required when `ORY_USER_LOGIN` is on: PKCE needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`) to exchange the authorization code for a token. The local stack provisions one and prints the export in its `local up` banner; for a hosted Ory project see [Register the user OAuth2 client](#register-the-user-oauth2-client) for the exact CLI / Console steps. Headless / CI runs can skip the browser flow entirely by pre-supplying `ORY_USER_SESSION_TOKEN` instead.
210
-
211
- 2. **Bootstrap permissions for the built-in tools.** One idempotent command grants the current user `use` on every tool Codex ships with (shell, apply_patch, …):
212
-
213
- ```bash
214
- npx -y -p @ory/codex ory-codex permissions bootstrap
215
- ```
216
-
217
- If a user identity is already cached at install time, the installer runs this for you automatically — re-run after adding tools, switching subjects, or changing the namespace.
218
-
219
- 3. **Check coverage.** `permissions status` probes every tool in the harness's catalog and prints allowed / denied per tool:
220
-
221
- ```bash
222
- npx -y -p @ory/codex ory-codex permissions status
223
- ```
224
-
225
- Add permissions for any MCP server tools or custom commands by hand, or via the Ory MCP server from inside Codex (*"grant me use on the shell tool"*).
226
-
227
- 4. **Promote to enforce.** Once the observe-mode logs look right, switch over:
228
-
229
- ```bash
230
- npx -y -p @ory/codex ory-codex permissions enforce
231
- ```
232
-
233
- Denies now block the tool call; Codex shows the denial reason and the decision is recorded as a `tool.block` trace span with `blocked: true`. Switch back any time with `permissions observe`.
234
-
235
- ## CLI reference
119
+ ## Commands
236
120
 
237
121
  ```
238
- npx -y -p @ory/codex ory-codex install | uninstall
239
- npx -y -p @ory/codex ory-codex configure [--project-url <url> --oauth2-client-id <id>] [--api-key <key>] [--audit-only]
240
- npx -y -p @ory/codex ory-codex agent <status|unregister> Manage the agent's OAuth2 identity
241
- npx -y -p @ory/codex ory-codex permissions <status|bootstrap|observe|enforce>
242
- npx -y -p @ory/codex ory-codex local <up|down|status|seed|logs|env|configure|reset>
243
- npx -y -p @ory/codex ory-codex status
122
+ ory-codex install | uninstall Install/remove; --reconfigure re-runs setup, --no-configure skips it
123
+ ory-codex status Show configuration, identities, permission coverage, recent activity
124
+ ory-codex watch Tail the live trace stream (OTel spans)
125
+ ory-codex permissions <cmd> status | bootstrap | observe (watch) | enforce (block)
126
+ ory-codex configure <flags> Point at a project by hand (--project-url, --oauth2-client-id, --user-login, --audit-only)
127
+ ory-codex agent <status|unregister> Manage Codex's own auto-created identity
128
+ ory-codex local <up|down|status|…> Run / manage a local Ory in Docker
244
129
  ```
245
130
 
246
- Highlights:
131
+ All prefixed with `npx -y -p @ory/codex`.
247
132
 
248
- - `agent status` — show the current persisted DCR identity for the agent.
249
- - `permissions observe` / `permissions enforce` — switch between "log denies, allow through" (the install default) and "block denies." `permissions bootstrap` writes `use` permissions for the harness's built-in tools so the promotion path doesn't require hand-writing relations.
250
- - `configure --audit-only` — kill switch that disables Ory entirely (no auth, no permission checks; only audit logging of tool invocations). For phased rollouts, prefer `permissions observe` over `--audit-only`.
251
- - `local seed` / `local env` — reseed the test user, or print env vars for pointing other tools at the local stack.
133
+ The local stack runs a complete Ory on your laptop: the Ory APIs at `http://localhost:4000`, a login UI on `:4455` (not :3000, to avoid Next.js port conflicts), the Ory Console on `:4100`, and Jaeger (the trace viewer) on `:16686`.
252
134
 
253
135
  ## Troubleshooting
254
136
 
255
- - **`ory-local-up` fails.** Make sure Docker is running and ports `4455` (login UI), `4000`, `4100`, and `16686` are free.
256
- - **PKCE login loops.** Clear persisted state with `npx -y -p @ory/codex ory-codex agent unregister` and retry.
257
- - **`npx` fetches an old version.** Force a fresh fetch: `npx -y -p @ory/codex@latest ory-codex …`.
258
- - **`npm install … ENOVERSIONS`.** If your `~/.npmrc` sets `min-release-age`, npm filters out package versions newer than that threshold. Override per-call with `npm_config_min_release_age=0 npx -y -p @ory/codex ory-codex install`.
259
- - **`codex doctor` reports `ory-mcp-server is not resolvable`.** The bundled MCP server resolves via `npx -y -p @ory/mcp-server` on demand — make sure `npm`/`npx` is on PATH. The first session start fetches the server tarball; subsequent sessions reuse the cache.
260
- - **Need more signal.** Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=/tmp/ory.log` to capture structured logs.
137
+ - **`local up` fails** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
138
+ - **Browser sign-in loops** — reset with `ory-codex agent unregister` and try again.
139
+ - **`npx` grabbed an old version** — force the latest: `npx -y -p @ory/codex@latest ory-codex …`.
140
+ - **`npm install … ENOVERSIONS`** — if your `~/.npmrc` sets `min-release-age`, npm hides versions newer than that. Override per-call: `npm_config_min_release_age=0 npx -y -p @ory/codex ory-codex install`.
141
+ - **`codex doctor` says `ory-mcp-server is not resolvable`** — the bundled tool server is fetched on demand via `npx`, so make sure `npm`/`npx` is on your PATH. The first session downloads it; later ones reuse the cache.
142
+ - **Want to see what's happening** — `npx -y -p @ory/codex ory-codex status` for a snapshot, `npx -y -p @ory/codex ory-codex watch` for the live trace stream, or set `ORY_AGENT_DEBUG=true` for a verbose log. Traces and logs live under `~/.config/ory-agent-plugins/codex/` (see [See what's happening](#see-whats-happening)).
261
143
 
262
- ## Links
144
+ ## Learn more
263
145
 
264
- - [Ory documentation](https://www.ory.com/docs/)
265
- - [Ory Network console](https://console.ory.sh)
266
- - [Ory Elements](https://github.com/ory/elements)
146
+ - [Ory documentation](https://www.ory.com/docs/) · [Ory Console](https://console.ory.sh) · [Ory Elements](https://github.com/ory/elements)
267
147
  - [Codex documentation](https://github.com/openai/codex)
268
148
 
269
149
  ## License
package/dist/cli/main.js CHANGED
@@ -55,14 +55,19 @@ function main() {
55
55
  const [command, ...args] = process.argv.slice(2);
56
56
  switch (command) {
57
57
  case "install":
58
+ (0, argus_1.beginDeferNextSteps)();
58
59
  (0, setup_js_1.install)(args);
59
- postInstallPermissions("ory-codex", "codex").then(() => process.exit(0), (err) => {
60
+ (0, argus_1.runPostInstall)("ory-codex", "codex", args).then(() => process.exit(0), (err) => {
60
61
  console.error(err.message ?? err);
61
62
  process.exit(1);
62
63
  });
63
64
  break;
64
65
  case "uninstall":
65
66
  (0, setup_js_1.uninstall)(args);
67
+ (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
68
+ console.error(err.message ?? err);
69
+ process.exit(1);
70
+ });
66
71
  break;
67
72
  case "configure":
68
73
  (0, argus_1.runConfigureCommand)("ory-codex", args);
@@ -91,6 +96,9 @@ function main() {
91
96
  process.exit(1);
92
97
  });
93
98
  break;
99
+ case "watch":
100
+ (0, argus_1.runWatchCommand)("codex", args);
101
+ break;
94
102
  case "help":
95
103
  case "--help":
96
104
  case "-h":
@@ -103,12 +111,6 @@ function main() {
103
111
  process.exit(1);
104
112
  }
105
113
  }
106
- async function postInstallPermissions(binName, harness) {
107
- const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
108
- (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
109
- bootstrappedAutomatically: bootstrapped,
110
- });
111
- }
112
114
  async function status() {
113
115
  await (0, argus_1.runStatusCommand)("ory-codex", "codex", {
114
116
  title: "Codex",
@@ -124,7 +126,7 @@ function help() {
124
126
  ory-codex — Ory plugin for Codex
125
127
 
126
128
  Usage:
127
- npx ory-codex <command> [options]
129
+ npx -y -p @ory/codex ory-codex <command> [options]
128
130
 
129
131
  Commands:
130
132
  install Install via \`codex plugin marketplace add\` + \`codex plugin add\`
@@ -136,14 +138,15 @@ Commands:
136
138
  local <cmd> Manage local Ory dev environment
137
139
  (up, down, status, seed, logs, env, configure, reset)
138
140
  status Show plugin status, config, and recent log lines
141
+ watch [trace-file] Tail the trace stream (OTel spans) live
139
142
 
140
143
  Examples:
141
- npx ory-codex install
142
- npx ory-codex configure --project-url https://<id>.projects.oryapis.com \\
144
+ npx -y -p @ory/codex ory-codex install
145
+ npx -y -p @ory/codex ory-codex configure --project-url https://<slug>.projects.oryapis.com \\
143
146
  --api-key ory_pat_...
144
- npx ory-codex permissions status
145
- npx ory-codex status
146
- npx ory-codex uninstall
147
+ npx -y -p @ory/codex ory-codex permissions status
148
+ npx -y -p @ory/codex ory-codex status
149
+ npx -y -p @ory/codex ory-codex uninstall
147
150
 
148
151
  Requires the \`codex\` CLI on PATH.
149
152
  `);
package/dist/cli/setup.js CHANGED
@@ -83,6 +83,15 @@ const MARKETPLACE_ROOT = path.join((0, argus_1.getHarnessDataDir)("codex"), "mar
83
83
  const PLUGIN_ROOT = path.join(MARKETPLACE_ROOT, "plugins", PLUGIN_NAME);
84
84
  /** Hook command that resolves via the npm registry on every invocation. */
85
85
  const HOOK_COMMAND = "npx -y -p @ory/codex ory-codex-hook";
86
+ /**
87
+ * Per-handler timeout (seconds). Codex kills a hook subprocess after this
88
+ * window (its built-in default is only 5s). SessionStart may run the
89
+ * interactive user login (PKCE browser flow), which needs a human in the
90
+ * loop, so it gets a generous window; the tool-lifecycle hooks only make a
91
+ * permission check, so a shorter window is plenty.
92
+ */
93
+ const SESSION_START_TIMEOUT_SEC = 300;
94
+ const TOOL_HOOK_TIMEOUT_SEC = 60;
86
95
  function readPackageVersion() {
87
96
  try {
88
97
  const pj = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf-8"));
@@ -129,13 +138,16 @@ function copyMarketplaceSkeleton() {
129
138
  }
130
139
  /**
131
140
  * Patch the plugin manifest with the runtime values that depend on the
132
- * installed npm package (currently just the version). Keeps the rest of the
133
- * static manifest untouched.
141
+ * installed npm package (the version) and re-assert the `hooks` pointer.
142
+ * Codex only wires up `hooks.json` when the manifest declares it, so we set
143
+ * it here as well as in the static skeleton to survive skeleton drift. Keeps
144
+ * the rest of the static manifest untouched.
134
145
  */
135
146
  function updatePluginManifest() {
136
147
  const manifestPath = path.join(PLUGIN_ROOT, ".codex-plugin", "plugin.json");
137
148
  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
138
149
  manifest.version = PACKAGE_VERSION;
150
+ manifest.hooks = "./hooks.json";
139
151
  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
140
152
  }
141
153
  /**
@@ -161,21 +173,39 @@ function renderCommands() {
161
173
  fs.writeFileSync(path.join(commandsDir, `${cmd.slug}.md`), (0, argus_1.commandToFrontmatterMarkdown)(cmd));
162
174
  }
163
175
  }
176
+ /**
177
+ * A Codex hook event maps to an array of matcher groups, each carrying its
178
+ * own list of command handlers (the same nested shape Claude Code uses). We
179
+ * register a single unmatched group so the handler runs for every event
180
+ * occurrence. Emitting the handler flat (without the wrapping group) parses
181
+ * as a matcher group with zero handlers, so the hook silently never runs.
182
+ */
183
+ function hookGroup(timeoutSec) {
184
+ return [
185
+ {
186
+ hooks: [{ type: "command", command: HOOK_COMMAND, timeout: timeoutSec }],
187
+ },
188
+ ];
189
+ }
164
190
  /**
165
191
  * Generate the hooks file. Hook command resolves the bin via `npx`, so the
166
192
  * path is stable across npm cache evictions and version bumps.
193
+ *
194
+ * Codex only loads this file when `plugin.json` declares `hooks` (see the
195
+ * marketplace skeleton); it is not auto-discovered by filename. Fresh plugin
196
+ * hooks are also untrusted until the user reviews them in Codex's hook-trust
197
+ * UI — see `printNextSteps`.
167
198
  */
168
199
  function writeHooks() {
169
200
  const hooksPath = path.join(PLUGIN_ROOT, "hooks.json");
170
- const entry = [{ type: "command", command: HOOK_COMMAND }];
171
201
  fs.writeFileSync(hooksPath, JSON.stringify({
172
202
  hooks: {
173
- SessionStart: entry,
174
- PreToolUse: entry,
175
- PostToolUse: entry,
176
- PermissionRequest: entry,
177
- UserPromptSubmit: entry,
178
- Stop: entry,
203
+ SessionStart: hookGroup(SESSION_START_TIMEOUT_SEC),
204
+ PreToolUse: hookGroup(TOOL_HOOK_TIMEOUT_SEC),
205
+ PostToolUse: hookGroup(TOOL_HOOK_TIMEOUT_SEC),
206
+ PermissionRequest: hookGroup(TOOL_HOOK_TIMEOUT_SEC),
207
+ UserPromptSubmit: hookGroup(TOOL_HOOK_TIMEOUT_SEC),
208
+ Stop: hookGroup(TOOL_HOOK_TIMEOUT_SEC),
179
209
  },
180
210
  }, null, 2) + "\n");
181
211
  }
@@ -255,11 +285,45 @@ function uninstall(_args) {
255
285
  }
256
286
  }
257
287
  function printNextSteps() {
288
+ (0, argus_1.nextStepsSink)(({ configured }) => configured ? printConfiguredNextStepsNow() : printNextStepsNow());
289
+ }
290
+ /**
291
+ * Closing message when the interactive wizard already connected Ory. Drops the
292
+ * manual "point at a project" steps (they'd contradict what's saved) but keeps
293
+ * Codex's harness-specific note about trusting freshly installed hooks.
294
+ */
295
+ function printConfiguredNextStepsNow() {
296
+ const npx = "npx -y -p @ory/codex ory-codex";
297
+ console.log("");
298
+ console.log("Next steps:");
299
+ console.log(" Start a Codex session — Ory is configured and ready. Codex treats");
300
+ console.log(" freshly installed plugin hooks as untrusted, so it will prompt you to");
301
+ console.log(" review and trust the Ory hooks on first launch; the auth gate and");
302
+ console.log(" per-tool permission checks only run once they're trusted.");
303
+ console.log("");
304
+ if ((0, argus_1.resolveConfig)().auditOnly) {
305
+ console.log(" Audit-only mode: tool calls are traced locally — no checks, nothing blocked.");
306
+ console.log("");
307
+ console.log(` 1. See what's been traced: ${npx} status (or watch live: ${npx} watch)`);
308
+ console.log(" 2. More detail? export ORY_AGENT_DEBUG=true");
309
+ }
310
+ else {
311
+ console.log(" It starts in watch mode: every tool call is checked, nothing blocked yet.");
312
+ console.log("");
313
+ console.log(` 1. See what Ory is doing: ${npx} status (or watch live: ${npx} watch)`);
314
+ console.log(` 2. Turn on enforcement: ${npx} permissions enforce`);
315
+ console.log(` (back to watch: ${npx} permissions observe)`);
316
+ console.log(" 3. More detail? export ORY_AGENT_DEBUG=true");
317
+ }
318
+ console.log("");
319
+ console.log(`To uninstall: ${npx} uninstall`);
320
+ }
321
+ function printNextStepsNow() {
258
322
  console.log("");
259
323
  console.log("Next steps:");
260
324
  console.log(" 1. (Optional) Point at an Ory project — without this, the plugin");
261
325
  console.log(" runs in pass-through mode (skills work, nothing is blocked):");
262
- console.log(" npx ory-codex configure --project-url https://<id>.projects.oryapis.com \\");
326
+ console.log(" npx -y -p @ory/codex ory-codex configure --project-url https://<slug>.projects.oryapis.com \\");
263
327
  console.log(" --oauth2-client-id <public OAuth2 client id>");
264
328
  console.log(" (`--oauth2-client-id` is required when --project-url is set, because the");
265
329
  console.log(" user PKCE browser flow needs a pre-registered public client. Add");
@@ -272,9 +336,12 @@ function printNextSteps() {
272
336
  console.log(" Without this, Codex runs without a human Ory identity attached to the");
273
337
  console.log(" session and permission checks fall back to a session:<id> subject.");
274
338
  console.log("");
275
- console.log(" 4. Start a Codex session — Ory hooks are now wired in.");
339
+ console.log(" 4. Start a Codex session. Codex treats freshly installed plugin");
340
+ console.log(" hooks as untrusted, so it will prompt you to review and trust");
341
+ console.log(" the Ory hooks on first launch — the auth gate and per-tool");
342
+ console.log(" permission checks only run once they're trusted.");
276
343
  console.log("");
277
- console.log("To uninstall: npx ory-codex uninstall");
344
+ console.log("To uninstall: npx -y -p @ory/codex ory-codex uninstall");
278
345
  }
279
346
  // --- Standalone binary entry point (ory-codex-setup) ---
280
347
  if (require.main === module) {
@@ -283,7 +350,7 @@ if (require.main === module) {
283
350
  ory-codex-setup — Install or remove the Ory plugin for Codex
284
351
 
285
352
  Usage:
286
- npx ory-codex-setup [options]
353
+ npx -y -p @ory/codex ory-codex-setup [options]
287
354
 
288
355
  Options:
289
356
  --uninstall Remove the Ory plugin and marketplace
@@ -302,6 +369,12 @@ refreshes Codex's cache copy on the next session.
302
369
  const args = process.argv.slice(2);
303
370
  if (args.includes("--uninstall")) {
304
371
  uninstall(args);
372
+ // Direct `-setup --uninstall` path: also clear stored Ory credentials.
373
+ // (The `ory-codex uninstall` command handles this itself.)
374
+ (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
375
+ console.error(err.message ?? err);
376
+ process.exit(1);
377
+ });
305
378
  }
306
379
  else {
307
380
  install(args);
package/dist/handlers.d.ts CHANGED
@@ -10,8 +10,8 @@ export interface HandleHookEventDeps {
10
10
  * Route a Codex hook event to the appropriate Ory integration.
11
11
  *
12
12
  * Codex events: SessionStart, PreToolUse, PostToolUse, PermissionRequest,
13
- * UserPromptSubmit, Stop. Hooks must be enabled via
14
- * `[features] codex_hooks = true` in `~/.codex/config.toml`.
13
+ * UserPromptSubmit, Stop. Hooks are declared by the plugin (`hooks` in
14
+ * plugin.json → hooks.json) and must be trusted by the user before they run.
15
15
  */
16
16
  export declare function handleHookEvent(input: CodexHookInput, client: OryAgentClient, deps?: HandleHookEventDeps): Promise<CodexHookOutput>;
17
17
  /**
package/dist/handlers.js CHANGED
@@ -7,8 +7,8 @@ const argus_1 = require("@ory/argus");
7
7
  * Route a Codex hook event to the appropriate Ory integration.
8
8
  *
9
9
  * Codex events: SessionStart, PreToolUse, PostToolUse, PermissionRequest,
10
- * UserPromptSubmit, Stop. Hooks must be enabled via
11
- * `[features] codex_hooks = true` in `~/.codex/config.toml`.
10
+ * UserPromptSubmit, Stop. Hooks are declared by the plugin (`hooks` in
11
+ * plugin.json → hooks.json) and must be trusted by the user before they run.
12
12
  */
13
13
  async function handleHookEvent(input, client, deps = {}) {
14
14
  const event = input.hook_event_name;
package/dist/types.d.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  /**
2
2
  * Codex hook event payload delivered on stdin.
3
3
  *
4
- * Codex uses a subprocess hook model (JSON stdin/stdout). Hooks are
5
- * feature-gated behind `[features] codex_hooks = true` in config.toml.
4
+ * Codex uses a subprocess hook model (JSON stdin/stdout). Hooks ship in the
5
+ * plugin (declared via `hooks` in plugin.json); Codex requires the user to
6
+ * trust freshly installed plugin hooks before they run.
6
7
  *
7
8
  * Canonical `tool_name` values:
8
9
  * - `"Bash"`
package/marketplace/plugins/ory-codex/.codex-plugin/plugin.json CHANGED
@@ -19,6 +19,7 @@
19
19
  "zanzibar"
20
20
  ],
21
21
  "skills": "./skills/",
22
+ "hooks": "./hooks.json",
22
23
  "mcpServers": "./.mcp.json",
23
24
  "interface": {
24
25
  "displayName": "Ory",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ory/codex",
3
- "version": "0.11.1",
3
+ "version": "0.12.1",
4
4
  "description": "Ory plugin for Codex: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://ory.com",
@@ -66,7 +66,8 @@
66
66
  "marketplace"
67
67
  ],
68
68
  "dependencies": {
69
- "@ory/argus": "0.11.1"
69
+ "reo-census": "^1.2.8",
70
+ "@ory/argus": "0.12.1"
70
71
  },
71
72
  "engines": {
72
73
  "node": ">=22"