@ory/pi 1.3.0 → 1.4.0

package/README.md

@@ -1,4 +1,4 @@
-# Ory Agent Plugin: Pi
+# Ory Agent Plugin and SDK Integration: Pi
 
 Security and developer experience for [Pi](https://pi.dev), powered by [Ory](https://ory.com).
 
@@ -16,21 +16,15 @@ One command installs two independent halves:
 - [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
 - macOS or Linux (Windows works via WSL2)
 
-Pi loads the plugin from your project's `node_modules`, so add it to your project first:
-
-```bash
-npm install @ory/pi
-```
-
 ## Get started
 
-Then run one command. It installs the plugin.:
+Run one command:
 
 ```bash
 npx -y -p @ory/pi ory-pi install
 ```
 
-The installer drops a tiny loader at `<project>/.pi/extensions/ory.js` so Pi discovers the plugin and adds the Ory skills under `<project>/.pi/skills`. Add `--global` to install the loader for all projects (at `~/.pi/agent/extensions/ory.js`) instead of just this one.
+The installer resolves the runtime once and drops a tiny loader at `<project>/.pi/extensions/ory.js` so Pi discovers the plugin, and adds the Ory skills under `<project>/.pi/skills`. Add `--global` to install the loader for all projects (at `~/.pi/agent/extensions/ory.js`) instead of just this one. No project dependency is required for CLI installation.
 
 Confirm everything landed with:
 
@@ -49,7 +43,7 @@ Point Pi's own package installer at the npm package:
 pi install npm:@ory/pi
 ```
 
-This registers the extension through Pi's package manifest. Run `npx -y -p @ory/pi ory-pi install` in a terminal afterwards to materialize the skills (and, later, `configure` if you want to connect).
+This registers the security extension through Pi's package manifest. Use either this registration or the Ory installer above, not both: duplicate extensions produce duplicate checks and activity. The Ory installer is the supported route for the complete skill catalog and runtime health checks.
 
 </details>
 
@@ -93,7 +87,59 @@ Once you connect to Ory Agent Security, two more things happen automatically:
 
 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 has no MCP support and no sub-agents by design, so there's nothing extra to register — just the plugin itself.
+The extension gates tools exposed through Pi's `tool_call` event and records `tool_result`. Extension-provided tools use their Pi tool names; the installer does not configure an MCP server, and this adapter does not translate MCP-specific grants or child-agent delegation. Calls that another extension executes outside Pi's tool lifecycle are outside this boundary.
+
+Session authentication runs on `session_start`, using `ctx.sessionManager.getSessionId()` for identity and activity. Loading extension resources alone does not start authentication. SDK hosts that omit lifecycle binding still start authentication lazily before their first tool call.
+
+## Embed Pi with the SDK
+
+The same `createOryPlugin` factory works in `DefaultResourceLoader.extensionFactories`.
+Install `@ory/pi`, `@earendil-works/pi-coding-agent@0.87.1`, and `tsx` in your application.
+Configure the routing URLs and runtime credential from your Agent Security deployment;
+the model provider credential remains separate.
+
+```typescript
+import {
+  createAgentSession, DefaultResourceLoader, getAgentDir,
+  ModelRuntime, SessionManager, SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { createOryPlugin, OryAgentClient } from "@ory/pi";
+
+const ory = OryAgentClient.fromEnv("pi");
+const settingsManager = SettingsManager.inMemory();
+const resourceLoader = new DefaultResourceLoader({
+  cwd: process.cwd(), agentDir: getAgentDir(), settingsManager,
+  noExtensions: true, // Load only the inline extension, avoiding duplicate discovery.
+  noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true,
+  extensionFactories: [createOryPlugin(ory)],
+});
+await resourceLoader.reload();
+const modelRuntime = await ModelRuntime.create();
+const model = modelRuntime.getModel("openai", "gpt-4o-mini");
+if (!model) throw new Error("The OpenAI gpt-4o-mini model is unavailable");
+const { session } = await createAgentSession({
+  resourceLoader, settingsManager, modelRuntime, model,
+  sessionManager: SessionManager.inMemory(),
+});
+try {
+  await session.bindExtensions({});
+  await session.prompt("Use the read tool to summarize README.md.");
+  console.log(session.getLastAssistantText());
+} finally {
+  session.dispose();
+}
+```
+
+Run this as an ESM TypeScript entry (for example `npx tsx agent.mts`) with
+`OPENAI_API_KEY` set. Built-in and custom tools share the same gate. In enforce mode,
+an explicit block returns `{ block: true, reason }` before execution, and Pi reports
+the denial to the model. Give each independent SDK session its own client and
+extension factory. Resume persistent sessions using Pi's `SessionManager` so the
+native session identity is retained.
+
+The Agent Security **Build → Pi SDK** quickstart and **Guides → Build → Pi SDK**
+provide a complete custom-tool example. Choose **Pi SDK** when creating a hosted
+Agent deployment; managed CLI installations continue to use the **Pi** plugin.
 
 ### See what's happening
 
@@ -163,12 +209,12 @@ All prefixed with `npx -y -p @ory/pi`.
 - **Local Ory won't start** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
 - **Browser sign-in loops** (after connecting) — confirm the reserved login client has all four documented loopback redirect URIs; `agent unregister` only clears legacy agent OAuth state.
 - **Running an older CLI than expected** — `npx -p @ory/pi` (no version pin) reuses a previously-downloaded copy instead of re-resolving to the latest. The install banner prints the running version; confirm it with `npx -y -p @ory/pi ory-pi version`. To force the current release, clear the cache and reinstall: `rm -rf ~/.npm/_npx` then `npx -y -p @ory/pi ory-pi install`. Pinning an exact version (`@ory/pi@<version>`) also bypasses the cached copy.
-- **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.
+- **Pi can't find the plugin** — check the loader at `.pi/extensions/ory.js` (or `~/.pi/agent/extensions/ory.js` for global installs) and run `ory-pi status` to verify its resolved runtime; re-run the installer if needed.
 
 ## Learn more
 
 - [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)
+- [Pi repository](https://github.com/earendil-works/pi) · [Pi SDK documentation](https://pi.dev/docs/latest/sdk)
 
 ## License
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { createOryPlugin } from "./plugin.js";
 export { createOryPlugin };
+export { OryAgentClient } from "@ory/argus";
 export type { CreateOryPluginDeps } from "./plugin.js";
 export type { PiExtension, PiExtensionApi, PiEvent, PiEventHandlers, PiToolCallContext, PiToolResultContext, PiToolCallResult, PiHookRuntimeContext, } from "./types.js";
 declare const _default: import("./types.js").PiExtension;

package/dist/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOryPlugin = void 0;
+exports.OryAgentClient = exports.createOryPlugin = void 0;
 const plugin_js_1 = require("./plugin.js");
 Object.defineProperty(exports, "createOryPlugin", { enumerable: true, get: function () { return plugin_js_1.createOryPlugin; } });
+var argus_1 = require("@ory/argus");
+Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return argus_1.OryAgentClient; } });
 // Pi loads in-process extensions via jiti and expects a default-exported
 // factory function `(pi) => void | Promise<void>`. CJS output (module:
 // nodenext → CJS) surfaces `module.exports` as the ESM `default`, so a single

package/dist/plugin.d.ts

@@ -3,7 +3,7 @@ import type { PiExtension } from "./types.js";
 export interface CreateOryPluginDeps {
     userLogin?: typeof ensureUserAuthenticated;
     agentGate?: typeof ensureAgentIdentity;
-    /** Pin the per-process id for deterministic tests. Production mints one. */
+    /** Fallback for hosts that do not supply a Pi session manager. */
     sessionId?: string;
 }
 export declare function createOryPlugin(clientOrConfig?: OryAgentClient | {

package/dist/plugin.js

@@ -11,19 +11,37 @@ function createOryPlugin(clientOrConfig, deps = {}) {
             : clientOrConfig
                 ? new argus_1.OryAgentClient({ ...clientOrConfig, harness: HARNESS })
                 : argus_1.OryAgentClient.fromEnv(HARNESS);
-        // Pi events have no session id, so one process UUID identifies the run.
-        const sessionId = deps.sessionId ?? (0, node_crypto_1.randomUUID)();
-        await (0, argus_1.withHookContext)(client, { sessionId }, async () => {
-            client.logger.info("lifecycle.session_start", { harness: HARNESS });
-            await (0, argus_1.sessionStart)(client, {
-                harness: HARNESS,
-                binName: "ory-pi",
-                userLogin: deps.userLogin,
-                agentGate: deps.agentGate,
+        const fallbackSessionId = deps.sessionId ?? (0, node_crypto_1.randomUUID)();
+        const sessionId = (ctx) => ctx?.sessionManager.getSessionId() ?? fallbackSessionId;
+        let activeSessionId;
+        let start;
+        const ensureStarted = async (id) => {
+            if (id !== activeSessionId) {
+                activeSessionId = id;
+                start = (0, argus_1.createSessionStarter)(client, {
+                    harness: HARNESS,
+                    binName: "ory-pi",
+                    userLogin: deps.userLogin,
+                    agentGate: deps.agentGate,
+                });
+            }
+            await start();
+        };
+        // Loading resources is not a session start. Pi supplies the real session
+        // through the hook context, including after resume/new/fork operations.
+        pi.on("session_start", (_event, ctx) => {
+            const id = sessionId(ctx);
+            return (0, argus_1.withHookContext)(client, { sessionId: id }, () => ensureStarted(id));
+        });
+        pi.on("tool_call", (event, ctx) => {
+            const id = sessionId(ctx);
+            return (0, argus_1.withHookContext)(client, { sessionId: id }, async () => {
+                // SDK hosts may prompt without binding extension UI/lifecycle handlers.
+                await ensureStarted(id);
+                return createToolCallHandler(client, id)(event);
             });
         });
-        pi.on("tool_call", createToolCallHandler(client, sessionId));
-        pi.on("tool_result", createToolResultHandler(client, sessionId));
+        pi.on("tool_result", (event, ctx) => createToolResultHandler(client, sessionId(ctx))(event));
     };
 }
 function createToolCallHandler(client, sessionId) {

package/dist/types.d.ts

@@ -1,114 +1,42 @@
-/**
- * Pi (the minimal coding agent — pi.dev / github.com/badlogic/pi-mono) plugin
- * types.
- *
- * Pi loads in-process TypeScript extensions via jiti. The module's DEFAULT
- * EXPORT is a factory function `(pi: ExtensionAPI) => void | Promise<void>`.
- * Pi awaits async factories before startup continues, so the factory body is
- * the de-facto session-start hook: we run the auth gates inline there.
- *
- * Tool hooks are registered with `pi.on(event, handler)`. The pre-execution
- * `tool_call` hook BLOCKS a tool by returning `{ block: true, reason }`;
- * returning nothing/undefined allows. A best-effort `tool_result` hook fires
- * after a tool completes and is used for activity auditing.
- *
- * Pi deliberately excludes MCP and sub-agents, so there is no MCP tool
- * parsing and no sub-agent identity path.
- *
- * Contract verified against @earendil-works/pi-coding-agent v0.80.2 (dist
- * core/extensions/types.d.ts). The `tool_call` event "Fired before a tool
- * executes. Can block." and a handler returns
- * `ToolCallEventResult { block?: boolean; reason?: string }`; the
- * `tool_result` event "Fired after a tool executes." carries `isError` and
- * `content`. The factory default export receives an `ExtensionAPI`.
- */
-/**
- * Context delivered to a `tool_call` handler (pre-execution).
- *
- * Verified shape: `{ type: "tool_call", toolCallId, toolName, input }`.
- * `input` is mutable in place to patch tool arguments; we only read it. Pi
- * does not put a session id on this event, so the plugin derives the
- * permission subject from a stable per-process fallback.
+/** Minimal structural Pi extension contract. No runtime SDK dependency.
+ * Verified against @earendil-works/pi-coding-agent 0.87.1.
+ * https://pi.dev/docs/latest/extensions
  */
 export interface PiToolCallContext {
-    /** Discriminant: always "tool_call". */
     type?: "tool_call";
-    /** Correlates the call with its later `tool_result`. */
     toolCallId?: string;
-    /** Tool being invoked. */
     toolName?: string;
-    /** Tool parameters (mutable in place per Pi; the gate only reads them). */
     input?: Record<string, unknown>;
-    [key: string]: unknown;
 }
-/**
- * Context delivered to a `tool_result` handler (post-execution).
- *
- * Verified shape: `{ type: "tool_result", toolCallId, toolName, input,
- * content, isError, details }`. Note Pi reports failure via the `isError`
- * boolean and the result payload via `content` (not `error`/`result`).
- */
 export interface PiToolResultContext {
-    /** Discriminant: always "tool_result". */
     type?: "tool_result";
-    /** Correlates with the originating `tool_call`. */
     toolCallId?: string;
     toolName?: string;
     input?: Record<string, unknown>;
-    /** Tool output blocks (text / images). */
     content?: unknown;
-    /** True when the tool returned an error result. */
     isError?: boolean;
-    /** Tool-specific structured details, when present. */
     details?: unknown;
-    [key: string]: unknown;
 }
-/**
- * The ExtensionContext Pi passes as the second argument to a hook (`ctx`).
- * Modeled minimally; the plugin does not depend on it beyond optional UI.
- */
+/** Pi passes this as the second argument, not as fields on the event. */
 export interface PiHookRuntimeContext {
-    ui?: {
-        confirm?: (message: string) => boolean | Promise<boolean>;
-        [key: string]: unknown;
+    sessionManager: {
+        getSessionId(): string;
     };
-    [key: string]: unknown;
 }
-/**
- * The result a `tool_call` handler returns to block a tool (Pi's
- * `ToolCallEventResult`). Returning nothing/undefined allows the tool
- * through. Verified: `{ block?: boolean; reason?: string }`.
- */
 export interface PiToolCallResult {
     block: true;
     reason?: string;
 }
-/**
- * Map of Pi extension event name → handler signature. Handlers may be async.
- * Verified against Pi's `ExtensionAPI.on(...)` overloads.
- */
 export interface PiEventHandlers {
+    session_start: (event: {
+        type: "session_start";
+    }, ctx?: PiHookRuntimeContext) => void | Promise<void>;
     tool_call: (event: PiToolCallContext, ctx?: PiHookRuntimeContext) => void | PiToolCallResult | Promise<void | PiToolCallResult>;
     tool_result: (event: PiToolResultContext, ctx?: PiHookRuntimeContext) => void | Promise<void>;
 }
 export type PiEvent = keyof PiEventHandlers;
-/**
- * The ExtensionAPI object Pi passes to the default-exported factory.
- * Verified against Pi's exported `ExtensionAPI` interface (a superset — we
- * model only the members this plugin uses).
- */
 export interface PiExtensionApi {
-    /** Subscribe to a lifecycle event. */
     on<E extends PiEvent>(event: E, handler: PiEventHandlers[E]): void;
-    /** Register a custom tool. Unused by this plugin; modeled for completeness. */
-    registerTool?: (name: string, def: unknown) => void;
-    /** Register a custom command. Unused by this plugin; modeled for completeness. */
-    registerCommand?: (name: string, def: unknown) => void;
-    [key: string]: unknown;
 }
-/**
- * The default-exported extension factory Pi invokes at load time. Pi awaits
- * the returned promise before startup continues, so it is safe to run the
- * session-start auth gates in the body.
- */
+/** Used both by Pi's CLI loader and DefaultResourceLoader.extensionFactories. */
 export type PiExtension = (pi: PiExtensionApi) => void | Promise<void>;

package/dist/types.js

@@ -1,26 +1,2 @@
 "use strict";
-/**
- * Pi (the minimal coding agent — pi.dev / github.com/badlogic/pi-mono) plugin
- * types.
- *
- * Pi loads in-process TypeScript extensions via jiti. The module's DEFAULT
- * EXPORT is a factory function `(pi: ExtensionAPI) => void | Promise<void>`.
- * Pi awaits async factories before startup continues, so the factory body is
- * the de-facto session-start hook: we run the auth gates inline there.
- *
- * Tool hooks are registered with `pi.on(event, handler)`. The pre-execution
- * `tool_call` hook BLOCKS a tool by returning `{ block: true, reason }`;
- * returning nothing/undefined allows. A best-effort `tool_result` hook fires
- * after a tool completes and is used for activity auditing.
- *
- * Pi deliberately excludes MCP and sub-agents, so there is no MCP tool
- * parsing and no sub-agent identity path.
- *
- * Contract verified against @earendil-works/pi-coding-agent v0.80.2 (dist
- * core/extensions/types.d.ts). The `tool_call` event "Fired before a tool
- * executes. Can block." and a handler returns
- * `ToolCallEventResult { block?: boolean; reason?: string }`; the
- * `tool_result` event "Fired after a tool executes." carries `isError` and
- * `content`. The factory default export receives an `ExtensionAPI`.
- */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/pi",
-  "version": "1.3.0",
+  "version": "1.4.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",
@@ -75,7 +75,7 @@
   ],
   "dependencies": {
     "reova": "^0.7.0",
-    "@ory/argus": "1.3.0"
+    "@ory/argus": "1.4.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2"