@gotgenes/pi-permission-system 20.7.2 → 20.7.3

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [20.7.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.7.2...pi-permission-system-v20.7.3) (2026-07-15)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** ship consumable public type declarations ([#592](https://github.com/gotgenes/pi-packages/issues/592)) ([542e094](https://github.com/gotgenes/pi-packages/commit/542e094b9650e8f13bd9dad3864007f3ce2c0cc2))
+
+
+### Documentation
+
+* **pi-permission-system:** document the bundled public type declaration ([070875d](https://github.com/gotgenes/pi-packages/commit/070875d654efde50e8867f8fd4aeba857a26c4fb))
+
 ## [20.7.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.7.1...pi-permission-system-v20.7.2) (2026-07-14)
 
 

package/dist/public.d.ts

@@ -0,0 +1,249 @@
+import { z } from 'zod';
+
+/**
+ * Registry for custom tool access-intent extractors.
+ *
+ * Lets sibling extensions declare the filesystem path a tool will access when
+ * the tool's input shape is not the default `input.path` convention, so the
+ * cross-cutting `path` and `external_directory` gates can see it.
+ * One extractor per tool name; duplicate registration throws.
+ */
+/** Returns the filesystem path this tool will access, or `undefined` to decline. */
+type ToolAccessExtractor = (input: Record<string, unknown>) => string | undefined;
+
+/**
+ * Registry for custom tool-input preview formatters.
+ *
+ * Allows extensions to register a formatter for a specific tool name so
+ * permission prompts can show a human-readable summary instead of raw JSON.
+ * One formatter per tool name; duplicate registration throws.
+ */
+/** A custom preview formatter for one tool's input. Returns `undefined` to decline. */
+type ToolInputFormatter = (input: Record<string, unknown>) => string | undefined;
+
+declare const permissionStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"allow">, z.ZodLiteral<"deny">, z.ZodLiteral<"ask">]>;
+/** A permission decision. */
+type PermissionState = z.infer<typeof permissionStateSchema>;
+
+/**
+ * Provenance of a rule — which source contributed it.
+ *
+ * Config scopes: "global", "project", "agent", "project-agent".
+ * Synthesized:   "builtin" (universal default / evaluate() fallback),
+ *                "baseline" (conditional MCP metadata auto-allow).
+ * Runtime:       "session" (session approvals).
+ * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode).
+ */
+type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" | "baseline" | "session" | "yolo";
+
+/**
+ * Execution context of a bash command nested inside a substitution or subshell.
+ * Absent for current-shell (top-level) commands.
+ */
+type BashCommandContext = "command_substitution" | "process_substitution" | "subshell";
+interface PermissionCheckResult {
+    toolName: string;
+    state: PermissionState;
+    /** Custom denial reason from a deny-with-reason pattern, when present. */
+    reason?: string;
+    matchedPattern?: string;
+    command?: string;
+    target?: string;
+    source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
+    /** Which source contributed the winning rule. */
+    origin: RuleOrigin;
+    /**
+     * Execution context of the offending nested command, when the winning bash
+     * unit came from a substitution or subshell. Absent for current-shell
+     * (top-level) commands.
+     */
+    commandContext?: BashCommandContext;
+}
+
+/** Emitted at `session_start`, after the service is published. */
+declare const PERMISSIONS_READY_CHANNEL = "permissions:ready";
+/** Emitted when a permission request is committed to the active UI prompt path. */
+declare const PERMISSIONS_UI_PROMPT_CHANNEL = "permissions:ui_prompt";
+/** Emitted after every permission gate resolution. */
+declare const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
+/**
+ * Payload emitted on `permissions:ready`.
+ *
+ * Intentionally empty: the channel is a readiness signal. There is no
+ * `protocolVersion` — the published types plus package semver define the
+ * broadcast contract.
+ */
+type PermissionsReadyEvent = Record<string, never>;
+/**
+ * Origin of a UI prompt.
+ *
+ * Forwarding is orthogonal to origin: a forwarded subagent prompt keeps its
+ * original source and is identified by a non-null `forwarding` field, not by a
+ * dedicated source value.
+ */
+type PermissionUiPromptSource = "tool_call" | "skill_input" | "skill_read";
+/** Forwarding context, present only when a prompt was forwarded from a non-UI subagent. */
+interface ForwardedPromptContext {
+    /** Requesting subagent's display name, when known. */
+    requesterAgentName: string | null;
+    /** Requesting subagent's session id, when known. */
+    requesterSessionId: string | null;
+}
+/**
+ * Payload emitted on `permissions:ui_prompt`, immediately before the active
+ * user-facing permission UI is shown.
+ *
+ * Lean by design: `surface`/`value` are the normalized display projection a
+ * notification consumer reads; `source` is the origin; `forwarding` is non-null
+ * only for forwarded subagent prompts. There is no `protocolVersion` — the
+ * published types plus package semver define the broadcast contract, and
+ * consumers should read defensively.
+ */
+interface PermissionUiPromptEvent {
+    /** Unique ID for the permission request being prompted. */
+    requestId: string;
+    /** Prompt origin. */
+    source: PermissionUiPromptSource;
+    /** Normalized display surface (e.g. "bash", "skill"), when known. */
+    surface: string | null;
+    /** Normalized display value (command, path, skill name, etc.), when known. */
+    value: string | null;
+    /** Agent name (when known). */
+    agentName: string | null;
+    /** Message displayed to the user. */
+    message: string;
+    /** Forwarding context, or null for a direct prompt. */
+    forwarding: ForwardedPromptContext | null;
+}
+/** How a permission decision was reached. */
+type PermissionDecisionResolution = "policy_allow" | "policy_deny" | "session_approved" | "infrastructure_auto_allowed" | "user_approved" | "user_approved_for_session" | "user_denied" | "auto_approved" | "confirmation_unavailable";
+/** Payload emitted on `permissions:decision`. */
+interface PermissionDecisionEvent {
+    /** Permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
+    surface: string;
+    /** The value that was evaluated (command, tool name, skill name, path). */
+    value: string;
+    /** Final decision. */
+    result: "allow" | "deny";
+    /** How the decision was reached. */
+    resolution: PermissionDecisionResolution;
+    /** Which config scope contributed the winning rule (when available). */
+    origin: string | null;
+    /** Agent name (when known). */
+    agentName: string | null;
+    /** Matched pattern from the winning rule (when available). */
+    matchedPattern: string | null;
+}
+
+/**
+ * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ *
+ * `Symbol.for()` is process-global by spec, so it survives jiti's per-extension
+ * module isolation (`moduleCache: false`). A consumer doing
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but
+ * `getPermissionsService()` reads from the same `globalThis` slot the provider
+ * wrote to — enabling direct, synchronous, type-safe function calls.
+ *
+ * Best practice: call `getPermissionsService()` per use rather than caching the
+ * reference — this ensures resilience across `/reload` and load-order edge cases.
+ */
+
+/**
+ * Public interface exposed to other extensions via `getPermissionsService()`.
+ *
+ * `checkPermission` takes a surface + optional value + optional agent name,
+ * and delegates to `PermissionManager.checkPermission()` with current session
+ * rules internally.
+ */
+interface PermissionsService {
+    /**
+     * Query the permission policy for a surface and value.
+     *
+     * @param surface   - Permission surface: "bash", "read", "mcp", "skill",
+     *                    "external_directory", etc.
+     * @param value     - The value to evaluate: command string, tool name, skill
+     *                    name, or path. Omit or pass `undefined` for a
+     *                    surface-level query.
+     * @param agentName - Optional agent name for per-agent policy resolution.
+     * @returns Full check result including state, matched pattern, and origin.
+     */
+    checkPermission(surface: string, value?: string, agentName?: string): PermissionCheckResult;
+    /**
+     * Register a custom preview formatter for a specific tool name.
+     *
+     * The formatter is consulted first inside `ToolPreviewFormatter.formatToolInputForPrompt`;
+     * returning `undefined` falls through to the built-in switch (and ultimately
+     * the JSON default).
+     *
+     * Only one formatter may be registered per tool name — a second call for the
+     * same name throws.  The returned disposer unregisters the formatter.
+     *
+     * @param toolName  - Exact tool name to register for (e.g. `"mcp"`, `"my-server:run"`).
+     * @param formatter - Receives the raw `input` record; return a string to use
+     *                    as the prompt preview, or `undefined` to decline.
+     */
+    registerToolInputFormatter(toolName: string, formatter: ToolInputFormatter): () => void;
+    /**
+     * Register a custom access-intent extractor for a specific tool name.
+     *
+     * The extractor declares the filesystem path a tool will access so the
+     * cross-cutting `path` and `external_directory` gates can see it. Use it for
+     * tools whose path lives under a non-standard key — built-in file tools and
+     * any tool exposing `input.path` (plus MCP via `input.arguments.path`) are
+     * already covered by convention without registration.
+     *
+     * The extractor receives the raw `input` record and returns the path string,
+     * or `undefined` to decline. Only one extractor may be registered per tool
+     * name — a second call for the same name throws. The returned disposer
+     * unregisters the extractor.
+     *
+     * @param toolName  - Exact tool name to register for (e.g. `"ffgrep"`).
+     * @param extractor - Receives the raw `input` record; return the path string,
+     *                    or `undefined` to decline.
+     */
+    registerToolAccessExtractor(toolName: string, extractor: ToolAccessExtractor): () => void;
+    /**
+     * Query the tool-level permission state for pre-filtering tools before
+     * creating a child session.
+     *
+     * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
+     * Does not consider command-level rules (e.g. per-bash-command patterns) —
+     * use `checkPermission` for runtime invocation gates.
+     *
+     * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+     * @param agentName - Optional agent name for per-agent policy resolution.
+     */
+    getToolPermission(toolName: string, agentName?: string): PermissionState;
+}
+/**
+ * Store a `PermissionsService` on `globalThis` so other extensions can
+ * retrieve it via `getPermissionsService()`.
+ *
+ * Called at `session_start` by the top-level (parent) instance only — an
+ * in-process subagent child skips publishing so it cannot clobber the parent's
+ * service. Overwrites any previously published service, which keeps `/reload`
+ * working: a reloaded parent re-publishes its fresh service.
+ */
+declare function publishPermissionsService(service: PermissionsService): void;
+/**
+ * Retrieve the published `PermissionsService`, or `undefined` if the
+ * permission-system extension has not loaded (or has been unloaded).
+ */
+declare function getPermissionsService(): PermissionsService | undefined;
+/**
+ * Remove `service` from `globalThis`, but only when the current slot still
+ * holds it (identity compare-and-delete).
+ *
+ * Called during `session_shutdown` to avoid stale references after the
+ * extension is torn down. Scoping the delete to the publishing instance keeps
+ * two cases correct:
+ *
+ * - An in-process subagent child never published the parent's service, so its
+ *   shutdown is a no-op and the parent's slot survives.
+ * - A superseded `/reload` generation no longer owns the slot, so its late
+ *   shutdown cannot wipe the new generation's freshly published service.
+ */
+declare function unpublishPermissionsService(service: PermissionsService): void;
+
+export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
+export type { ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, ToolInputFormatter };

package/docs/cross-extension-api.md

@@ -39,6 +39,9 @@ Consumers call `getPermissionsService()` to retrieve it — even though their `i
 An in-process subagent child does not publish its own service; inside a child, `getPermissionsService()` resolves the parent's service.
 A consumer reacting to the `permissions:ready` broadcast (also emitted at `session_start`, after the publish) can resolve the service immediately.
 
+All types below are directly importable and type-check with `tsc` out of the box.
+`@gotgenes/pi-permission-system`'s published `exports` resolve `import type { … }` to a self-contained, bundled declaration file with no internal module references, so a downstream `tsconfig.json` needs no special path configuration.
+
 ### API
 
 The `PermissionsService` interface:

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "20.7.2",
+  "version": "20.7.3",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
-    ".": "./src/service.ts"
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./src/service.ts"
+    }
   },
   "imports": {
     "#src/*": "./src/*",
@@ -12,6 +15,7 @@
   },
   "files": [
     "src",
+    "dist",
     "config/config.example.json",
     "schemas/permissions.schema.json",
     "docs/*.md",
@@ -67,6 +71,8 @@
     "@earendil-works/pi-coding-agent": "0.79.1",
     "@earendil-works/pi-tui": "0.79.1",
     "@types/node": "^22.15.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-dts": "^6.4.1",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
@@ -78,9 +84,11 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs",
     "gen:schema": "node --experimental-strip-types scripts/generate-permissions-schema.ts && biome format --write schemas/permissions.schema.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "verify:public-types": "bash scripts/verify-public-types.sh",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"
   }