@ory/pi 0.11.0 → 0.12.0

package/README.md

@@ -1,126 +1,142 @@
 # Ory Agent Plugin: Pi
 
-[Ory](https://ory.com) bundled into [Pi](https://pi.dev) ([badlogic/pi-mono](https://github.com/badlogic/pi-mono), a minimal coding agent): skills and commands 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 Pi runs.
+Security and developer experience for [Pi](https://pi.dev), powered by [Ory](https://ory.com).
 
-You don't need an Ory account or any prior Ory experience to start.
+**Security.** Pi 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; Pi 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.
 
-The extension contract is verified against `@earendil-works/pi-coding-agent` v0.80.2 — the `session_start`/`tool_call`/`tool_result` events, the `tool_call` block signature (`{ block?, reason? }`), the `~/.pi/agent` config root, the `.pi/extensions/` auto-discovery loader, and the `.pi/skills/` location all match.
+**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.
 
-## New to Ory?
+## What you'll need
 
-[Ory](https://www.ory.com/docs/) is an open-source identity and access platform — 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:
-
-- **Ory Elements** are prebuilt, themeable UI components for the auth pages. The scaffolding skills wire them into your app for you.
-- **The local Ory stack** is a complete Ory running on your laptop in Docker — no account, no signup, no API key.
-
-## What this plugin does
-
-Two independent things, and you can use either on its own:
+- [Pi](https://pi.dev) installed (`@earendil-works/pi-coding-agent`)
+- Node.js **22 or newer**
+- [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
+- macOS or Linux (Windows works via WSL2)
 
-1. **Build auth into your app.** Have Pi scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This needs nothing but Docker.
-2. **Govern the agent itself.** Authenticate Pi's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See [Agent security](#agent-security).
+Pi loads the plugin from your project's `node_modules`, so add it to your project first:
 
-## Prerequisites
+```bash
+npm install @ory/pi
+```
 
-- [Pi](https://pi.dev) installed (`@earendil-works/pi-coding-agent`)
-- Node.js **≥ 22**
-- [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
-- macOS or Linux. Windows works via WSL2.
+## Get started
 
-## Install
+Then run one command. It installs the plugin and walks you through connecting:
 
 ```bash
 npx -y -p @ory/pi ory-pi install
 ```
 
-`install` drops a tiny loader file at `<project>/.pi/extensions/ory.js` (project scope, the default) — Pi auto-discovers every `*.js`/`*.ts` file under `.pi/extensions/` and runs its default export as an extension factory, so the loader simply re-exports the installed `@ory/pi` package's factory (`export { default } from "@ory/pi";`). No `settings.json` entry is needed. With `--global` the loader lands at `~/.pi/agent/extensions/ory.js` instead. Install also materializes the Ory skills and commands under `<project>/.pi/skills`.
+The installer drops a tiny loader at `<project>/.pi/extensions/ory.js` so Pi discovers the plugin, adds the Ory skills under `<project>/.pi/skills`, and then asks how you want to connect — **press Enter for the default**:
+
+- **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.
+- **Local** — run a complete Ory on your laptop with Docker. No account, no signup, no keys. Great for trying it out.
+- **Audit-only** — skip Ory entirely and just log what Pi does.
 
-The plugin must be resolvable from the project's `node_modules`, so install `@ory/pi` first (`npm install @ory/pi` or add it to your project's dependencies) before running `ory-pi install`.
+That's it. Confirm everything landed with:
 
 ```bash
-npx -y -p @ory/pi ory-pi install --global   # install the loader for all projects
-npx -y -p @ory/pi ory-pi status             # confirm the loader + hooks
-npx -y -p @ory/pi ory-pi uninstall          # remove the loader and skills
+npx -y -p @ory/pi ory-pi status
 ```
 
-`status` prints configuration, user and agent identity, per-tool permission coverage, whether the extension loader is installed, the hooks it wires up, and a tail of recent debug logs.
+`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, whether the loader is in place, and recent activity. Anything not set up yet shows as `(unset)`.
+
+Re-run install with `--reconfigure` to change your connection later, or `--no-configure` to skip the wizard. Add `--global` to install the loader for all projects (at `~/.pi/agent/extensions/ory.js`) instead of just this one.
 
-### Alternative: install via Pi's package manager
+<details>
+<summary>Prefer to let Pi manage the plugin?</summary>
 
-If you prefer Pi to manage the extension, point its package installer at the npm package:
+Point Pi's own package installer at the npm package:
 
 ```bash
 pi install npm:@ory/pi
 ```
 
-This records the package under `settings.packages` and reads the `pi.extensions` manifest from `@ory/pi`'s `package.json` (which points at `dist/index.js`, the default-exported factory). Either path leads to the same extension; pick whichever fits your workflow.
+This registers the extension through Pi's package manifest, but skips the guided setup — run `npx -y -p @ory/pi ory-pi install` (or `configure`) in a terminal afterwards to connect.
 
-## Quickstart (≈ 3 minutes)
+</details>
 
-From any project where you'd like Ory authentication, inside Pi:
+## What you get
 
-1. **Start a local Ory instance.** Ask Pi *"start the local Ory stack"* or invoke the `ory-local-up` skill. A banner prints the seeded test user's email and password — note them.
-2. **Scaffold Ory into your project.** Ask Pi *"add Ory auth to this app"* (the `ory-auth-setup` skill). It installs Ory Elements, wires the SDK, and generates the login / registration / recovery / settings pages, all targeting the local stack.
-3. **Sign in.** Start your app, visit the login page, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, zero configuration.
+Once connected, every tool Pi runs is governed by Ory — three things happen automatically:
 
-Continue to [Agent security](#agent-security) when you're ready to enforce.
+- **Who's driving.** You sign in once in your browser (a secure redirect flow — no passwords touch the plugin), and Pi gets its own identity that it registers automatically on first run. No tokens to copy around, and the "who did what" trail stays queryable later. (Pi's startup can't hard-block, so sign-in there is advisory — it still signs you in and logs it, but never stops the session.)
+- **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.
+- **A record of everything.** Every decision (allowed, denied, skipped) is logged as a trace you can send to a viewer like Jaeger, or just a file.
 
-## How the integration works
+If Ory is ever unreachable, the plugin gets out of the way and lets Pi keep working — so it can't lock you out.
 
-Pi loads in-process **TypeScript/JavaScript extensions** auto-discovered from `.pi/extensions/` (project) and `~/.pi/agent/extensions/` (global), loaded with [jiti](https://github.com/unjs/jiti). Each file's **default export** is invoked as a factory function at startup; the installed loader re-exports `@ory/pi`'s default factory.
+> Pi has no MCP support and no sub-agents by design, so there's nothing extra to register — just the plugin itself.
 
-The phases map as:
+### See what's happening
 
-- **Session start** (factory body) — run the user and agent auth gates. Advisory only: Pi's factory has no return-value channel to hard-block at session start, so user login refreshes tokens and emits an audit span but the session always proceeds.
-- **Per-tool decision** — the factory registers a `pi.on("tool_call")` handler that checks the tool against Ory Permissions. In enforce mode a deny **blocks by returning `{ block: true, reason }`**; in observe mode it records a `permission.observe_deny` span and allows.
-- **Post-tool** — a `pi.on("tool_result")` handler records a `tool.complete` trace span. Trace-only.
+Everything the plugin does is observable out of the box — no configuration required:
 
-**Pi excludes MCP and sub-agents by design**, so this plugin has **no MCP server registration and no sub-agent identity path** — unlike the Claude Code or Continue plugins, there is nothing to register beyond the extension itself.
+- **Status at a glance.** `npx -y -p @ory/pi ory-pi status` shows what's configured, who's signed in, how many built-in tools your permissions cover, and the most recent tool-call activity.
+- **Live traces.** Every tool call is recorded as an OpenTelemetry-style span. Watch them stream as the agent works:
 
-The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config): the agent always starts, and enforcement is only as strong as your permission grants.
+  ```bash
+  npx -y -p @ory/pi ory-pi watch
+  ```
 
-## Agent security
+  Spans are also written to `~/.config/ory-agent-plugins/pi/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.
+- **Debug log.** For a verbose play-by-play, set `ORY_AGENT_DEBUG=true`; structured logs land in `~/.config/ory-agent-plugins/pi/ory-agent-debug.log`.
 
-Once pointed at an Ory project (local or hosted), Pi's session and every tool call can be governed by Ory.
+### Ready to enforce?
 
-- **Authentication.** The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is on (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted thereafter). The Pi process (the **agent**) gets its own OAuth2 identity via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run.
-- **Authorization.** Before any tool runs, the `tool_call` handler checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relations) against the user's subject and blocks on `deny`.
-- **Audit.** Every decision is recorded as a structured trace span (NDJSON file and/or OTLP export).
-
-### Permission modes: observe → enforce
-
-After install the plugin runs in **observe mode**: every tool call is checked, but a deny is recorded as a `permission.observe_deny` audit span and the tool runs anyway.
+When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
 
 ```bash
-# Grant the current user `use` on every built-in tool (idempotent):
-npx -y -p @ory/pi ory-pi permissions bootstrap
-
-# See allowed/denied per tool:
-npx -y -p @ory/pi ory-pi permissions status
-
-# Turn on hard blocking once the observe-mode logs look right:
 npx -y -p @ory/pi ory-pi permissions enforce
 ```
 
-Switch back any time with `permissions observe`. To disable Ory entirely (audit logging only), run `ory-pi configure --audit-only`.
+Now a denied tool is actually blocked and Pi shows why (the plugin returns `{ block: true, reason }` on Pi's `tool_call` event). 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.
+
+## Also: add login to your own app
+
+Beyond securing Pi, the plugin helps you build Ory into whatever you're working on. Ask Pi *"add Ory login to this app"* and it scaffolds the login, registration, recovery, and settings pages (using [Ory Elements](https://github.com/ory/elements)) wired to a local Ory — no signup or keys needed. Start that local Ory by asking Pi *"start the local Ory stack"* (the `ory-local-up` skill) — it prints a test email + password to sign in with — and tear it down with `ory-local-down`.
 
-## Pointing at a real Ory project
+Bundled **skills** (just ask in plain language) 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.
 
-The Quickstart uses the local stack. To point at a hosted [Ory Network](https://console.ory.sh) project:
+## Configure by hand (CI / advanced)
+
+The guided setup covers most people. For scripted or CI setups, or to point at an existing Ory Network project, configure 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.
 
 ```bash
 npx -y -p @ory/pi ory-pi configure \
-  --project-url https://<id>.projects.oryapis.com \
-  --oauth2-client-id <public OAuth2 client id>
+  --project-url https://<slug>.projects.oryapis.com \
+  --oauth2-client-id <sign-in client id> \
+  --user-login
 ```
 
-`--oauth2-client-id` is required whenever `--project-url` is set — the user PKCE flow needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`). See the [repo README](../../README.md) and [`AGENTS.md`](../../AGENTS.md) for the full environment-variable reference and permission-mode semantics. Config is shared across every Ory agent plugin at `~/.config/ory-agent-plugins/config.json`.
+Pi'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 public sign-in client, registered with the four loopback URLs `http://127.0.0.1:47823..47826/callback`; the guided setup makes it for you. For logging-only with no checks, use `--audit-only`. The equivalent env vars are `ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, and `ORY_USER_LOGIN`.
+
+With nothing configured, the plugin still loads and runs in **pass-through mode**: skills and logging work, but no checks run and nothing is blocked. Perfectly fine if you only want the app-building features.
+
+## Commands
+
+```
+ory-pi install | uninstall        Install/remove; --reconfigure re-runs setup, --no-configure skips it, --global for all projects
+ory-pi status                     Show configuration, identities, permission coverage, recent activity
+ory-pi watch                      Tail the live trace stream (OTel spans)
+ory-pi permissions <cmd>          status | bootstrap | observe (watch) | enforce (block)
+ory-pi configure <flags>          Point at a project by hand (--project-url, --oauth2-client-id, --user-login, --audit-only)
+ory-pi agent <status|unregister>  Manage Pi's own auto-created identity
+```
+
+All prefixed with `npx -y -p @ory/pi`.
+
+## Troubleshooting
 
-Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills and commands work, but nothing is blocked.
+- **Local Ory won't start** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
+- **Browser sign-in loops** — reset with `ory-pi agent unregister` and try again.
+- **`npx` grabbed an old version** — force the latest: `npx -y -p @ory/pi@latest ory-pi …`.
+- **Pi can't find the plugin** — make sure `@ory/pi` is installed in the project (`npm install @ory/pi`) and the loader exists at `.pi/extensions/ory.js`; re-run the installer if not.
+- **Want to see what's happening** — `npx -y -p @ory/pi ory-pi status` for a snapshot, `npx -y -p @ory/pi ory-pi 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/pi/` (see [See what's happening](#see-whats-happening)).
 
-## Links
+## Learn more
 
-- [Ory documentation](https://www.ory.com/docs/)
+- [Ory documentation](https://www.ory.com/docs/) · [Ory Console](https://console.ory.sh) · [Ory Elements](https://github.com/ory/elements)
 - [Pi repository](https://github.com/badlogic/pi-mono)
 - [Repo README](../../README.md) and [AGENTS.md](../../AGENTS.md) — full env-var and permission-mode reference
 

package/dist/cli/main.js

@@ -52,14 +52,19 @@ function main() {
     const [command, ...args] = process.argv.slice(2);
     switch (command) {
         case "install":
+            (0, argus_1.beginDeferNextSteps)();
             install(args);
-            postInstallPermissions("ory-pi", "pi").then(() => process.exit(0), (err) => {
+            (0, argus_1.runPostInstall)("ory-pi", "pi", args).then(() => process.exit(0), (err) => {
                 console.error(err.message ?? err);
                 process.exit(1);
             });
             break;
         case "uninstall":
             uninstall(args);
+            (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
             break;
         case "configure":
             (0, argus_1.runConfigureCommand)("ory-pi", args);
@@ -89,7 +94,7 @@ function main() {
             });
             break;
         case "watch":
-            (0, argus_1.runWatchCommand)(args);
+            (0, argus_1.runWatchCommand)("pi", args);
             break;
         case "help":
         case "--help":
@@ -103,12 +108,6 @@ function main() {
             process.exit(1);
     }
 }
-async function postInstallPermissions(binName, harness) {
-    const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
-    (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
-        bootstrappedAutomatically: bootstrapped,
-    });
-}
 function parseProjectDir(args) {
     const idx = args.indexOf("--project-dir");
     if (idx !== -1 && args[idx + 1])
@@ -186,7 +185,7 @@ After installing, the plugin hooks into these Pi lifecycle events:
 
 Examples:
   npx -y -p @ory/pi ory-pi install
-  npx -y -p @ory/pi ory-pi configure --project-url https://<id>.projects.oryapis.com --api-key ory_pat_...
+  npx -y -p @ory/pi ory-pi configure --project-url https://<slug>.projects.oryapis.com --api-key ory_pat_...
   npx -y -p @ory/pi ory-pi permissions bootstrap
   npx -y -p @ory/pi ory-pi local up
   npx -y -p @ory/pi ory-pi status

package/dist/cli/setup.js

@@ -93,6 +93,18 @@ function main() {
     (0, assets_js_1.installPiOryAssets)(args.projectDir);
     console.log(`Ory extension loader installed at ${loaderPath}`);
     console.log(`Ory skills installed to ${path.join(args.projectDir, ".pi", "skills")}`);
-    (0, argus_1.printNextSteps)("Pi", "npx ory-pi-setup --uninstall");
+    (0, argus_1.printNextSteps)("Pi", "npx -y -p @ory/pi ory-pi-setup --uninstall", {
+        binName: "ory-pi",
+        harness: "pi",
+    });
 }
 main();
+// When invoked directly as the `-setup` bin with `--uninstall`, also clear
+// stored Ory credentials. When required by the plugin's main CLI, that
+// command owns the purge, so the `require.main` guard prevents a double run.
+if (require.main === module && process.argv.includes("--uninstall")) {
+    (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
+        console.error(err.message ?? err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/pi",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Ory plugin for Pi (the minimal coding agent): scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -72,7 +72,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.11.0"
+    "@ory/argus": "0.12.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",