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

package/dist/hosts/integration/pi-native-events.js

@@ -0,0 +1,348 @@
+/**
+ * In-process native Pi event-fact capture (rollover observation source).
+ *
+ * A small, bounded, opt-in producer that subscribes to a fixed set of supported installed Pi 1.3.0
+ * extension callbacks and derives conservative in-process facts plus invalidation notifications. It is
+ * NOT authority, external control, writer fencing, or a native-stop/quiescence/transfer proof. It never
+ * calls the accepted freeze controller's `observe()`, never synthesizes queue/approval numbers, and
+ * never infers a stop from balanced tool events. Facts come only from live callback contexts, never from
+ * caller-supplied fact JSON.
+ *
+ * It holds no resources: no timer, watcher, filesystem, process, transcript, network, controller, or
+ * rollover import. In-memory only: a restart or reload loses every fact. There is no thaw and no
+ * transfer behavior.
+ *
+ * Conservative identity handling: an unknown, throwing, or malformed session read invalidates the prior
+ * session-derived facts (settled confidence and tool-tracking health) and never revalidates them on the
+ * next matching identity read; only a later trustworthy supported boundary can re-establish settled, and
+ * only a native session change starts fresh tool tracking. Payload reads are guarded so a throwing or
+ * proxy accessor is treated as malformed and still notifies subscribers.
+ *
+ * Notifications are delivered in chronological order under bounded reentrancy. If the bounded buffer or
+ * per-drain budget is exceeded, delivery is lost; this is a sticky delivery gap. Rather than ending any
+ * subscriber on an older healthy snapshot, the drain discards stale buffered facts and delivers one
+ * terminal, conservative gap invalidation to every still-subscribed listener. The gap is sticky: while it
+ * is unresolved every snapshot reports `notificationBacklogOverflow`, `settled: 'unknown'` and
+ * `toolTrackingHealthy: false`, and no ordinary later event restores healthy confidence.
+ *
+ * Installed Pi 1.3.0 API pinned from the installed docs/examples (the package ships no .d.ts):
+ *   docs/extensions.md (sha256:a2b5ff0f95e7e470ed0846d7c4fbfc5781fe7e694b8e7f51ea08859f3ad7325d):
+ *   lifecycle events `session_start`, `before_agent_start` (a run becomes busy), `agent_settled`
+ *   (final, "Pi will not continue automatically"), and nested `tool_execution_start` /
+ *   `tool_execution_end` carrying a string `toolCallId` (`<parent id>/<n>` for nested calls); the
+ *   running session is read from `ctx.sessionManager.getSessionId()` and idleness from `ctx.isIdle()`
+ *   (examples/extensions/send-user-message.ts
+ *   sha256:9261e433c782f354530105e1c9723a19798868f72fd1f5d68af3a4624ad7e446). The narrow structural
+ *   host interface below matches that shape; structural compatibility is not a shipped-declaration or
+ *   live-load proof.
+ */
+export const PI_NATIVE_EVENTS_SCHEMA = 'pappra/pi-native-events/1';
+/** The only installed callbacks this producer subscribes. Nothing else is observed. */
+export const SUPPORTED_CALLBACKS = Object.freeze([
+    'session_start',
+    'before_agent_start',
+    'agent_settled',
+    'tool_execution_start',
+    'tool_execution_end',
+]);
+const MAX_ID_LENGTH = 256;
+const DEFAULT_MAX_TRACKED_TOOLS = 4096;
+const DEFAULT_MAX_SEQUENCE = Number.MAX_SAFE_INTEGER;
+const DEFAULT_MAX_NOTIFY_QUEUE = 1024;
+/**
+ * Honest boundaries of these facts. Shared frozen; a snapshot exposes the same immutable array.
+ */
+export const NATIVE_EVENT_LIMITATIONS = Object.freeze([
+    'in_process_observations_only_not_authority_external_control_or_writer_fencing',
+    'not_a_native_stop_quiescence_or_transfer_proof',
+    'queue_depth_and_global_approvals_unknown_no_supported_extension_api',
+    'in_flight_tool_completeness_unknown_observed_open_count_is_not_authoritative',
+    'unknown_session_identity_invalidates_settled_and_tool_tracking_confidence',
+    'notification_delivery_gap_delivers_a_terminal_invalidation_to_every_listener_and_stays_sticky',
+    'does_not_observe_background_or_external_non_managed_tool_activity',
+    'memory_only_facts_lost_on_restart_or_reload_no_thaw_no_transfer',
+    'produces_facts_only_never_calls_controller_observe_or_asserts_readiness',
+]);
+function isSafeId(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= MAX_ID_LENGTH);
+}
+/** Pinned: the running session id is `ctx.sessionManager.getSessionId()`. Any failure stays unknown. */
+function readSessionId(context) {
+    try {
+        if (typeof context !== 'object' || context === null)
+            return null;
+        const manager = context.sessionManager;
+        if (typeof manager !== 'object' || manager === null)
+            return null;
+        const getter = manager.getSessionId;
+        if (typeof getter !== 'function')
+            return null;
+        const value = getter.call(manager);
+        return isSafeId(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Pinned: idleness is `ctx.isIdle()`. A throw, a missing method, or a non-boolean stays unknown. */
+function readIdle(context) {
+    try {
+        if (typeof context !== 'object' || context === null)
+            return 'unknown';
+        const getter = context.isIdle;
+        if (typeof getter !== 'function')
+            return 'unknown';
+        const value = getter.call(context);
+        return typeof value === 'boolean' ? value : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * A tool event carries a string `toolCallId`. The property read is guarded: a throwing/proxy accessor or
+ * any non-string is treated as malformed (returns null), never propagated into the host event path.
+ */
+function readToolCallId(event) {
+    try {
+        if (typeof event !== 'object' || event === null)
+            return null;
+        const raw = event.toolCallId;
+        return isSafeId(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+class Producer {
+    #maxTrackedTools;
+    #maxSequence;
+    #maxNotifyQueue;
+    #openTools = new Set();
+    #listeners = new Set();
+    #notifyQueue = [];
+    #sessionId;
+    #sessionKnown;
+    #settled = 'unknown';
+    #idle = 'unknown';
+    #toolTrackingHealthy = true;
+    #sequence = 0;
+    #sequenceSaturated = false;
+    #notificationOverflow = false;
+    #overflowPending = false;
+    #draining = false;
+    constructor(options) {
+        const seeded = isSafeId(options.sessionId) ? options.sessionId : null;
+        this.#sessionId = seeded;
+        this.#sessionKnown = seeded !== null;
+        this.#maxTrackedTools = positiveIntOr(options.maxTrackedTools, DEFAULT_MAX_TRACKED_TOOLS);
+        this.#maxSequence = positiveIntOr(options.maxSequence, DEFAULT_MAX_SEQUENCE);
+        this.#maxNotifyQueue = positiveIntOr(options.maxNotifyQueue, DEFAULT_MAX_NOTIFY_QUEUE);
+    }
+    handle(kind, event, context) {
+        // Every subscribed callback advances the sequence first, including malformed events, identity
+        // failures, and session changes; the monotonic sequence is never reset by any of them.
+        this.#advance();
+        this.#applySession(context);
+        this.#idle = readIdle(context);
+        // Boundary and tool facts are applied only under a known, trustworthy identity. An unknown session
+        // already invalidated settled and tool-tracking confidence in #applySession, so nothing is applied
+        // and no unassociated event mutates the last session's tracked ids.
+        if (this.#sessionKnown) {
+            switch (kind) {
+                case 'before_agent_start':
+                    this.#settled = false;
+                    break;
+                case 'agent_settled':
+                    this.#settled = true;
+                    break;
+                case 'tool_execution_start':
+                    this.#trackStart(event);
+                    break;
+                case 'tool_execution_end':
+                    this.#trackEnd(event);
+                    break;
+                case 'session_start':
+                    break;
+            }
+        }
+        this.#enqueueNotify();
+    }
+    #advance() {
+        if (this.#sequenceSaturated)
+            return;
+        if (this.#sequence >= this.#maxSequence) {
+            this.#sequenceSaturated = true;
+            return;
+        }
+        this.#sequence += 1;
+        if (this.#sequence >= this.#maxSequence)
+            this.#sequenceSaturated = true;
+    }
+    #applySession(context) {
+        const id = readSessionId(context);
+        if (id === null) {
+            // Unknown identity: invalidate prior session-derived facts rather than resurrecting them on a
+            // later matching read. The last known id is retained only so a recovery is not mistaken for a
+            // change; confidence stays invalidated until a trustworthy boundary or a real session change.
+            this.#sessionKnown = false;
+            this.#settled = 'unknown';
+            this.#toolTrackingHealthy = false;
+            return;
+        }
+        this.#sessionKnown = true;
+        if (this.#sessionId !== id) {
+            // Native session change: clear this session's facts and tracked ids, but never the sequence. A new
+            // session is the only trustworthy reset of tracking health (a delivery gap, if any, stays sticky).
+            this.#sessionId = id;
+            this.#settled = 'unknown';
+            this.#openTools.clear();
+            this.#toolTrackingHealthy = true;
+        }
+    }
+    #trackStart(event) {
+        const id = readToolCallId(event);
+        if (id === null) {
+            this.#toolTrackingHealthy = false;
+            return;
+        }
+        if (this.#openTools.has(id)) {
+            this.#toolTrackingHealthy = false;
+            return;
+        }
+        if (this.#openTools.size >= this.#maxTrackedTools) {
+            this.#toolTrackingHealthy = false;
+            return;
+        }
+        this.#openTools.add(id);
+    }
+    #trackEnd(event) {
+        const id = readToolCallId(event);
+        if (id === null) {
+            this.#toolTrackingHealthy = false;
+            return;
+        }
+        if (!this.#openTools.has(id)) {
+            this.#toolTrackingHealthy = false;
+            return;
+        }
+        this.#openTools.delete(id);
+    }
+    #markDeliveryGap() {
+        // A delivery gap is sticky and owes a terminal, subscriber-visible loss notification this drain.
+        this.#notificationOverflow = true;
+        this.#overflowPending = true;
+    }
+    #deliver(facts) {
+        // Copy the listener set so subscription changes during delivery cannot corrupt the walk, and isolate
+        // each listener so one throwing listener cannot starve the others or the producer.
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(facts);
+            }
+            catch {
+                // Listener isolation: swallow and continue.
+            }
+        }
+    }
+    #enqueueNotify() {
+        if (this.#notifyQueue.length >= this.#maxNotifyQueue) {
+            this.#markDeliveryGap();
+        }
+        else {
+            this.#notifyQueue.push(this.snapshot());
+        }
+        if (this.#draining)
+            return;
+        this.#drain();
+    }
+    #drain() {
+        this.#draining = true;
+        try {
+            // Serialize delivery so reentrant events do not interleave: each subscriber sees snapshots in
+            // chronological sequence order. Delivery per drain is bounded to guarantee termination.
+            let delivered = 0;
+            while (this.#notifyQueue.length > 0) {
+                // Once a gap exists, stop delivering stale buffered healthy facts.
+                if (this.#overflowPending)
+                    break;
+                if (delivered >= this.#maxNotifyQueue) {
+                    this.#markDeliveryGap();
+                    break;
+                }
+                const facts = this.#notifyQueue.shift();
+                if (facts === undefined)
+                    break;
+                this.#deliver(facts);
+                delivered += 1;
+            }
+            if (this.#overflowPending) {
+                // Terminal, subscriber-visible loss: discard stale buffered facts and deliver exactly one
+                // conservative invalidation so every still-subscribed listener's final fact is the gap, never an
+                // older healthy snapshot. Events fired reentrantly during this delivery are dropped (bounded);
+                // the sticky overflow keeps every later snapshot invalid, so no further drain is started here.
+                this.#overflowPending = false;
+                this.#notifyQueue.length = 0;
+                this.#deliver(this.snapshot());
+                this.#notifyQueue.length = 0;
+                this.#overflowPending = false;
+            }
+        }
+        finally {
+            this.#draining = false;
+        }
+    }
+    snapshot() {
+        // A sticky delivery gap forces conservative confidence; no ordinary later event restores it.
+        const gap = this.#notificationOverflow;
+        const facts = {
+            schema: PI_NATIVE_EVENTS_SCHEMA,
+            sessionId: this.#sessionId,
+            sessionKnown: this.#sessionKnown,
+            settled: gap ? 'unknown' : this.#settled,
+            idle: this.#idle,
+            inFlightCompleteness: 'unknown',
+            observedOpenToolCount: this.#openTools.size,
+            toolTrackingHealthy: this.#toolTrackingHealthy && !gap,
+            queue: 'unknown',
+            approvals: 'unknown',
+            nativeStop: false,
+            sequence: this.#sequence,
+            sequenceSaturated: this.#sequenceSaturated,
+            notificationBacklogOverflow: gap,
+            limitations: NATIVE_EVENT_LIMITATIONS,
+        };
+        return Object.freeze(facts);
+    }
+    onInvalidate(listener) {
+        this.#listeners.add(listener);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this.#listeners.delete(listener);
+        };
+    }
+}
+function positiveIntOr(value, fallback) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+        ? value
+        : fallback;
+}
+/**
+ * Subscribe a fresh producer to the five supported callbacks on `pi`. It only touches the supplied
+ * host (`pi.on`); it starts, installs, exports, and wires nothing else. The returned producer yields
+ * observations and invalidation notifications only — never authority, control, or a stop proof.
+ */
+export function registerPiNativeEvents(pi, options) {
+    const producer = new Producer(options);
+    for (const callback of SUPPORTED_CALLBACKS) {
+        pi.on(callback, (event, context) => {
+            producer.handle(callback, event, context);
+        });
+    }
+    return producer;
+}

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

