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

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

@@ -0,0 +1,223 @@
+/**
+ * Concrete local task-record reader + opt-in bootstrap-guard registration (one rollover prerequisite).
+ *
+ * This supplies the accepted successor bootstrap guard (`pi-bootstrap-guard.ts`) with a real, bounded,
+ * read-only task-record dependency and wires the actual `tool_call` gate. It is NOT old-writer stop, a
+ * transfer executor, automatic rollover, or an installation; it changes no accepted guard/core/host code.
+ *
+ * Reader contract (fail-closed): it reads ONLY `<domainRoot>/tasks/<taskId>/task.json` for an explicit,
+ * trusted, CANONICAL absolute domain root (rejected at registration if a symlink prefix means
+ * `realpathSync(root) !== root`) and a short safe task id. The three ancestor directories (domain root,
+ * `tasks`, task root) are pinned by device/inode once and re-checked by no-follow `lstat` both BEFORE and
+ * AFTER the bounded read, so a replaced/redirected/symlinked ancestor during the read interval denies the
+ * call instead of silently rebinding; it never creates directories (it does NOT use
+ * `resolveDomainRoot`/`taskRootFor`, which `mkdir`) and never resolves from cwd or a cache. The record is
+ * read via `src/infra/bounded-file.ts` (`readBoundedFile`): a bounded (8 MiB), regular-file,
+ * no-follow, non-blocking descriptor read refusing symlink/FIFO/device/directory targets and oversized
+ * content. The record file's observable identity and change metadata (inode, size, mtime, ctime) are
+ * captured before and after the read; a replacement or in-place change during the read is resolved with a
+ * strictly bounded coherent retry (the record inode is never pinned forever, so normal atomic store updates
+ * between calls are supported). Only a stable, coherent read is parsed, schema-validated (`isTaskRecord`)
+ * and identity-checked: `task_id`, `domain_id` (= `domainIdOf(domainRoot)`), `domain_root` and `task_root`
+ * must all equal the selected canonical root. An in-memory revision/digest floor rejects a lower
+ * `state_revision` (rollback) or different bytes at the same revision, and is NOT reset by a failed read
+ * (same revision + same bytes is repeatable). Any violation/read-failure/malformed result throws, which the
+ * guard turns into an explicit block; a fresh parsed object is returned and the floor/pinned identities are
+ * primitives, immune to outward mutation.
+ *
+ * Boundaries (explicit): rollback detection is for THIS runtime only — not durable restart fencing, and not
+ * authentication against arbitrary user-owned filesystem changes (explicit local-root trust boundary). The
+ * reader detects a change DURING its own read; there is still an UNAVOIDABLE check/use interval AFTER
+ * `read()` returns, before the tool actually runs. There is no filesystem lock, atomic global snapshot, OS
+ * write fence, native-stop proof, old-writer stop, transfer executor, automatic rollover, or installation
+ * here. No writes, locks, sidecars, watchers, timers, process/model/network/transcript calls, new authority
+ * store, or automatic recovery. The imported guard/store/validation APIs are read-only dependencies.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoundedFile } from '../../infra/bounded-file.js';
+import { RECORD_FILE, domainIdOf } from '../../collab/store.js';
+import { isTaskRecord } from '../../collab/validation.js';
+import { registerPiBootstrapGuard, } from './pi-bootstrap-guard.js';
+const TASKS_DIRNAME = 'tasks';
+const MAX_RECORD_BYTES = 8 * 1024 * 1024;
+const MAX_READ_ATTEMPTS = 8;
+const SAFE_TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function pinDirectory(dir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(dir);
+    }
+    catch {
+        throw new Error(`pi-bootstrap-runtime: required directory is missing: ${dir}`);
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`pi-bootstrap-runtime: path is not a real directory: ${dir}`);
+    return { dev: stat.dev, ino: stat.ino };
+}
+function recheckDirectory(dir, pinned) {
+    let stat;
+    try {
+        stat = fs.lstatSync(dir);
+    }
+    catch {
+        throw new Error(`pi-bootstrap-runtime: directory disappeared: ${dir}`);
+    }
+    if (stat.isSymbolicLink() ||
+        !stat.isDirectory() ||
+        stat.dev !== pinned.dev ||
+        stat.ino !== pinned.ino)
+        throw new Error(`pi-bootstrap-runtime: directory identity changed (redirect): ${dir}`);
+}
+function sameObservation(a, b) {
+    return (a.ino === b.ino &&
+        a.size === b.size &&
+        a.mtimeMs === b.mtimeMs &&
+        a.ctimeMs === b.ctimeMs);
+}
+class BoundedLocalReader {
+    #domainRoot;
+    #taskId;
+    #tasksDir;
+    #taskRoot;
+    #recordPath;
+    #expectedDomainId;
+    #domainIdentity;
+    #tasksIdentity;
+    #taskIdentity;
+    #floorRevision = null;
+    #floorDigest = null;
+    constructor(domainRoot, taskId) {
+        if (typeof domainRoot !== 'string' || !path.isAbsolute(domainRoot))
+            throw new RangeError('pi-bootstrap-runtime: domain root must be an absolute path');
+        if (typeof taskId !== 'string' || !SAFE_TASK_ID.test(taskId))
+            throw new RangeError('pi-bootstrap-runtime: task id must be a short safe identifier');
+        // Require a canonical root: a symlink anywhere in the prefix makes realpath differ from the input.
+        let canonical;
+        try {
+            canonical = fs.realpathSync(domainRoot);
+        }
+        catch {
+            throw new Error(`pi-bootstrap-runtime: domain root does not exist: ${domainRoot}`);
+        }
+        if (canonical !== domainRoot)
+            throw new RangeError('pi-bootstrap-runtime: domain root must be canonical (no symlink prefix or alias)');
+        this.#domainRoot = domainRoot;
+        this.#taskId = taskId;
+        this.#tasksDir = path.join(domainRoot, TASKS_DIRNAME);
+        this.#taskRoot = path.join(this.#tasksDir, taskId);
+        this.#recordPath = path.join(this.#taskRoot, RECORD_FILE);
+        this.#expectedDomainId = domainIdOf(domainRoot);
+        // Require existing directories and pin their identities once; never create them.
+        this.#domainIdentity = pinDirectory(this.#domainRoot);
+        this.#tasksIdentity = pinDirectory(this.#tasksDir);
+        this.#taskIdentity = pinDirectory(this.#taskRoot);
+    }
+    #recheckAncestors() {
+        recheckDirectory(this.#domainRoot, this.#domainIdentity);
+        recheckDirectory(this.#tasksDir, this.#tasksIdentity);
+        recheckDirectory(this.#taskRoot, this.#taskIdentity);
+    }
+    #observeRecordFile() {
+        try {
+            const stat = fs.lstatSync(this.#recordPath);
+            if (stat.isSymbolicLink() || !stat.isFile())
+                return null;
+            return {
+                ino: stat.ino,
+                size: stat.size,
+                mtimeMs: stat.mtimeMs,
+                ctimeMs: stat.ctimeMs,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    read() {
+        let lastReason = 'record unstable during read';
+        for (let attempt = 0; attempt < MAX_READ_ATTEMPTS; attempt += 1) {
+            // Pinned ancestors must still be the same real directories before the read.
+            this.#recheckAncestors();
+            const before = this.#observeRecordFile();
+            const result = readBoundedFile(this.#recordPath, MAX_RECORD_BYTES);
+            if (!result.ok)
+                throw new Error(`pi-bootstrap-runtime: record read failed (${result.code})`);
+            const after = this.#observeRecordFile();
+            // A pinned ancestor replaced DURING the read interval denies this call (namespace redirect).
+            this.#recheckAncestors();
+            // The record file replaced or changed in place during the read interval: bounded coherent retry.
+            if (before === null ||
+                after === null ||
+                !sameObservation(before, after)) {
+                lastReason = 'record changed during read';
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(result.text);
+            }
+            catch {
+                throw new Error('pi-bootstrap-runtime: record is not valid JSON');
+            }
+            if (!isTaskRecord(parsed))
+                throw new Error('pi-bootstrap-runtime: record failed schema validation');
+            const record = parsed;
+            // Complete task-domain identity against the selected canonical root (not just derived domain_id).
+            if (record.task_id !== this.#taskId)
+                throw new Error('pi-bootstrap-runtime: record task id mismatch');
+            if (record.domain_id !== this.#expectedDomainId)
+                throw new Error('pi-bootstrap-runtime: record domain id does not derive from the selected root');
+            if (record.domain_root !== this.#domainRoot)
+                throw new Error('pi-bootstrap-runtime: record domain_root does not match the selected root');
+            if (record.task_root !== this.#taskRoot)
+                throw new Error('pi-bootstrap-runtime: record task_root does not match the selected task');
+            const revision = record.state_revision;
+            if (typeof revision !== 'number' ||
+                !Number.isSafeInteger(revision) ||
+                revision < 0)
+                throw new Error('pi-bootstrap-runtime: record has an invalid state_revision');
+            const digest = result.digest;
+            if (this.#floorRevision !== null) {
+                if (revision < this.#floorRevision)
+                    throw new Error('pi-bootstrap-runtime: record state_revision rolled back');
+                if (revision === this.#floorRevision && digest !== this.#floorDigest)
+                    throw new Error('pi-bootstrap-runtime: record bytes changed at the same state_revision');
+            }
+            // Advance the floor only after a stable, coherent, validated read; a failure never resets it.
+            if (this.#floorRevision === null || revision > this.#floorRevision) {
+                this.#floorRevision = revision;
+                this.#floorDigest = digest;
+            }
+            // Fresh parsed data; the floor and pinned identities are primitives, immune to outward mutation.
+            return record;
+        }
+        throw new Error(`pi-bootstrap-runtime: ${lastReason} after ${MAX_READ_ATTEMPTS} attempts`);
+    }
+}
+/**
+ * Build the bounded local reader for an explicit canonical domain root + task id. Requires existing
+ * directories; never creates any. Exposed for focused testing and reuse.
+ */
+export function createLocalTaskRecordReader(domainRoot, taskId) {
+    return new BoundedLocalReader(domainRoot, taskId);
+}
+/**
+ * Register the opt-in successor bootstrap gate wired to the concrete local reader. Configuration is
+ * trusted host integration (never model input); the reader is built here (no caller-reader override). The
+ * `tool_call` gate is registered synchronously before any model work. Returns the guard's conservative
+ * status handle only — no allow/release surface.
+ */
+export function registerPiBootstrapRuntime(pi, config) {
+    if (typeof config !== 'object' || config === null)
+        throw new RangeError('pi-bootstrap-runtime: configuration is required');
+    if (config.taskId !== config.guard.taskId)
+        throw new RangeError('pi-bootstrap-runtime: runtime task id must equal the guard task id');
+    const reader = createLocalTaskRecordReader(config.domainRoot, config.taskId);
+    // registerPiBootstrapGuard copies/validates the pinned config; the reader is supplied here, not by a
+    // caller, and a reader throw/malformed result becomes the guard's explicit block.
+    return registerPiBootstrapGuard(pi, {
+        ...config.guard,
+        readRecord: () => reader.read(),
+    });
+}

