@ory/pi 0.10.0

package/dist/cli/setup.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * 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`).
+ */
+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 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() {
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        (0, argus_1.printSetupHelp)("ory-pi-setup", "Pi");
+        process.exit(0);
+    }
+    const args = (0, argus_1.parseSetupArgs)({ supportsGlobal: true });
+    if (args.print) {
+        console.log(loader_js_1.LOADER_CONTENTS);
+        return;
+    }
+    if (args.uninstall) {
+        const removed = (0, loader_js_1.removeOryLoader)(args);
+        console.log(removed
+            ? "Removed Ory extension loader."
+            : "No Ory extension loader found. Nothing to uninstall.");
+        (0, assets_js_1.uninstallPiOryAssets)(args.projectDir);
+        console.log(`Removed Ory skills from ${path.join(args.projectDir, ".pi", "skills")}`);
+        return;
+    }
+    const loaderPath = (0, loader_js_1.writeOryLoader)(args);
+    (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");
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { createOryPlugin } from "./plugin.js";
+export { createOryPlugin };
+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;
+export default _default;

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOryPlugin = void 0;
+const plugin_js_1 = require("./plugin.js");
+Object.defineProperty(exports, "createOryPlugin", { enumerable: true, get: function () { return plugin_js_1.createOryPlugin; } });
+// 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
+// default export is what Pi's loader receives. Instantiate the plugin from env.
+// eslint-disable-next-line import/no-default-export
+exports.default = (0, plugin_js_1.createOryPlugin)();

package/dist/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pi in-process extension (auth + blocking permission gate + tracing).
+ *
+ * Pi loads a default-exported factory `(pi) => void | Promise<void>` from a
+ * TypeScript extension module (via jiti) and awaits it before startup
+ * continues. We treat the factory body as the session-start hook: it runs the
+ * user gate (advisory — there is no block channel for the session itself), the
+ * agent gate, and writes the user→agent delegation tuple.
+ *
+ * The blocking permission decision lives in the `tool_call` hook, which CAN
+ * block by returning `{ block: true, reason }` (like OpenClaw's
+ * `before_tool_call`). The `tool_result` hook records the `tool.complete`
+ * audit span after a tool runs.
+ *
+ * Pi excludes MCP and sub-agents by design, 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 and the extension loader): the `tool_call`
+ * handler returns `ToolCallEventResult { block?: boolean; reason? }`,
+ * `tool_result` carries `isError`/`content`, and Pi awaits the async factory
+ * default export.
+ */
+import { OryAgentClient, ensureUserAuthenticated, ensureAgentIdentity } from "@ory/argus";
+import type { PiExtension } from "./types.js";
+export interface CreateOryPluginDeps {
+    /** Test injection point for the user login flow. */
+    userLogin?: typeof ensureUserAuthenticated;
+    /** Test injection point for the agent identity gate. */
+    agentGate?: typeof ensureAgentIdentity;
+}
+/**
+ * Create the Ory extension factory for Pi.
+ *
+ * Returns a function matching Pi's `PiExtension` contract: it receives the
+ * ExtensionAPI, runs the session-start auth gates in the body, and registers
+ * the `tool_call` (blocking) and `tool_result` (tracing) hooks.
+ */
+export declare function createOryPlugin(clientOrConfig?: OryAgentClient | {
+    projectUrl: string;
+    apiKey?: string;
+}, deps?: CreateOryPluginDeps): PiExtension;

package/dist/plugin.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * Pi in-process extension (auth + blocking permission gate + tracing).
+ *
+ * Pi loads a default-exported factory `(pi) => void | Promise<void>` from a
+ * TypeScript extension module (via jiti) and awaits it before startup
+ * continues. We treat the factory body as the session-start hook: it runs the
+ * user gate (advisory — there is no block channel for the session itself), the
+ * agent gate, and writes the user→agent delegation tuple.
+ *
+ * The blocking permission decision lives in the `tool_call` hook, which CAN
+ * block by returning `{ block: true, reason }` (like OpenClaw's
+ * `before_tool_call`). The `tool_result` hook records the `tool.complete`
+ * audit span after a tool runs.
+ *
+ * Pi excludes MCP and sub-agents by design, 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 and the extension loader): the `tool_call`
+ * handler returns `ToolCallEventResult { block?: boolean; reason? }`,
+ * `tool_result` carries `isError`/`content`, and Pi awaits the async factory
+ * default export.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOryPlugin = createOryPlugin;
+const argus_1 = require("@ory/argus");
+/**
+ * Create the Ory extension factory for Pi.
+ *
+ * Returns a function matching Pi's `PiExtension` contract: it receives the
+ * ExtensionAPI, runs the session-start auth gates in the body, and registers
+ * the `tool_call` (blocking) and `tool_result` (tracing) hooks.
+ */
+function createOryPlugin(clientOrConfig, deps = {}) {
+    return async (pi) => {
+        const client = clientOrConfig instanceof argus_1.OryAgentClient
+            ? clientOrConfig
+            : clientOrConfig
+                ? new argus_1.OryAgentClient({ ...clientOrConfig, harness: "pi" })
+                : argus_1.OryAgentClient.fromEnv("pi");
+        // The factory body IS the session-start hook: Pi awaits async extension
+        // factories before startup continues (verified against
+        // @earendil-works/pi-coding-agent v0.80.2). Pi also exposes a dedicated
+        // `session_start` event, but the factory body is sufficient and runs
+        // exactly once per process.
+        await runSessionStart(client, deps);
+        pi.on("tool_call", createToolCallHandler(client));
+        pi.on("tool_result", createToolResultHandler(client));
+    };
+}
+// ─── session start (factory body) ──────────────────────────────────
+async function runSessionStart(client, deps) {
+    client.logger.info("lifecycle.session_start", { harness: "pi" });
+    client.tracer.setContext({ traceId: (0, argus_1.deriveTraceId)("pi"), sessionId: "pi" });
+    client.tracer.record("session.start", "ok", { attributes: {} });
+    // Run the user login. Pi's factory body has no return-value channel to
+    // block the session, so allowBlock is false — the flow emits the user.auth
+    // audit span, refreshes tokens, and may prompt when interactive, but never
+    // prevents the session from starting. When ORY_USER_LOGIN is unset it is a
+    // no-op (mode === "disabled") and we fall through to legacy verification.
+    const userGate = deps.userLogin ?? argus_1.ensureUserAuthenticated;
+    const decision = await userGate(client, {
+        binName: "ory-pi",
+        harness: "pi",
+        allowBlock: false,
+    });
+    // Resolve the agent identity (machine credentials). Never blocks; attaches
+    // the agent's bearer token to outgoing Ory API calls.
+    const agentGate = deps.agentGate ?? argus_1.ensureAgentIdentity;
+    await agentGate(client, { projectUrl: (0, argus_1.resolveConfig)().projectUrl, harness: "pi" });
+    // Once both principals are populated, write the user→agent delegation tuple.
+    // Idempotent + fail-open: audit-trail data only.
+    await recordUserDelegatesAgent(client);
+    if (decision.mode !== "disabled") {
+        return;
+    }
+    const resolved = (0, argus_1.resolveConfig)();
+    if (resolved.auditOnly) {
+        client.logger.info("config.audit_only", {
+            message: "Audit-only mode enabled. Auth and permission checks are disabled.",
+        });
+        return;
+    }
+    if (!resolved.projectUrl) {
+        client.logger.warn("config.not_configured", {
+            message: "Ory plugin is not configured. Auth and permission checks are disabled. " +
+                "Run 'npx ory-pi configure' to connect to an Ory project.",
+        });
+        return;
+    }
+    const sessionToken = process.env.ORY_SESSION_TOKEN;
+    const oauth2Token = process.env.ORY_OAUTH2_TOKEN;
+    if (sessionToken) {
+        await verifySessionToken(client, sessionToken);
+        return;
+    }
+    if (oauth2Token) {
+        await verifyOAuth2Token(client, oauth2Token);
+        return;
+    }
+    client.logger.warn("session.no_credentials", {
+        message: "Neither ORY_SESSION_TOKEN nor ORY_OAUTH2_TOKEN is set. " +
+            "Skipping authentication.",
+    });
+}
+async function verifySessionToken(client, token) {
+    try {
+        const session = await client.verifySession(token);
+        if (!session.active) {
+            client.logger.warn("session.inactive", {
+                message: "Ory session is not active. Re-authenticate to enable auth checks.",
+            });
+        }
+    }
+    catch (err) {
+        client.logger.warn("session.verify_failed", {
+            code: isOryError(err) ? err.code : "unknown",
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function verifyOAuth2Token(client, token) {
+    try {
+        const tokenInfo = await client.introspectToken(token);
+        if (!tokenInfo.active) {
+            client.logger.warn("oauth2.token_inactive", {
+                message: "Ory OAuth2 token is not active. Obtain a new token to enable auth checks.",
+            });
+            return;
+        }
+        client.logger.info("oauth2.session_authenticated", {
+            clientId: tokenInfo.clientId,
+            subject: tokenInfo.subject,
+        });
+    }
+    catch (err) {
+        client.logger.warn("oauth2.introspect_failed", {
+            code: isOryError(err) ? err.code : "unknown",
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+// ─── tool_call (pre-execution, blocking) ───────────────────────────
+function createToolCallHandler(client) {
+    return async (event) => {
+        const toolName = event.toolName ?? "unknown";
+        // Pi does not put a session id on the tool_call event; the per-process
+        // trace context set at session start ("pi") carries correlation. We tag
+        // the span with the toolCallId so a tool_call lines up with its later
+        // tool_result.
+        client.logger.info("lifecycle.tool_call", { toolName, toolCallId: event.toolCallId });
+        client.tracer.setContext({ traceId: (0, argus_1.deriveTraceId)("pi"), sessionId: "pi" });
+        const inputSummary = (0, argus_1.summarizeToolInput)(toolName, event.input);
+        // In audit-only mode, log the invocation but skip permission checks.
+        if ((0, argus_1.resolveConfig)().auditOnly) {
+            client.tracer.record("tool.invoke", "ok", {
+                attributes: { toolName, ...inputSummary },
+            });
+            return;
+        }
+        // If Ory is not configured, pass through.
+        if (!(0, argus_1.resolveConfig)().projectUrl) {
+            client.tracer.record("tool.invoke", "skipped", {
+                attributes: { toolName, reason: "not_configured", ...inputSummary },
+            });
+            return;
+        }
+        const subject = (0, argus_1.resolveUserSubject)(client, "agent:pi");
+        const subjectId = (0, argus_1.subjectLabel)(subject);
+        const namespace = resolveNamespace();
+        try {
+            const outcome = await (0, argus_1.gateToolCall)(client, {
+                harness: "pi",
+                toolName,
+                check: { namespace, object: toolName, relation: "use", ...subject },
+                spanAttributes: { toolName },
+            });
+            // Interactive tools (operator-extensible via ORY_INTERACTIVE_TOOLS):
+            // the user.interaction span is already recorded; pass through.
+            if (outcome.kind === "interactive") {
+                return;
+            }
+            const decision = outcome;
+            if (decision.kind === "fail_open") {
+                handlePermissionError(decision.error, toolName, client);
+                return;
+            }
+            const attrs = { toolName, ...inputSummary };
+            const decisionAttrs = decision.spanAttributes;
+            if (decision.kind === "allow") {
+                client.tracer.record("tool.invoke", "ok", {
+                    attributes: { ...attrs, ...decisionAttrs, allowed: true },
+                });
+                return;
+            }
+            if (decision.kind === "observe") {
+                client.tracer.record("tool.block", "denied", {
+                    attributes: { ...attrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
+                });
+                client.tracer.record("tool.invoke", "ok", {
+                    attributes: { ...attrs, ...decisionAttrs, allowed: false, observed: true },
+                });
+                return;
+            }
+            // decision.kind === "deny" — enforce: block the tool call.
+            client.tracer.record("tool.block", "denied", {
+                attributes: { ...attrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(true) },
+            });
+            const reason = (0, argus_1.formatDenialMessage)({
+                tool: toolName,
+                subjectId,
+                namespace,
+            });
+            client.logger.warn("tool.denied", {
+                toolName,
+                subjectId,
+                message: reason,
+            });
+            return { block: true, reason };
+        }
+        catch (err) {
+            handlePermissionError(err, toolName, client);
+            // Fail open — allow the tool call.
+        }
+    };
+}
+// ─── tool_result (post-execution, tracing) ─────────────────────────
+function createToolResultHandler(client) {
+    return async (event) => {
+        const toolName = event.toolName ?? "unknown";
+        client.tracer.setContext({ traceId: (0, argus_1.deriveTraceId)("pi"), sessionId: "pi" });
+        // Pi reports failure via the `isError` boolean and the result payload via
+        // `content` (verified shape), not `error`/`result`.
+        const isError = event.isError === true;
+        client.logger.info("lifecycle.tool_result", {
+            toolName,
+            toolCallId: event.toolCallId,
+            isError,
+        });
+        client.tracer.record("tool.complete", isError ? "error" : "ok", {
+            attributes: {
+                toolName,
+                ...(0, argus_1.summarizeToolInput)(toolName, event.input),
+                ...(0, argus_1.summarizeToolOutput)(toolName, event.content),
+                ...(isError ? { error: true } : {}),
+            },
+        });
+    };
+}
+// ─── Helpers ───────────────────────────────────────────────────────
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+function isOryError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        "message" in err);
+}
+function handlePermissionError(err, toolName, client) {
+    if (isOryError(err)) {
+        if (err.code === "network_error" || err.code === "rate_limited") {
+            client.logger.warn("permission.fallback", {
+                toolName,
+                code: err.code,
+                message: "Failing open",
+            });
+            return;
+        }
+        client.logger.error("permission.check.error", {
+            toolName,
+            code: err.code,
+            message: err.message,
+        });
+    }
+    else {
+        client.logger.error("permission.check.error", {
+            toolName,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    // Fail-open is log-and-allow: no tool.invoke span, matching the core
+    // gate() vocabulary. The errored permission.check span carries the audit
+    // trail for the failed check itself.
+}
+/**
+ * Write the user→agent delegation tuple. Idempotent and fail-open: requires
+ * both principal subjects to be populated; any error (including an
+ * unconfigured projectUrl, which manifests as a network_error) is logged and
+ * swallowed. Purely audit-trail data — does not affect enforcement.
+ */
+async function recordUserDelegatesAgent(client) {
+    const user = client.userPrincipal.subject;
+    const agent = client.agentPrincipal.subject;
+    if (!user || !agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "missing principal",
+            hasUser: !!user,
+            hasAgent: !!agent,
+        });
+        return;
+    }
+    try {
+        await client.createRelationship({
+            namespace: resolveNamespace(),
+            object: `agent:${agent}`,
+            relation: "delegate",
+            subjectId: `user:${user}`,
+        }, { spanAttributes: { delegation: "user-to-agent" } });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("delegation.user_to_agent.failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 audit tracing.
+ *
+ * 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.
+ */
+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.
+ */
+export interface PiHookRuntimeContext {
+    ui?: {
+        confirm?: (message: string) => boolean | Promise<boolean>;
+        [key: string]: unknown;
+    };
+    [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 {
+    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.
+ */
+export type PiExtension = (pi: PiExtensionApi) => void | Promise<void>;

package/dist/types.js

@@ -0,0 +1,26 @@
+"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 audit tracing.
+ *
+ * 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 });