@@ -0,0 +1,166 @@
+/**
+ * Opt-in in-session Pi managed-tool freeze (rollover prerequisite).
+ *
+ * A separately opt-in Pi extension/controller: a later explicit integration calls
+ * `registerPiRolloverFreeze(pi, …)` inside a managed interactive session. This module does NOT
+ * activate in the current session, install itself, change default lifecycle hooks or touch user
+ * settings. It is self-contained: no subprocess, model, network, transcript, file watcher, timer,
+ * automatic handoff or successor launch, and no imports of the rollover orchestrator.
+ *
+ * What it is: a fail-closed managed Pi tool barrier. While latched it BLOCKS every tool except an
+ * explicit, vetted native read allowlist. Only tools in a fixed vetted read-tool universe can be
+ * allow-listed; bash/write/edit and every unknown/custom tool are blocked regardless of
+ * configuration. It never parses shell commands or tool paths and never calls a shell.
+ *
+ * What it is NOT: an OS sandbox, a stop proof, or an authority control. Pre-existing/background
+ * processes and external writers are outside it. A freeze latch alone is not "confirmed stopped".
+ * Native settled/queue/in-flight/approval facts are caller-supplied, UNAUTHENTICATED observations,
+ * never host-verified; any unknown/busy/pending condition and any session change or tool activity
+ * yield not-ready. Each readiness snapshot must be a complete coherent observation; absent facts are
+ * unknown, never an inherited historical all-clear. The latch is memory-only: a restart/reload loses
+ * it. There is intentionally NO thaw: recovery/release is a later, separately scoped,
+ * authority-checked integration.
+ *
+ * Installed Pi 1.3.0 API pinned from the installed example extensions (the package ships no .d.ts):
+ *   permission-gate.ts (sha256:e32086ba9dd9b4ba0fd308b65241d9affa0b5ecd3f90ef7ea1b9f2b30cab8cc1),
+ *   protected-paths.ts (sha256:9ca66b1f3b1b9a61cc5ddc660f92cca2ea66c4264a1bdb6b00e0da5844399fe2),
+ *   commands.ts        (sha256:36716b53da169936c7e1360a4fde1e2fc0c3356a6505f177235f09c5538c6e4f),
+ *   docs/extensions.md (sha256:a2b5ff0f95e7e470ed0846d7c4fbfc5781fe7e694b8e7f51ea08859f3ad7325d):
+ *   `pi.on("tool_call", async (event, ctx) => { … return { block: true, reason }; }` [allow: return
+ *   undefined] with `event.toolName: string` and `event.input: Record<string, unknown>`;
+ *   `pi.registerCommand(name, { description, handler })`; and the running session is read from
+ *   `ctx.sessionManager.getSessionId()`. The narrow structural `PiFreezeHost` interface matches that
+ *   shape. Structural compatibility checks are NOT a shipped-declaration or live-load proof.
+ */
+export declare const PI_ROLLOVER_FREEZE_STATUS_SCHEMA = "pappra/pi-rollover-freeze-status/1";
+/**
+ * The fixed vetted native read-tool universe. Only these may ever be allow-listed while latched.
+ * Pi 1.3.0 built-in tools are read/bash/edit/write; `read` is the only read-only one. `bash` can
+ * read but also write, so it is deliberately excluded; write/edit/unknown/custom are never allowed.
+ */
+export declare const VETTED_NATIVE_READ_TOOLS: readonly string[];
+/** Default allowlist (the full vetted read universe). A caller may only narrow within the vetted set. */
+export declare const DEFAULT_READ_TOOL_ALLOWLIST: readonly string[];
+export interface FreezeToken {
+    readonly sessionId: string;
+    readonly taskId: string;
+    readonly handoffId: string;
+    readonly generation: number;
+}
+export type FreezeOutcome = {
+    readonly ok: true;
+    readonly state: 'frozen' | 'already_frozen';
+    readonly idempotent: boolean;
+    readonly token: FreezeToken;
+} | {
+    readonly ok: false;
+    readonly reason: 'invalid_token' | 'wrong_session' | 'conflicting_freeze' | 'stale_generation';
+    readonly detail: string;
+};
+export interface ToolDecision {
+    readonly block: boolean;
+    readonly reason: string | null;
+}
+/**
+ * One caller-supplied, UNAUTHENTICATED native observation. It must carry the full freeze token and
+ * is a COMPLETE snapshot; an omitted count/flag is treated as unknown, never an inherited fact.
+ */
+export interface NativeObservation {
+    readonly token: FreezeToken;
+    readonly sequence: number;
+    readonly settled?: boolean;
+    readonly queuedMessages?: number;
+    readonly inFlightTools?: number;
+    readonly pendingApprovals?: number;
+}
+export type ObserveOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'not_frozen' | 'token_mismatch' | 'invalid_observation' | 'stale_sequence';
+    readonly detail: string;
+};
+export interface FreezeNativeStatus {
+    readonly settled: 'yes' | 'no' | 'unknown';
+    readonly queuedMessages: number | 'unknown';
+    readonly inFlightTools: number | 'unknown';
+    readonly pendingApprovals: number | 'unknown';
+    readonly observedSequence: number | null;
+}
+export interface FreezeStatus {
+    readonly schema: typeof PI_ROLLOVER_FREEZE_STATUS_SCHEMA;
+    readonly sessionId: string;
+    readonly frozen: boolean;
+    readonly token: FreezeToken | null;
+    readonly native: FreezeNativeStatus;
+    /** The replay fence: the last accepted observation sequence, surviving readiness invalidation. */
+    readonly lastAcceptedSequence: number | null;
+    /** True only when frozen AND every native fact is a fresh caller-supplied advisory all-clear snapshot (not authoritative live-native facts). */
+    readonly ready: boolean;
+    readonly readyBlockers: readonly string[];
+    /** Readiness is advisory: observations are caller-supplied and unauthenticated, not a stop proof. */
+    readonly observationSource: 'caller-supplied-unauthenticated';
+    readonly readinessIsNativeStopProof: false;
+    readonly thawSupported: false;
+    readonly limitations: readonly string[];
+}
+export interface RolloverFreezeOptions {
+    /** The native session this controller is bound to; freeze tokens and callbacks must match it. */
+    readonly sessionId: string;
+    /** Narrowing selection within the vetted read universe; unsafe names are dropped conservatively. */
+    readonly readAllowlist?: readonly string[];
+}
+/**
+ * In-memory, no-I/O freeze controller. One instance per managed session; the `pi` registration
+ * wires it to `tool_call` and the freeze/status commands. A fresh instance starts UNPROVEN
+ * (not frozen, not ready). There is no thaw.
+ */
+export declare class RolloverFreezeController {
+    #private;
+    constructor(options: RolloverFreezeOptions);
+    get sessionId(): string;
+    get frozen(): boolean;
+    freeze(token: FreezeToken): FreezeOutcome;
+    /**
+     * The fail-closed tool barrier, revalidating the live session on every call. A wrong/missing/
+     * changed context session invalidates readiness and fails closed while latched; any tool activity
+     * invalidates a prior all-clear so it cannot be reused without a fresh observation.
+     */
+    decideToolCall(toolName: unknown, contextSessionId: string | null): ToolDecision;
+    /** Reset readiness to unknown (on session change or activity). Does not clear the latch. */
+    invalidateReadiness(): void;
+    /**
+     * Apply one caller-supplied, unauthenticated complete native snapshot correlated to the active
+     * freeze. Validates the full token and every field type; a malformed or stale observation never
+     * changes readiness. Omitted fields become unknown (no inherited all-clear).
+     */
+    observe(observation: NativeObservation): ObserveOutcome;
+    /** A defensive, frozen in-memory status snapshot; mutating it cannot change the controller. */
+    status(): FreezeStatus;
+}
+/** Narrow structural view of the installed Pi 1.3.0 extension host (see header). */
+export interface PiToolCallEvent {
+    readonly toolName: string;
+    readonly input: Record<string, unknown>;
+}
+export interface PiToolBlockDecision {
+    readonly block: true;
+    readonly reason: string;
+}
+export interface PiCommandOptions {
+    readonly description: string;
+    readonly handler: (args: string, context: unknown) => void | Promise<void>;
+}
+export interface PiFreezeHost {
+    on(event: 'tool_call', handler: (event: PiToolCallEvent, context: unknown) => Promise<PiToolBlockDecision | undefined>): void;
+    registerCommand(name: string, options: PiCommandOptions): void;
+}
+/**
+ * Concrete registration entry for a later explicit integration. Wires the controller to the Pi
+ * `tool_call` barrier (revalidating the live session on every call) and to validated
+ * `/rollover-freeze` and `/rollover-status` commands. There is intentionally NO thaw command.
+ * Returns the controller (the no-I/O orchestration surface). It only touches the supplied `pi`.
+ */
+export declare function registerPiRolloverFreeze(pi: PiFreezeHost, options: RolloverFreezeOptions & {
+    readonly controller?: RolloverFreezeController;
+}): RolloverFreezeController;