package/dist/hosts/integration/pi-native-events.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 declare const PI_NATIVE_EVENTS_SCHEMA = "pappra/pi-native-events/1";
+/** The only installed callbacks this producer subscribes. Nothing else is observed. */
+export declare const SUPPORTED_CALLBACKS: readonly ["session_start", "before_agent_start", "agent_settled", "tool_execution_start", "tool_execution_end"];
+export type SupportedCallback = (typeof SUPPORTED_CALLBACKS)[number];
+/** Explicit, non-inferable facts: there is no supported extension API for either. */
+export type UnknownFact = 'unknown';
+/**
+ * Honest boundaries of these facts. Shared frozen; a snapshot exposes the same immutable array.
+ */
+export declare const NATIVE_EVENT_LIMITATIONS: readonly string[];
+/** A single subscribed callback handler, shaped like the installed `pi.on(event, handler)`. */
+export type PiNativeCallbackHandler = (event: unknown, context: unknown) => void;
+/** Narrow structural host: only `on` for the five supported callbacks is required. */
+export interface PiNativeEventHost {
+    on(event: SupportedCallback, handler: PiNativeCallbackHandler): void;
+}
+export interface NativeEventProducerOptions {
+    /** The native session expected at registration; every callback re-derives identity from context. */
+    readonly sessionId: string;
+    /** Bound on tracked open tool ids; exceeding it marks tracking unhealthy (default 4096). */
+    readonly maxTrackedTools?: number;
+    /** Sequence saturation bound; reaching it stops advancement to avoid a replayable wrap. */
+    readonly maxSequence?: number;
+    /** Bound on buffered/drained reentrant notifications; exceeding it is a delivery gap (default 1024). */
+    readonly maxNotifyQueue?: number;
+}
+/**
+ * An immutable snapshot of derived facts. `settled`/`idle` are tri-state: a boolean only when cleanly
+ * observed, else `'unknown'`. `observedOpenToolCount` is a local, non-authoritative observation; true
+ * in-flight completeness is never established, so it is reported as `inFlightCompleteness: 'unknown'`.
+ * Once `notificationBacklogOverflow` is set (a delivery gap), `settled` is forced to `'unknown'` and
+ * `toolTrackingHealthy` to `false` and stays so for every later snapshot.
+ */
+export interface NativeFactsSnapshot {
+    readonly schema: typeof PI_NATIVE_EVENTS_SCHEMA;
+    /** Last identity read from a callback context; trust it only when `sessionKnown` is true. */
+    readonly sessionId: string | null;
+    readonly sessionKnown: boolean;
+    readonly settled: boolean | UnknownFact;
+    readonly idle: boolean | UnknownFact;
+    /** Always `'unknown'`: no supported invariant establishes complete in-flight knowledge. */
+    readonly inFlightCompleteness: UnknownFact;
+    /** Count of tool ids observed open since the last clean session start; NOT a complete count. */
+    readonly observedOpenToolCount: number;
+    /**
+     * False after any duplicate start, unmatched end, malformed/oversized id, tracking overflow, an
+     * unknown-session interval, or a notification delivery gap. Only a native session change can reset the
+     * tool-tracking causes; a delivery gap keeps it false.
+     */
+    readonly toolTrackingHealthy: boolean;
+    readonly queue: UnknownFact;
+    readonly approvals: UnknownFact;
+    /** Never inferred from events; always false. */
+    readonly nativeStop: false;
+    /** Strictly increasing across every subscribed callback and session change until saturation. */
+    readonly sequence: number;
+    /** True once the sequence bound is reached; the sequence then stays fixed (no replayable wrap). */
+    readonly sequenceSaturated: boolean;
+    /** Sticky: true once notification delivery was lost; confidence is then permanently suspect. */
+    readonly notificationBacklogOverflow: boolean;
+    readonly limitations: readonly string[];
+}
+export interface NativeEventProducer {
+    /** Current derived facts as an immutable snapshot. Never fed blindly into a controller. */
+    snapshot(): NativeFactsSnapshot;
+    /** Subscribe to invalidation; fires in chronological order after every callback. Returns unsubscribe. */
+    onInvalidate(listener: (facts: NativeFactsSnapshot) => void): () => void;
+}
+/**
+ * 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 declare function registerPiNativeEvents(pi: PiNativeEventHost, options: NativeEventProducerOptions): NativeEventProducer;