@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/dist/hosts/integration/pi-bootstrap-extension.d.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { PiBootstrapGuard } from './pi-bootstrap-guard.js';
+/**
+ * Self-contained Pi extension entry for the opt-in successor bootstrap gate.
+ *
+ * This file is bundled into `pappra-bootstrap-extension.mjs` and shipped next to a validated
+ * `bootstrap.json` inside a private export directory. Loading it registers a default-deny
+ * `tool_call` handler before any configuration, reader or lifecycle work; only a fully
+ * initialized accepted guard may reach the real decision. Any failure keeps the deny handler
+ * for the process lifetime and never rethrows into an unrestricted loader fallthrough.
+ *
+ * The status command reports registration, never write permission: `registered` only means the
+ * gate and lifecycle handlers were installed, and `write_permitted` is always `not-asserted`.
+ */
+export declare const PI_BOOTSTRAP_STATUS_SCHEMA = "pappra/pi-bootstrap-status/1";
+export type PiBootstrapState = 'denied' | 'registered';
+export interface PiBootstrapStatus {
+    readonly schema: typeof PI_BOOTSTRAP_STATUS_SCHEMA;
+    /** `registered` means handlers were installed; it is not a permission signal. */
+    readonly state: PiBootstrapState;
+    readonly registered: boolean;
+    /** The gate never asserts current write permission; a tool call still decides per call. */
+    readonly write_permitted: 'not-asserted';
+    readonly mode: 'deny-until-completed-transfer' | 'default-deny';
+    readonly reason: string | null;
+    readonly taskId: string | null;
+    readonly config_digest: string | null;
+    readonly guard: ReturnType<PiBootstrapGuard['status']> | null;
+    readonly limitations: readonly string[];
+}
+/**
+ * Loads the sibling config, registers the accepted runtime gate and the accepted lifecycle
+ * extension, and exposes a read-only status command. Returns the installed handler count only
+ * for tests; the host surface itself has no allow/release API.
+ */
+export default function bootstrapExtension(pi: ExtensionAPI): void;

package/dist/hosts/integration/pi-bootstrap-extension.js

@@ -0,0 +1,101 @@
+import { fileURLToPath } from 'node:url';
+import { boundedReason, readPiBootstrapConfig, runtimeConfigOf, } from './bootstrap-config.js';
+import { registerPiBootstrapRuntime } from './pi-bootstrap-runtime.js';
+import { createPiExtension } from './pi-extension-runtime.js';
+/**
+ * Self-contained Pi extension entry for the opt-in successor bootstrap gate.
+ *
+ * This file is bundled into `pappra-bootstrap-extension.mjs` and shipped next to a validated
+ * `bootstrap.json` inside a private export directory. Loading it registers a default-deny
+ * `tool_call` handler before any configuration, reader or lifecycle work; only a fully
+ * initialized accepted guard may reach the real decision. Any failure keeps the deny handler
+ * for the process lifetime and never rethrows into an unrestricted loader fallthrough.
+ *
+ * The status command reports registration, never write permission: `registered` only means the
+ * gate and lifecycle handlers were installed, and `write_permitted` is always `not-asserted`.
+ */
+export const PI_BOOTSTRAP_STATUS_SCHEMA = 'pappra/pi-bootstrap-status/1';
+const LIMITATIONS = Object.freeze([
+    'registered_is_not_write_permission',
+    'not_a_native_host_load_or_trust_proof',
+    'no_allow_thaw_release_or_permanent_unlock',
+    'check_use_gap_and_background_effects_are_not_fenced',
+]);
+function notify(context, message) {
+    if (typeof context !== 'object' || context === null)
+        return;
+    if ('ui' in context &&
+        typeof context.ui === 'object' &&
+        context.ui !== null &&
+        'notify' in context.ui &&
+        typeof context.ui.notify === 'function') {
+        context.ui.notify(message, 'info');
+    }
+}
+function configPath() {
+    return fileURLToPath(new URL('./bootstrap.json', import.meta.url));
+}
+/**
+ * Loads the sibling config, registers the accepted runtime gate and the accepted lifecycle
+ * extension, and exposes a read-only status command. Returns the installed handler count only
+ * for tests; the host surface itself has no allow/release API.
+ */
+export default function bootstrapExtension(pi) {
+    const extensionHost = pi;
+    let initialized = false;
+    let deniedReason = 'bootstrap-config-not-loaded';
+    let config = null;
+    let configDigest = null;
+    let guard = null;
+    const status = () => ({
+        schema: PI_BOOTSTRAP_STATUS_SCHEMA,
+        state: initialized ? 'registered' : 'denied',
+        registered: initialized,
+        write_permitted: 'not-asserted',
+        mode: initialized ? 'deny-until-completed-transfer' : 'default-deny',
+        reason: initialized ? null : deniedReason,
+        taskId: config?.taskId ?? null,
+        config_digest: configDigest,
+        guard: guard === null ? null : guard.status(),
+        limitations: LIMITATIONS,
+    });
+    // Fail-closed first — every tool call before full initialization is blocked here.
+    // After success it returns `undefined` and the accepted guard handler makes the decision.
+    extensionHost.on('tool_call', () => {
+        if (initialized)
+            return undefined;
+        return {
+            block: true,
+            reason: `pappra-bootstrap: ${deniedReason ?? 'not-initialized'}`,
+        };
+    });
+    try {
+        extensionHost.registerCommand('bootstrap-status', {
+            description: 'Report bootstrap gate registration only (never write permission).',
+            handler: (_args, context) => {
+                notify(context, JSON.stringify(status()));
+            },
+        });
+        const loaded = readPiBootstrapConfig(configPath());
+        if (loaded.ok === false) {
+            deniedReason = `${loaded.code}: ${loaded.message}`;
+            return;
+        }
+        config = loaded.config;
+        configDigest = loaded.digest;
+        const registered = registerPiBootstrapRuntime(pi, runtimeConfigOf(loaded.config));
+        // The accepted lifecycle extension is attached unchanged after the gate.
+        createPiExtension(pi);
+        guard = registered;
+        initialized = true;
+    }
+    catch (error) {
+        try {
+            deniedReason = boundedReason(error);
+        }
+        catch {
+            deniedReason = 'initialization failed';
+        }
+        initialized = false;
+    }
+}

