@ory/pi 0.10.0

package/README.md

@@ -0,0 +1,129 @@
+# 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.
+
+You don't need an Ory account or any prior Ory experience to start.
+
+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.
+
+## New to Ory?
+
+[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:
+
+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).
+
+## Prerequisites
+
+- [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.
+
+## Install
+
+```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 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`.
+
+```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
+```
+
+`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.
+
+### Alternative: install via Pi's package manager
+
+If you prefer Pi to manage the extension, point its 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.
+
+## Quickstart (≈ 3 minutes)
+
+From any project where you'd like Ory authentication, inside Pi:
+
+1. **Start a local Ory instance.** Ask Pi *"start the local Ory stack"* or run `/local-up`. 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.
+
+Continue to [Agent security](#agent-security) when you're ready to enforce.
+
+## How the integration works
+
+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.
+
+The phases map as:
+
+- **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.
+
+**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.
+
+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.
+
+## Agent security
+
+Once pointed at an Ory project (local or hosted), Pi's session and every tool call can be governed by Ory.
+
+- **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.
+
+```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`.
+
+## Pointing at a real Ory project
+
+The Quickstart uses the local stack. To point at a hosted [Ory Network](https://console.ory.sh) project:
+
+```bash
+npx -y -p @ory/pi ory-pi configure \
+  --project-url https://<id>.projects.oryapis.com \
+  --oauth2-client-id <public OAuth2 client id>
+```
+
+`--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`.
+
+Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills and commands work, but nothing is blocked.
+
+## Links
+
+- [Ory documentation](https://www.ory.com/docs/)
+- [Pi repository](https://github.com/badlogic/pi-mono)
+- [Repo README](../../README.md) and [AGENTS.md](../../AGENTS.md) — full env-var and permission-mode reference
+
+## License
+
+Apache-2.0

package/dist/cli/assets.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Materialize / clean the Ory skill catalog and command-skills for the Pi
+ * plugin. The guide skills plus the local-stack commands (rendered as
+ * user-invocable skills) land at `<projectDir>/.pi/skills/<name>/SKILL.md`.
+ *
+ * Pi has a skills system but no native slash-command system to rely on, so —
+ * like Codex and OpenClaw — the commands are wrapped with `commandToSkill` and
+ * written alongside the guide skills.
+ *
+ * Skills live under `<projectDir>/.pi/skills/`, verified against
+ * @earendil-works/pi-coding-agent v0.80.2 (the `.pi` config dir).
+ */
+export declare function installPiOryAssets(projectDir: string): void;
+export declare function uninstallPiOryAssets(projectDir: string): void;

package/dist/cli/assets.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Materialize / clean the Ory skill catalog and command-skills for the Pi
+ * plugin. The guide skills plus the local-stack commands (rendered as
+ * user-invocable skills) land at `<projectDir>/.pi/skills/<name>/SKILL.md`.
+ *
+ * Pi has a skills system but no native slash-command system to rely on, so —
+ * like Codex and OpenClaw — the commands are wrapped with `commandToSkill` and
+ * written alongside the guide skills.
+ *
+ * Skills live under `<projectDir>/.pi/skills/`, verified against
+ * @earendil-works/pi-coding-agent v0.80.2 (the `.pi` config dir).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installPiOryAssets = installPiOryAssets;
+exports.uninstallPiOryAssets = uninstallPiOryAssets;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+const RENDER_OPTS = {
+    binName: "ory-pi",
+    packageName: "@ory/pi",
+};
+const CONFIG_DIR = ".pi";
+function piRoot(projectDir) {
+    return path.join(projectDir, CONFIG_DIR);
+}
+function skillsDir(projectDir) {
+    return path.join(piRoot(projectDir), "skills");
+}
+function installPiOryAssets(projectDir) {
+    const dir = skillsDir(projectDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const guideSkills = (0, argus_1.renderOrySkills)("pi", RENDER_OPTS);
+    const commandSkills = (0, argus_1.renderOryCommands)("pi", RENDER_OPTS).map(argus_1.commandToSkill);
+    (0, argus_1.writeSkillTree)(dir, [...guideSkills, ...commandSkills]);
+}
+function safeRmEmpty(dir) {
+    try {
+        if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+            fs.rmdirSync(dir);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+function uninstallPiOryAssets(projectDir) {
+    const dir = skillsDir(projectDir);
+    if (fs.existsSync(dir)) {
+        (0, argus_1.removeSkillDirs)(dir, [...argus_1.ORY_SKILL_NAMES, ...argus_1.ORY_COMMAND_SKILL_NAMES]);
+        safeRmEmpty(dir);
+    }
+    safeRmEmpty(piRoot(projectDir));
+}

package/dist/cli/loader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared logic for installing / removing the Ory extension loader file.
+ *
+ * Pi auto-discovers in-process extensions from `<cwd>/.pi/extensions/` (project
+ * scope) and `~/.pi/agent/extensions/` (global scope): each `*.ts`/`*.js` file
+ * placed there is loaded via jiti and its default export is invoked as the
+ * extension factory. A bare module id in `settings.json`'s `extensions` array is
+ * NOT loaded — those entries are resolved as filesystem paths. So we drop a
+ * tiny loader file that re-exports the installed `@ory/pi` package's default
+ * factory; Pi discovers the file, jiti resolves `@ory/pi` from `node_modules`,
+ * and the factory runs. No `settings.json` entry is required.
+ *
+ * Verified against @earendil-works/pi-coding-agent v0.80.2 (the extension
+ * loader's `discoverAndLoadExtensions` / `discoverExtensionsInDir`).
+ */
+export declare const EXTENSION_MODULE = "@ory/pi";
+export declare const LOADER_FILENAME = "ory.js";
+export declare const LOADER_CONTENTS = "// Ory extension loader for Pi. Re-exports @ory/pi's default factory so Pi's\n// extension auto-discovery (which scans .pi/extensions/ for *.js files) can\n// load it. Generated by 'ory-pi install' / 'ory-pi-setup' \u2014 safe to delete.\nexport { default } from \"@ory/pi\";\n";
+/** Resolve the `.pi/extensions/` dir for the requested scope. */
+export declare function getExtensionsDir(opts: {
+    global?: boolean;
+    projectDir: string;
+}): string;
+/** Full path to the loader file for the requested scope. */
+export declare function getLoaderPath(opts: {
+    global?: boolean;
+    projectDir: string;
+}): string;
+/** Write the loader file, creating `.pi/extensions/` as needed. */
+export declare function writeOryLoader(opts: {
+    global?: boolean;
+    projectDir: string;
+}): string;
+/**
+ * Remove the loader file (and the `.pi/extensions/` dir if it's left empty).
+ * Returns true if a loader file was present and removed.
+ */
+export declare function removeOryLoader(opts: {
+    global?: boolean;
+    projectDir: string;
+}): boolean;

package/dist/cli/loader.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Shared logic for installing / removing the Ory extension loader file.
+ *
+ * Pi auto-discovers in-process extensions from `<cwd>/.pi/extensions/` (project
+ * scope) and `~/.pi/agent/extensions/` (global scope): each `*.ts`/`*.js` file
+ * placed there is loaded via jiti and its default export is invoked as the
+ * extension factory. A bare module id in `settings.json`'s `extensions` array is
+ * NOT loaded — those entries are resolved as filesystem paths. So we drop a
+ * tiny loader file that re-exports the installed `@ory/pi` package's default
+ * factory; Pi discovers the file, jiti resolves `@ory/pi` from `node_modules`,
+ * and the factory runs. No `settings.json` entry is required.
+ *
+ * Verified against @earendil-works/pi-coding-agent v0.80.2 (the extension
+ * loader's `discoverAndLoadExtensions` / `discoverExtensionsInDir`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOADER_CONTENTS = exports.LOADER_FILENAME = exports.EXTENSION_MODULE = void 0;
+exports.getExtensionsDir = getExtensionsDir;
+exports.getLoaderPath = getLoaderPath;
+exports.writeOryLoader = writeOryLoader;
+exports.removeOryLoader = removeOryLoader;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+exports.EXTENSION_MODULE = "@ory/pi";
+exports.LOADER_FILENAME = "ory.js";
+exports.LOADER_CONTENTS = `// Ory extension loader for Pi. Re-exports @ory/pi's default factory so Pi's
+// extension auto-discovery (which scans .pi/extensions/ for *.js files) can
+// load it. Generated by 'ory-pi install' / 'ory-pi-setup' — safe to delete.
+export { default } from "@ory/pi";
+`;
+/** Resolve the `.pi/extensions/` dir for the requested scope. */
+function getExtensionsDir(opts) {
+    return opts.global
+        ? path.join(os.homedir(), ".pi", "agent", "extensions")
+        : path.join(opts.projectDir, ".pi", "extensions");
+}
+/** Full path to the loader file for the requested scope. */
+function getLoaderPath(opts) {
+    return path.join(getExtensionsDir(opts), exports.LOADER_FILENAME);
+}
+/** Write the loader file, creating `.pi/extensions/` as needed. */
+function writeOryLoader(opts) {
+    const dir = getExtensionsDir(opts);
+    const loaderPath = path.join(dir, exports.LOADER_FILENAME);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(loaderPath, exports.LOADER_CONTENTS);
+    return loaderPath;
+}
+/**
+ * Remove the loader file (and the `.pi/extensions/` dir if it's left empty).
+ * Returns true if a loader file was present and removed.
+ */
+function removeOryLoader(opts) {
+    const dir = getExtensionsDir(opts);
+    const loaderPath = path.join(dir, exports.LOADER_FILENAME);
+    const existed = fs.existsSync(loaderPath);
+    if (existed) {
+        fs.unlinkSync(loaderPath);
+    }
+    try {
+        if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+            fs.rmdirSync(dir);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return existed;
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Main CLI for @ory/pi.
+ *
+ * Usage:
+ *   npx ory-pi install [--project-dir <path>] [--global]   Install the Ory extension loader into .pi/extensions/
+ *   npx ory-pi uninstall                                    Remove the Ory extension loader
+ *   npx ory-pi configure                                    Set or view Ory project URL and API key
+ *   npx ory-pi status                                       Show plugin status
+ */
+export {};

package/dist/cli/main.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Main CLI for @ory/pi.
+ *
+ * Usage:
+ *   npx ory-pi install [--project-dir <path>] [--global]   Install the Ory extension loader into .pi/extensions/
+ *   npx ory-pi uninstall                                    Remove the Ory extension loader
+ *   npx ory-pi configure                                    Set or view Ory project URL and API key
+ *   npx ory-pi status                                       Show plugin status
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+const assets_js_1 = require("./assets.js");
+const loader_js_1 = require("./loader.js");
+function main() {
+    const [command, ...args] = process.argv.slice(2);
+    switch (command) {
+        case "install":
+            install(args);
+            postInstallPermissions("ory-pi", "pi").then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "uninstall":
+            uninstall(args);
+            break;
+        case "configure":
+            (0, argus_1.runConfigureCommand)("ory-pi", args);
+            break;
+        case "agent":
+            (0, argus_1.runAgentCommand)("ory-pi", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "permissions":
+            (0, argus_1.runPermissionsCommand)("ory-pi", "pi", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "status":
+            status(args).then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "local":
+            (0, argus_1.runLocalCommand)("ory-pi", args).catch((err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "watch":
+            (0, argus_1.runWatchCommand)(args);
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            help();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            help();
+            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])
+        return args[idx + 1];
+    return process.cwd();
+}
+function isGlobal(args) {
+    return args.includes("--global") || args.includes("-g");
+}
+// Pi auto-discovers extensions from `<cwd>/.pi/extensions/` (project) and
+// `~/.pi/agent/extensions/` (global): each `*.js`/`*.ts` file there is loaded
+// via jiti and its default export is the factory. We drop a loader file that
+// re-exports @ory/pi's default factory. No settings.json entry is needed.
+// Verified against @earendil-works/pi-coding-agent v0.80.2. See ./loader.ts.
+function loaderOpts(args) {
+    return { global: isGlobal(args), projectDir: parseProjectDir(args) };
+}
+function install(args) {
+    const projectDir = parseProjectDir(args);
+    const loaderPath = (0, loader_js_1.writeOryLoader)(loaderOpts(args));
+    (0, assets_js_1.installPiOryAssets)(projectDir);
+    console.log(`Ory extension loader installed at ${loaderPath}`);
+    console.log(`  Re-exports the default factory from ${loader_js_1.EXTENSION_MODULE}`);
+    console.log(`  Skills + commands installed under ${path.join(projectDir, ".pi", "skills")}`);
+    (0, argus_1.printEnvHelp)("ory-pi");
+}
+function uninstall(args) {
+    const projectDir = parseProjectDir(args);
+    const removed = (0, loader_js_1.removeOryLoader)(loaderOpts(args));
+    console.log(removed
+        ? "Ory extension loader removed."
+        : "No Ory extension loader found. Nothing to uninstall.");
+    (0, assets_js_1.uninstallPiOryAssets)(projectDir);
+}
+async function status(args) {
+    const loaderPath = (0, loader_js_1.getLoaderPath)(loaderOpts(args));
+    await (0, argus_1.runStatusCommand)("ory-pi", "pi", {
+        title: "Pi",
+        printPluginSection: () => {
+            const installed = fs.existsSync(loaderPath);
+            console.log("Extension & hooks:");
+            console.log(`  Loader file:         ${loaderPath}`);
+            console.log(`  Extension installed: ${installed ? "yes" : "NO"}`);
+            if (installed) {
+                console.log(`  Re-exports:          ${loader_js_1.EXTENSION_MODULE} (default factory)`);
+            }
+            console.log(`  Blocking support:    yes (tool_call can deny tool execution)`);
+            console.log(`  Hooks registered:    session-start (factory body), tool_call, tool_result`);
+        },
+    });
+}
+function help() {
+    console.log(`
+ory-pi — Ory plugin for Pi (the minimal coding agent)
+
+Usage:
+  npx -y -p @ory/pi ory-pi <command> [options]
+
+Commands:
+  install [--project-dir <path>] [--global]   Install the Ory extension loader into .pi/extensions/
+  uninstall [--project-dir <path>] [--global] Remove the Ory extension loader
+  configure                        Set or view Ory project URL and API key
+  agent <status|unregister>        Manage the agent's OAuth2 (DCR) identity
+  permissions <cmd>                Manage permission mode and tool permissions
+                                   (status, bootstrap, observe, enforce)
+  local <cmd>                      Manage local Ory dev environment
+                                   (up, down, status, seed, logs, env, configure, reset)
+  status [--project-dir <path>]    Show plugin configuration and status
+  watch [trace-file]               Watch live trace output
+
+After installing, the plugin hooks into these Pi lifecycle events:
+  session-start (factory body)  Verify session / resolve agent identity via Ory
+  tool_call                     Check tool permissions via Ory Permissions (can block)
+  tool_result                   Record tool completion trace
+
+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 permissions bootstrap
+  npx -y -p @ory/pi ory-pi local up
+  npx -y -p @ory/pi ory-pi status
+`);
+}
+main();

package/dist/cli/setup.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Setup CLI for the Ory Pi plugin.
+ *
+ * Pi auto-discovers in-process extensions from `<cwd>/.pi/extensions/` (project
+ * scope) and `~/.pi/agent/extensions/` (global scope): every `*.ts`/`*.js` file
+ * placed there is loaded via jiti and its default export is invoked as the
+ * extension factory. A bare module id in `settings.json`'s `extensions` array is
+ * NOT loaded — those entries are resolved as filesystem paths.
+ *
+ * So this writer drops a tiny loader file that re-exports the installed
+ * `@ory/pi` package's default factory:
+ *
+ *   // .pi/extensions/ory.js
+ *   export { default } from "@ory/pi";
+ *
+ * Pi discovers the file, jiti resolves `@ory/pi` from `node_modules`, and the
+ * factory runs. Project scope writes `<projectDir>/.pi/extensions/ory.js`;
+ * global scope (`--global`) writes `~/.pi/agent/extensions/ory.js`. No
+ * `settings.json` entry is required — discovery alone enables the extension.
+ *
+ * Pi excludes MCP by design, so there is NO MCP server block.
+ *
+ * Usage:
+ *   npx ory-pi-setup                       # Install loader into project .pi/extensions/
+ *   npx ory-pi-setup --global              # Install loader into ~/.pi/agent/extensions/
+ *   npx ory-pi-setup --project-dir /path/to/repo
+ *   npx ory-pi-setup --print               # Print the loader contents to stdout
+ *   npx ory-pi-setup --uninstall           # Remove the Ory loader
+ *
+ * Verified against @earendil-works/pi-coding-agent v0.80.2 (the extension
+ * loader's `discoverAndLoadExtensions` / `discoverExtensionsInDir`).
+ */
+export {};