@gotgenes/pi-permission-system 26.3.1 → 27.0.0

package/src/index.ts

@@ -2,7 +2,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
 import { warmBashParser } from "./access-intent/bash/parser";
 import { buildResolvedIntentFromMatchValues } from "./access-intent/input-normalizer";
-import { AuthorizerRegistry } from "./authority/authorizer-registry";
+import {
+  AuthorizerRegistry,
+  ObservedAuthorizerRegistrar,
+} from "./authority/authorizer-registry";
 import { AuthorizerSelection } from "./authority/authorizer-selection";
 import {
   ForwardedRequestServer,
@@ -35,6 +38,7 @@ import {
   AgentPrepHandler,
   PermissionGateHandler,
   SessionLifecycleHandler,
+  SessionTurnPrep,
 } from "./handlers";
 import { GateRunner } from "./handlers/gates/runner";
 import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeline";
@@ -46,6 +50,7 @@ import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
 import { resolveRenderBudget } from "./presentation/dialog-renderer";
+import type { PermissionsService } from "./service";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
@@ -233,12 +238,24 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       ),
   });
 
-  const permissionsService = new LocalPermissionsService(
+  // Explicitly annotated to break a type-inference cycle: the selection's
+  // `getPermissionQuery` thunk closes over this service, and the service's
+  // registrar closes back over the selection. Both are resolved at call time
+  // at runtime; `tsc` needs one of the two typed by hand to unwind them.
+  const permissionsService: PermissionsService = new LocalPermissionsService(
     resolver,
     session,
     formatterRegistry,
     accessExtractorRegistry,
-    authorizerRegistry,
+    // Sibling extensions register through the observing decorator, so a link
+    // offered to a node whose chain never runs is accepted and recorded rather
+    // than vanishing (ADR 0012 decision 4). Chain resolution keeps reading the
+    // undecorated registry above.
+    new ObservedAuthorizerRegistrar(
+      authorizerRegistry,
+      authorizerSelection,
+      logger,
+    ),
   );
 
   // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
@@ -249,13 +266,16 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   );
 
   // PermissionServiceLifecycle owns the process-global service publication:
-  // activate() publishes (skipped for registered subagent children — see #302)
-  // and emits ready; teardown() unsubscribes all session listeners and
-  // unpublishes. Deferred to session_start because identifying a child
-  // requires the session id from ctx, unavailable at factory-init time.
+  // activate() publishes this node's service under its own session id (and to
+  // the legacy root slot unless this is a registered subagent child — see
+  // #302), then announces the node's session id and chain role on the ready
+  // channel; teardown() unsubscribes all session listeners and unpublishes.
+  // Deferred to session_start because both facts come from ctx, unavailable at
+  // factory-init time.
   const serviceLifecycle = new PermissionServiceLifecycle(
     permissionsService,
     subagentDetection,
+    authorizerSelection,
     pi.events,
     [unsubSubagentLifecycle],
   );
@@ -274,13 +294,18 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
     audit,
   );