package/dist/hosts/integration/pi-bootstrap-guard.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Opt-in successor-bootstrap managed-tool gate (one rollover prerequisite).
+ *
+ * A separately opt-in Pi `tool_call` guard for the NEW (successor) writer session during a rollover.
+ * Registered before any model work, it starts DENIED for every non-vetted-read managed tool
+ * (bash/write/edit and any unknown/custom tool); only the fixed vetted native-read set reused from the
+ * accepted freeze module is ever allowed, and only for the exact pinned native session. It permits the
+ * successor's first non-read tool ONLY after the authoritative, validated current task record proves the
+ * completed writer transfer to the pinned successor — read fresh on EVERY call. It does not require a
+ * first-work REPORT to permit the first write; that proof comes afterward.
+ *
+ * Authority is validated against the record itself for cross-record CONSISTENCY, not merely schema
+ * validity: the pinned intent in `record.rollover`, the completed WRITER `record.handoffs` entry (kind,
+ * subtask/attempt, coordinator epoch, exact from/to, resources and ownership snapshot consistent with the
+ * intent), a transfer boundary bounded by the current record and history, the latest actionable attempt
+ * owned by the successor with `ownership:'transferred'` and its full confirmed native binding, and every
+ * original claim held by the successor at `original + 1`. Duplicate or ambiguous ids anywhere block rather
+ * than letting a first-match lookup resolve contradictory records to allow. Every check is fail-closed: a
+ * malformed event, a throwing property/record accessor, or any traversal/validation failure returns an
+ * explicit block and never escapes into host default behavior.
+ *
+ * What it is NOT: it is not a transfer action, a stop/quiescence inference, an authority store, or a
+ * filesystem/cross-process write fence. It never mutates claims, epochs, handoffs, bindings, messages,
+ * the bundle or the archive; it never feeds observations into the freeze controller; it adds no timer,
+ * watcher, spawned command, transcript access, network or model call. There is no model-accessible allow/
+ * thaw/release method and no boolean authorization callback. The record comes only from an explicitly
+ * trusted, read-only host adapter supplied at registration that returns record DATA (never `allowed:true`,
+ * a self-signed token or an invented stop proof); this slice does not authenticate a filesystem/remote
+ * source, establish freshness against a dishonest adapter, or install a durable reader — a later real
+ * adapter must bind and read the actual task domain safely, and this is not complete native authorization.
+ *
+ * There is no filesystem lock covering a tool's later execution: the guard answers the call-time question
+ * only (check/use gap), and background/external processes and effects outside managed Pi tools are never
+ * fenced.
+ *
+ * Installed Pi 1.3.0 `tool_call` blocking contract and the vetted native-read set are reused from the
+ * accepted `pi-rollover-extension.ts`; the running session is read from `ctx.sessionManager.getSessionId()`
+ * (pinned API). Structural compatibility is not a shipped-declaration or live-load proof.
+ */
+import { type PiToolBlockDecision, type PiToolCallEvent } from './pi-rollover-extension.js';
+export declare const PI_BOOTSTRAP_GUARD_STATUS_SCHEMA = "pappra/pi-bootstrap-guard-status/1";
+export interface BootstrapGuardIdentity {
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly harness: string;
+}
+/** One pinned ORIGINAL claim: the guard requires the current claim at `originalResourceEpoch + 1`. */
+export interface BootstrapGuardClaim {
+    readonly claimId: string;
+    readonly originalResourceEpoch: number;
+}
+/**
+ * The explicitly trusted, read-only host adapter. It returns the current full task record DATA, or
+ * throws/returns a non-record on failure (treated conservatively as a block). It never returns an allow
+ * decision, a token or a stop proof. In tests this is a fixture; a later real adapter binds and reads the
+ * authoritative task domain. This slice does not authenticate or install it.
+ */
+export type TrustedRecordReader = () => unknown | Promise<unknown>;
+export interface BootstrapGuardOptions {
+    readonly taskId: string;
+    readonly intentId: string;
+    readonly handoffId: string;
+    readonly generation: number;
+    readonly subtaskId: string;
+    readonly attempt: number;
+    readonly inputRevision: string;
+    readonly coordinatorEpoch: number;
+    readonly successor: BootstrapGuardIdentity;
+    readonly claims: readonly BootstrapGuardClaim[];
+    readonly readRecord: TrustedRecordReader;
+}
+interface PinnedConfig {
+    readonly taskId: string;
+    readonly intentId: string;
+    readonly handoffId: string;
+    readonly generation: number;
+    readonly subtaskId: string;
+    readonly attempt: number;
+    readonly inputRevision: string;
+    readonly coordinatorEpoch: number;
+    readonly successor: BootstrapGuardIdentity;
+    readonly claims: readonly BootstrapGuardClaim[];
+}
+export interface BootstrapDecision {
+    readonly allow: boolean;
+    readonly reason: string;
+}
+export interface BootstrapGuardStatus {
+    readonly schema: typeof PI_BOOTSTRAP_GUARD_STATUS_SCHEMA;
+    readonly taskId: string;
+    readonly intentId: string;
+    readonly handoffId: string;
+    readonly generation: number;
+    readonly subtaskId: string;
+    readonly attempt: number;
+    readonly coordinatorEpoch: number;
+    readonly successor: BootstrapGuardIdentity;
+    readonly pinnedClaimCount: number;
+    readonly mode: 'deny-until-completed-transfer';
+    readonly vettedReadTools: readonly string[];
+    readonly limitations: readonly string[];
+}
+export interface PiToolCallHandler {
+    (event: PiToolCallEvent, context: unknown): Promise<PiToolBlockDecision | undefined>;
+}
+/** Narrow structural host: only a `tool_call` subscription is needed (no model-accessible command). */
+export interface PiBootstrapGuardHost {
+    on(event: 'tool_call', handler: PiToolCallHandler): void;
+}
+export interface PiBootstrapGuard {
+    status(): BootstrapGuardStatus;
+}
+/**
+ * Pure decision over the current record. Allows a non-read tool only when the validated record proves a
+ * consistent completed WRITER transfer to the pinned successor. First-work is NOT required. Any traversal
+ * or accessor failure fails closed.
+ */
+export declare function decideBootstrapWrite(record: unknown, pinned: PinnedConfig, liveSessionId: string | null): BootstrapDecision;
+/**
+ * Register the opt-in successor bootstrap gate on `pi`. It only subscribes `tool_call`; it registers no
+ * model-accessible command, removes no tools/MCP/skills/hooks, and mutates nothing. The returned handle
+ * exposes a conservative frozen status only — no allow/thaw/release.
+ */
+export declare function registerPiBootstrapGuard(pi: PiBootstrapGuardHost, options: BootstrapGuardOptions): PiBootstrapGuard;
+export {};