-  const agentPrep = new AgentPrepHandler(
+  const turnPrep = new SessionTurnPrep(
     session,
-    resolver,
-    toolRegistry,
     () => {
       void warmBashParser();
     },
+    serviceLifecycle,
+  );
+  const agentPrep = new AgentPrepHandler(
+    turnPrep,
+    session,
+    resolver,
+    toolRegistry,
   );
 
   const gateRunner = new GateRunner(

package/src/permission-events.ts

@@ -18,7 +18,14 @@ export interface PermissionEventBus {
 
 // ── Channel name constants ─────────────────────────────────────────────────
 
-/** Emitted at `session_start`, after the service is published. */
+/**
+ * Emitted at `session_start` after the emitting node published its service, and
+ * again at that node's first `before_agent_start` (ADR 0012 decision 3).
+ *
+ * Fires at least once per session and may repeat, so a handler must be
+ * idempotent — registering on every emission hits the duplicate-registration
+ * throw.
+ */
 export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 
 /** Emitted when a permission request is committed to the active UI prompt path. */
@@ -30,13 +37,34 @@ export const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
 // ── permissions:ready ──────────────────────────────────────────────────────
 
 /**
- * Payload emitted on `permissions:ready`.
+ * Payload emitted on `permissions:ready`: plain facts about the node that
+ * emitted it (ADR 0012 decision 2).
  *
- * Intentionally empty: the channel is a readiness signal. There is no
- * `protocolVersion` — the published types plus package semver define the
- * broadcast contract.
+ * The bus announces; the locator provides. The payload carries data a consumer
+ * can log, serialize, and replay — never a live capability — so the service
+ * itself is fetched with `getPermissionsService(sessionId)`.
+ *
+ * There is no `protocolVersion` — the published types plus package semver
+ * define the broadcast contract.
  */
-export type PermissionsReadyEvent = Record<string, never>;
+export interface PermissionsReadyEvent {
+  /**
+   * The emitting node's session id: the key for
+   * `getPermissionsService`. `null` when the host exposed no session
+   * id, in which case this node published no keyed service.
+   */
+  sessionId: string | null;
+  /**
+   * Whether this node adjudicates its own asks (its authorizer chain runs) or
+   * relays them to a serving node, which runs *its* chain over the same facts
+   * (ADR 0007 §7).
+   *
+   * A registration needs no branch on this: extractors and formatters are read
+   * by every node's own gates, and a chain link registered where no chain runs
+   * is accepted and recorded rather than refused (ADR 0012 decision 4).
+   */
+  adjudicatesLocally: boolean;
+}
 
 // ── permissions:ui_prompt ──────────────────────────────────────────────────
 
@@ -152,13 +180,18 @@ export interface PermissionDecisionEvent {
 
 /**
  * Emit the `permissions:ready` broadcast.
- * Call at `session_start`, after the service is published, so a consumer
- * reacting to ready can immediately resolve `getPermissionsService()`.
+ * Call after the node published its service, so a consumer reacting to ready
+ * can immediately resolve `getPermissionsService(event.sessionId)`.
+ * Called twice per session: at `session_start`, and at the first
+ * `before_agent_start` so a consumer whose own `session_start` ran later still
+ * hears it (ADR 0012 decision 3).
  */
-export function emitReadyEvent(events: PermissionEventBus): void {
-  const payload: PermissionsReadyEvent = {};
+export function emitReadyEvent(
+  events: PermissionEventBus,
+  event: PermissionsReadyEvent,
+): void {
   try {
-    events.emit(PERMISSIONS_READY_CHANNEL, payload);
+    events.emit(PERMISSIONS_READY_CHANNEL, event);
   } catch {
     // Broadcasts are best-effort. A throwing listener must not block the
     // permission system from completing session startup.

package/src/service-lifecycle.ts

@@ -1,11 +1,15 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AdjudicationRole } from "./authority/authorizer-selection";
 import type { RegisteredChildDetector } from "./authority/subagent-detection";
 import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
 import {
   type PermissionsService,
   publishPermissionsService,
+  publishRootPermissionsService,
   unpublishPermissionsService,
+  unpublishRootPermissionsService,
 } from "./service";
+import { readSessionId } from "./session-identity";
 
 /** The session-scoped service lifecycle that the lifecycle handler drives. */
 export interface ServiceLifecycle {
@@ -13,35 +17,98 @@ export interface ServiceLifecycle {
   teardown(): void;
 }
 
+/**
+ * Announces this node's ready facts at most once per session, whatever the
+ * caller does (ADR 0012 decision 3, the ready latch).
+ *
+ * Kept separate from `ServiceLifecycle` because the two roles have different
+ * callers: the session lifecycle starts and tears the node down, while the
+ * latch fires from the turn about to start.
+ */
+export interface ReadyAnnouncer {
+  announceReady(ctx: ExtensionContext): void;
+}
+
 /**
  * Owns the process-global service publication lifecycle for one extension
- * instance.
+ * instance — that is, for one node (ADR 0012).
  *
- * - `activate` publishes the service (skipped for registered subagent children
- *   so they never clobber the parent's slot — see #302), then emits the ready
- *   event.
+ * - `activate` publishes the service under this node's own session id, so a
+ *   sibling extension loaded into this node registers into the registries this
+ *   node's gates and chain read. It additionally publishes to the legacy
+ *   process-root slot unless this is a registered subagent child, which must
+ *   not clobber its parent's slot (#302). Then it announces both facts a
+ *   consumer needs — the session id and the chain role — on the ready channel,
+ *   and re-arms the latch so the turn about to start announces once more.
+ * - `announceReady` is that second announcement: it fires at most once per
+ *   activation cycle, so `permissions:ready` reaches a consumer whose own
+ *   `session_start` ran after this node's (ADR 0012 decision 3). The channel's
+ *   contract is therefore "at least once per session, and may repeat" —
+ *   handlers must be idempotent.
  * - `teardown` runs all session-scoped subscription cleanups in order, then
- *   unpublishes the service.
+ *   unpublishes from both slots. Each unpublish is identity-scoped, so a
+ *   superseded `/reload` generation cannot evict the fresh one.
  */
-export class PermissionServiceLifecycle implements ServiceLifecycle {
+export class PermissionServiceLifecycle
+  implements ServiceLifecycle, ReadyAnnouncer
+{
+  /** The key this instance last published under; `null` until it publishes. */
+  private publishedSessionId: string | null = null;
+
+  /** Whether the latch has already announced for the current session. */
+  private announced = false;
+
   constructor(
     private readonly service: PermissionsService,
     private readonly detection: RegisteredChildDetector,
+    private readonly role: AdjudicationRole,
     private readonly events: PermissionEventBus,
     private readonly subscriptions: readonly (() => void)[],
   ) {}
 
   activate(ctx: ExtensionContext): void {
+    // Re-arm: a new session generation gets its own post-session_start
+    // announcement, so a consumer that loaded after this node still hears one.
+    this.announced = false;
+    const sessionId = readSessionId(ctx);
+    if (sessionId !== null) {
+      publishPermissionsService(sessionId, this.service);
+      this.publishedSessionId = sessionId;
+    }
     if (!this.detection.isRegisteredChild(ctx)) {
-      publishPermissionsService(this.service);
+      publishRootPermissionsService(this.service);
+    }
+    this.emitReady(ctx);
+  }
+
+  announceReady(ctx: ExtensionContext): void {
+    if (this.announced) {
+      return;
     }
-    emitReadyEvent(this.events);
+    this.announced = true;
+    this.emitReady(ctx);
   }
 
   teardown(): void {
     for (const unsubscribe of this.subscriptions) {
       unsubscribe();
     }
-    unpublishPermissionsService(this.service);
+    if (this.publishedSessionId !== null) {
+      unpublishPermissionsService(this.publishedSessionId, this.service);
+      this.publishedSessionId = null;
+    }
+    unpublishRootPermissionsService(this.service);
+  }
+
+  /**
+   * The one place a ready payload is built, so the `session_start` emission and
+   * the latch emission cannot drift in shape: both read the node's facts from
+   * the context they are handed.
+   */
+  private emitReady(ctx: ExtensionContext): void {
+    emitReadyEvent(this.events, {
+      sessionId: readSessionId(ctx),
+      adjudicatesLocally: this.role.adjudicatesLocally(),
+    });
   }
 }

package/src/service.ts

@@ -1,14 +1,24 @@
 /**
- * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ * Cross-extension service accessors 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.
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but the
+ * accessors here read from the same `globalThis` slots 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.
+ * There are two slots, because one process can host several **nodes** (one Pi
+ * session runtime each — a root session and its in-process subagent children
+ * all load their own instance of this extension):
+ *
+ * - A session-keyed map, written by every node under its own session id.
+ *   `getPermissionsService(sessionId)` resolves the service whose
+ *   registries that node's own gates and chain read (ADR 0012 decision 2).
+ * - A single legacy slot holding the process root's service, read by the
+ *   deprecated `getRootPermissionsService()`.
+ *
+ * Best practice: resolve per use rather than caching the reference — this
+ * ensures resilience across `/reload` and load-order edge cases.
  */
 
 import type { Authorizer } from "./authority/authorizer";
@@ -62,9 +72,14 @@ export type {
 } from "./presentation/prompt-payload";
 export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
 
-/** Process-global key for the service slot. */
+/** Process-global key for the legacy (process-root) service slot. */
 const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
 
+/** Process-global key for the session-keyed service map (ADR 0012 decision 2). */
+const SESSION_SERVICES_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:session-services",
+);
+
 /**
  * The narrow, read-only projection of {@link PermissionsService}: answer a
  * policy query for a surface, and report a tool-level state. This is the
@@ -104,7 +119,14 @@ export interface PermissionQuery {
 }
 
 /**
- * Public interface exposed to other extensions via `getPermissionsService()`.
+ * Public interface exposed to other extensions via
+ * {@link getPermissionsService} (or the deprecated
+ * {@link getRootPermissionsService}).
+ *
+ * Each instance belongs to one node, and its three registration surfaces are
+ * read by that node alone: extractors and formatters by its own gates, chain
+ * links by its own chain. Resolve the service of the node whose behavior you
+ * mean to affect.
  *
  * `checkPermission` takes a surface + optional value + optional agent name,
  * and delegates to `PermissionManager.checkPermission()` with current session
@@ -182,28 +204,176 @@ export interface PermissionsService extends PermissionQuery {
 }
 
 /**
- * Store a `PermissionsService` on `globalThis` so other extensions can
- * retrieve it via `getPermissionsService()`.
+ * Store a `PermissionsService` in the legacy process-root slot, read by
+ * `getRootPermissionsService()`.
  *
  * 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.
  */
-export function publishPermissionsService(service: PermissionsService): void {
+export function publishRootPermissionsService(
+  service: PermissionsService,
+): void {
   (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
 }
 
 /**
- * Retrieve the published `PermissionsService`, or `undefined` if the
- * permission-system extension has not loaded (or has been unloaded).
+ * Warned at most once per module copy, so a consumer hears it on its first
+ * deprecated call and never again. Under jiti isolation each consumer
+ * extension holds its own copy, so each hears it for its own call site.
  */
-export function getPermissionsService(): PermissionsService | undefined {
+let warnedDeprecatedAccessor = false;
+
+const DEPRECATED_ACCESSOR_WARNING =
+  "getRootPermissionsService() is deprecated: it answers with the process root's " +
+  "service, which is the wrong node in every node but the root — inside an " +
+  "in-process subagent child it hands back the parent's service, so a " +
+  "registration lands where the child's gates never read it and a policy " +
+  "query answers against the parent's config. Use " +
+  "getPermissionsService(sessionId) with the sessionId from the " +
+  "permissions:ready payload. See " +
+  "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/cross-extension-api.md";
+
+/**
+ * Retrieve the process root's published `PermissionsService`, or `undefined`
+ * if the permission-system extension has not loaded (or has been unloaded).
+ *
+ * @deprecated Use {@link getPermissionsService} with the `sessionId`
+ * from the `permissions:ready` payload. This accessor answers "the process
+ * root's service", which is the wrong question in every node but the root.
+ * Removal is deferred to a future major (ADR 0012 decision 7).
+ */
+export function getRootPermissionsService(): PermissionsService | undefined {
+  if (!warnedDeprecatedAccessor) {
+    warnedDeprecatedAccessor = true;
+    process.emitWarning(DEPRECATED_ACCESSOR_WARNING, {
+      type: "DeprecationWarning",
+      code: "PI_PERMISSION_SYSTEM_DEP0001",
+    });
+  }
+  return readRootService();
+}
+
+/**
+ * The undeprecated read of the root slot, for this package's own lifecycle.
+ *
+ * `unpublishRootPermissionsService` must compare identities without warning the
+ * host about a call the host did not make.
+ */
+function readRootService(): PermissionsService | undefined {
   return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
     | PermissionsService
     | undefined;
 }
 
+/**
+ * The process-global map of session id → that node's service, created on first
+ * use.
+ *
+ * Backed by `globalThis` + `Symbol.for()` for the same reason the single slot
+ * above is: each session's `ResourceLoader` builds its own jiti instance, so a
+ * parent and its in-process child share no module state — only process globals.
+ */
+function sessionServices(): Map<string, PermissionsService> {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[SESSION_SERVICES_KEY] as
+    | Map<string, PermissionsService>
+    | undefined;
+  if (existing) {
+    return existing;
+  }
+  const services = new Map<string, PermissionsService>();
+  store[SESSION_SERVICES_KEY] = services;
+  return services;
+}
+
+/**
+ * Publish `service` as the service of the node whose session is `sessionId`
+ * (ADR 0012 decision 2 — node-locality).
+ *
+ * Every node publishes under its own key, including an in-process subagent
+ * child, so there is nothing to clobber: a child's sibling extension registers
+ * an extractor, formatter, or chain link into the registry the child's own
+ * gates and chain read.
+ */
+export function publishPermissionsService(
+  sessionId: string,
+  service: PermissionsService,
+): void {
+  sessionServices().set(sessionId, service);
+}
+
+/**
+ * Retrieve the service belonging to the node whose session is `sessionId`, or
+ * `undefined` when that node has published none.
+ *
+ * This is the supported way to obtain a node's service, for registration and
+ * for policy queries alike. Take `sessionId` from the `permissions:ready`
+ * payload (or from `ctx.sessionManager.getSessionId()` inside your own session
+ * handler), and resolve per use rather than caching the reference.
+ *
+ * A caller the type checker cannot reach — JavaScript, or a consumer compiled
+ * against an earlier major — may still call this with no argument. That answers
+ * `undefined` rather than another node's service, and warns once so the missing
+ * registration is not silent.
+ */
+export function getPermissionsService(
+  sessionId: string,
+): PermissionsService | undefined {
+  if (typeof sessionId !== "string") {
+    warnMissingSessionId();
+    return undefined;
+  }
+  return sessionServices().get(sessionId);
+}
+
+const MISSING_SESSION_ID_WARNING =
+  "getPermissionsService() was called without a session id and answered " +
+  "undefined. It resolves the service of one node, so it needs the sessionId " +
+  "from the permissions:ready payload: getPermissionsService(sessionId). To " +
+  "read the process root's service — what the zero-arg call used to do — use " +
+  "the deprecated getRootPermissionsService(). See " +
+  "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/cross-extension-api.md";
+
+/**
+ * Warned at most once per module copy, like the deprecation guard above, so a
+ * consumer polling the locator every turn reports the defect once.
+ *
+ * Deliberately not a `DeprecationWarning`: an operator who silences those with
+ * `--no-deprecation` still needs to hear that a registration never landed.
+ */
+let warnedMissingSessionId = false;
+
+function warnMissingSessionId(): void {
+  if (warnedMissingSessionId) {
+    return;
+  }
+  warnedMissingSessionId = true;
+  process.emitWarning(MISSING_SESSION_ID_WARNING, {
+    type: "Warning",
+    code: "PI_PERMISSION_SYSTEM_WARN0001",
+  });
+}
+
+/**
+ * Remove the `sessionId` entry, but only when it still holds `service`
+ * (identity compare-and-delete, like {@link unpublishRootPermissionsService}).
+ *
+ * Scoping the delete to the publishing instance keeps a superseded `/reload`
+ * generation's late shutdown from wiping the new generation's freshly
+ * published service.
+ */
+export function unpublishPermissionsService(
+  sessionId: string,
+  service: PermissionsService,
+): void {
+  const services = sessionServices();
+  if (services.get(sessionId) === service) {
+    services.delete(sessionId);
+  }
+}
+
 /**
  * Remove `service` from `globalThis`, but only when the current slot still
  * holds it (identity compare-and-delete).
@@ -217,8 +387,10 @@ export function getPermissionsService(): PermissionsService | undefined {
  * - A superseded `/reload` generation no longer owns the slot, so its late
  *   shutdown cannot wipe the new generation's freshly published service.
  */
-export function unpublishPermissionsService(service: PermissionsService): void {
-  if (getPermissionsService() !== service) {
+export function unpublishRootPermissionsService(
+  service: PermissionsService,
+): void {
+  if (readRootService() !== service) {
     return;
   }
   // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable

package/src/session-identity.ts

@@ -0,0 +1,33 @@
+/**
+ * session-identity.ts — This node's own session id.
+ *
+ * One Pi session runtime is a **node** (ADR 0012): its own `ExtensionContext`,
+ * event bus, gates, and `PermissionSession`. The session id is how a node names
+ * itself to the rest of the process — it keys the subagent-child registry, the
+ * serving-heartbeat records, and the session-keyed service publication.
+ *
+ * The read is defensive because the id is not guaranteed to be reachable: a
+ * host may expose a session manager without one. An unavailable id is `null`
+ * rather than a throw, so a caller decides what to do without an unreachable
+ * id (skip a keyed publication, report "not a registered child") instead of
+ * failing session startup.
+ */
+
+/** Narrow context: the only session-manager reader {@link readSessionId} consumes. */
+export interface SessionIdentityContext {
+  sessionManager: {
+    getSessionId(): string;
+  };
+}
+
+/**
+ * Return the session id `ctx` belongs to, or `null` when the host does not
+ * expose one (absent, empty, or throwing).
+ */
+export function readSessionId(ctx: SessionIdentityContext): string | null {
+  try {
+    return ctx.sessionManager.getSessionId() || null;
+  } catch {
+    return null;
+  }
+}