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

package/dist/adapters/pi/recovery-extension.js

@@ -0,0 +1,238 @@
+// Pi recovery adapter: composes the opt-in recovery extension above `src/app`
+// and `src/hosts`.
+//
+// Loading this extension installs supported startup/settled/manual
+// reconciliation triggers that each run the durable recovery executor once per
+// observed trigger, gated by the ACTUAL host session (not a configuration
+// assertion) and deduplicated by the executor's durable canonical cause. It does
+// not touch the accepted observation-only native-event producer, never spawns a
+// session or a hidden daemon, never polls for model/worker completion, and never
+// answers approval automatically. There is no known reconnect event: if no
+// supported trigger fires, nothing is reconciled, and a missing host observation
+// stays explicit rather than being manufactured to unblock an enqueue. An initial
+// no-op does not suppress a later genuine cause, and recovery's own settled event
+// cannot re-issue an already-reserved cause (no self-loop).
+//
+// Composition lives here rather than in `src/hosts/integration`: the host layer
+// must not depend on application orchestration. The configuration format is owned
+// by the lower-layer reader re-exported below, so bundle export inside `src/hosts`
+// validates the same bytes without reaching this module.
+import { fileURLToPath } from 'node:url';
+import { createHerdrRecoveryController, executeRecovery, } from '../../app/collab-recovery-executor.js';
+import { readPiRecoveryConfig, } from '../../hosts/integration/recovery-config.js';
+export { PI_RECOVERY_CONFIG_SCHEMA, readPiRecoveryConfig, } from '../../hosts/integration/recovery-config.js';
+export const PI_RECOVERY_STATUS_SCHEMA = 'pappra/pi-recovery-status/1';
+const LIMITATIONS = Object.freeze([
+    'opt_in_explicit_configuration_only_no_ambient_task_discovery',
+    'actual_host_session_gated_not_a_configuration_assertion',
+    'no_known_reconnect_event_missing_observation_stays_explicit',
+    'cause_aware_durable_dedup_prevents_self_wake_loops',
+    'no_new_session_hidden_daemon_completion_poll_or_approval_auto',
+    'submission_or_queue_acceptance_is_not_consumption_or_completion',
+]);
+/**
+ * Build a single-flight reconciler. Every supported trigger may run; a reconcile never overlaps another.
+ * The ACTUAL observed host session must match the configured expected session before any work — a config
+ * loaded in a foreign session is skipped. Re-issuing the same cause is prevented durably by the executor's
+ * canonical-cause reservation, so a later new cause can still progress while recovery's own settled event
+ * cannot repeatedly wake itself.
+ */
+export function createRecoveryReconciler(config, deps, configDigest = null) {
+    const execute = deps.execute ?? executeRecovery;
+    const expectedSession = {
+        session_id: config.expected.session_id,
+        cwd: config.expected.cwd,
+        binding_digest: config.expected.binding_digest,
+        binding_ref: config.expected.binding_ref,
+        target_agent: config.target.agent,
+        pane_id: config.expected.pane_id,
+        harness: config.expected.harness,
+    };
+    const issued = new Set();
+    let reconcileCount = 0;
+    let running = false;
+    let last = null;
+    const record = (outcome) => {
+        last = outcome;
+        return outcome;
+    };
+    return {
+        async reconcile(trigger, hostFacts) {
+            if (running)
+                return record({
+                    trigger,
+                    skipped: true,
+                    reason: 'a reconciliation is already in progress; not overlapping.',
+                });
+            if (hostFacts === null)
+                return record({
+                    trigger,
+                    skipped: true,
+                    reason: 'the actual host session could not be observed; refusing to reconcile without host evidence.',
+                });
+            if (hostFacts.session_id !== config.expected.session_id)
+                return record({
+                    trigger,
+                    skipped: true,
+                    reason: 'the actual host session does not match the configured expected session; refusing to reconcile.',
+                });
+            if (hostFacts.cwd !== config.expected.cwd)
+                return record({
+                    trigger,
+                    skipped: true,
+                    reason: 'the actual host cwd does not match the configured expected cwd; refusing to reconcile.',
+                });
+            running = true;
+            try {
+                const result = await execute({
+                    taskRoot: config.taskRoot,
+                    planFile: config.planFile,
+                    self: config.self,
+                    policy: config.policy,
+                    requestId: config.requestId,
+                    mode: config.mode,
+                    expectedSession,
+                }, {
+                    controller: deps.controller,
+                    ...(deps.now ? { now: deps.now } : {}),
+                    ...(deps.sleep ? { sleep: deps.sleep } : {}),
+                });
+                reconcileCount += 1;
+                if (result.reservation &&
+                    (result.status === 'applied' || result.status === 'deferred'))
+                    issued.add(result.reservation.key);
+                return record({ trigger, skipped: false, result });
+            }
+            finally {
+                running = false;
+            }
+        },
+        status() {
+            return {
+                schema: PI_RECOVERY_STATUS_SCHEMA,
+                registered: true,
+                mode: config.mode,
+                task_root: config.taskRoot,
+                config_digest: configDigest,
+                reconcile_count: reconcileCount,
+                issued_causes: [...issued],
+                last,
+                limitations: LIMITATIONS,
+            };
+        },
+    };
+}
+const MAX_HOST_ID_LENGTH = 512;
+function isSafeHostId(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= MAX_HOST_ID_LENGTH);
+}
+/**
+ * Pinned installed Pi API (matching the accepted native-event producer): the running session id is read
+ * from `ctx.sessionManager.getSessionId()` with its receiver preserved. Any throwing/missing/invalid access
+ * stays null. This is the supported host shape, not a fabricated event field.
+ */
+function readHostSessionId(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 isSafeHostId(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Pinned installed Pi API: the working directory is `ctx.cwd`. A throw or non-string stays null. */
+function readHostCwd(context) {
+    try {
+        if (typeof context !== 'object' || context === null)
+            return null;
+        const value = context.cwd;
+        return typeof value === 'string' && value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Observe genuine host facts from the supported installed Pi context
+ * (`ctx.sessionManager.getSessionId()` and `ctx.cwd`). Returns null when no actual session can be read, so
+ * a missing observation stays explicit and is never synthesized.
+ */
+export function observeHostFacts(event, context) {
+    void event;
+    const session_id = readHostSessionId(context);
+    if (session_id === null)
+        return null;
+    return { session_id, cwd: readHostCwd(context) };
+}
+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('./recovery.json', import.meta.url));
+}
+/**
+ * Opt-in extension entry. Loads the sibling `recovery.json`, builds a live-target-verifying Herdr
+ * controller for `apply` mode (a no-op controller for `plan` mode, which never issues an effect), and
+ * installs startup/settled triggers plus a manual `pappra-recovery` command. Each trigger observes the
+ * ACTUAL host session and reconciles through the durable, cause-deduplicated executor. A load or validation
+ * failure disables reconciliation and reports it through the status command; it never throws into the
+ * loader and never substitutes a hidden fresh Pi process for the visible workflow.
+ */
+export default function recoveryExtension(pi) {
+    const host = pi;
+    const load = readPiRecoveryConfig(configPath());
+    if (!load.ok) {
+        host.registerCommand('pappra-recovery', {
+            description: 'Opt-in recovery reconciliation (disabled: config not loaded).',
+            handler: (_args, context) => {
+                notify(context, JSON.stringify({
+                    schema: PI_RECOVERY_STATUS_SCHEMA,
+                    registered: false,
+                    reason: `${load.code}`,
+                    limitations: LIMITATIONS,
+                }));
+            },
+        });
+        return;
+    }
+    const controller = load.config.mode === 'apply'
+        ? createHerdrRecoveryController({ env: process.env }, { agent: load.config.target.agent })
+        : {
+            id: 'recovery-plan-noop',
+            perform: async () => ({
+                disposition: 'unknown',
+                detail: 'plan mode issues no effect',
+                observation: 'none',
+            }),
+        };
+    const reconciler = createRecoveryReconciler(load.config, { controller }, load.digest);
+    const run = async (trigger, event, context) => {
+        const facts = observeHostFacts(event, context);
+        const outcome = await reconciler.reconcile(trigger, facts);
+        notify(context, JSON.stringify(outcome));
+    };
+    host.on('session_start', (event, context) => run('session_start', event, context));
+    host.on('agent_settled', (event, context) => run('agent_settled', event, context));
+    host.registerCommand('pappra-recovery', {
+        description: 'Reconcile durable recovery for the configured task (plan or apply per config).',
+        handler: (_args, context) => run('manual', null, context),
+    });
+}

package/dist/adapters/pi/session-transition-extension.d.ts

@@ -0,0 +1,30 @@
+import { type SessionTransitionHost } from '../../app/collab-session-transition.js';
+import { type NativeEventProducer } from '../../hosts/integration/pi-native-events.js';
+import { type RolloverFreezeController } from '../../hosts/integration/pi-rollover-extension.js';
+export declare const PI_SESSION_TRANSITION_EXTENSION_ID = "pappra/pi-session-transition-host/1";
+export declare const PI_SESSION_TRANSITION_LIMITATIONS: readonly string[];
+export interface PiSessionTransitionContext {
+    readonly cwd?: unknown;
+    readonly sessionManager?: unknown;
+    readonly ui?: unknown;
+}
+interface PiSessionTransitionHostState {
+    readonly host: SessionTransitionHost;
+    readonly controller: RolloverFreezeController;
+    readonly producer: NativeEventProducer;
+    readonly sessionId: string;
+    readonly cwd: string;
+}
+/**
+ * Build the opt-in in-process host adapter from one exact Pi command context. The adapter reports
+ * native quiescence as unavailable: supported Pi events cannot provide a complete queue/approval/
+ * external-writer inventory or authenticated native stop receipt. Its freeze method is retained
+ * only as the existing managed-tool barrier and is never promoted to stop proof.
+ */
+export declare function createPiSessionTransitionHost(pi: unknown, context: unknown, env?: NodeJS.ProcessEnv): PiSessionTransitionHostState | null;
+/**
+ * Explicit Pi extension entry. Loading registers one command; it does not start a successor,
+ * mutate settings, query a model, send a prompt or claim that the host has stop-proof capability.
+ */
+export default function piSessionTransitionExtension(pi: unknown): void;
+export {};

package/dist/adapters/pi/session-transition-extension.js

@@ -0,0 +1,265 @@
+// Pi session-transition adapter: composes the opt-in transition extension above
+// `src/app` and `src/hosts`.
+//
+// The native observation and freeze primitives stay in `src/hosts/integration`;
+// only the orchestration composition and its application imports live here, so
+// the host layer keeps no application dependency.
+import { object as isRecord } from '../../infra/validation.js';
+import path from 'node:path';
+import { loadSessionTransitionRequest, planSessionTransition, applySessionTransition, } from '../../app/collab-session-transition.js';
+import { registerPiNativeEvents, } from '../../hosts/integration/pi-native-events.js';
+import { registerPiRolloverFreeze, } from '../../hosts/integration/pi-rollover-extension.js';
+export const PI_SESSION_TRANSITION_EXTENSION_ID = 'pappra/pi-session-transition-host/1';
+export const PI_SESSION_TRANSITION_LIMITATIONS = Object.freeze([
+    'no_supported_complete_native_message_queue_or_pending_approval_inventory',
+    'pi_native_event_in_flight_tracking_is_incomplete_and_never_proves_writer_stop',
+    'managed_tool_freeze_is_not_native_process_or_external_writer_stop_proof',
+    'herdr_session_metadata_is_not_process_affiliation',
+    'native_pi_session_archive_is_unavailable',
+]);
+function contextSessionId(context) {
+    try {
+        if (!isRecord(context) || !isRecord(context['sessionManager']))
+            return null;
+        const manager = context['sessionManager'];
+        const getter = manager['getSessionId'];
+        if (typeof getter !== 'function')
+            return null;
+        const value = getter.call(manager);
+        return typeof value === 'string' && value.length > 0 && value.length <= 256
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function contextCwd(context) {
+    if (!isRecord(context))
+        return null;
+    const value = context['cwd'];
+    return typeof value === 'string' &&
+        path.isAbsolute(value) &&
+        value.length <= 4096
+        ? value
+        : null;
+}
+function paneFromEnvironment(env = process.env) {
+    const value = env['HERDR_PANE_ID'];
+    return typeof value === 'string' && /^[A-Za-z0-9]+:p[A-Za-z0-9]+$/.test(value)
+        ? value
+        : null;
+}
+function freezeFailure(token, sessionId) {
+    return {
+        ok: false,
+        reason: token.sessionId === sessionId ? 'conflicting_freeze' : 'wrong_session',
+        detail: 'The Pi session-transition adapter does not authorize native stop or ownership transfer.',
+    };
+}
+/**
+ * Build the opt-in in-process host adapter from one exact Pi command context. The adapter reports
+ * native quiescence as unavailable: supported Pi events cannot provide a complete queue/approval/
+ * external-writer inventory or authenticated native stop receipt. Its freeze method is retained
+ * only as the existing managed-tool barrier and is never promoted to stop proof.
+ */
+export function createPiSessionTransitionHost(pi, context, env = process.env) {
+    const sessionId = contextSessionId(context);
+    const cwd = contextCwd(context);
+    if (sessionId === null || cwd === null)
+        return null;
+    const controller = registerPiRolloverFreeze(pi, {
+        sessionId,
+    });
+    const producer = registerPiNativeEvents(pi, {
+        sessionId,
+    });
+    const host = {
+        id: PI_SESSION_TRANSITION_EXTENSION_ID,
+        async observe() {
+            const currentSession = contextSessionId(context);
+            const currentCwd = contextCwd(context);
+            const status = controller.status();
+            const facts = producer.snapshot();
+            return {
+                session_id: currentSession,
+                cwd: currentCwd,
+                pane_id: paneFromEnvironment(env),
+                proof_support: 'unavailable',
+                proof: null,
+                freeze_status: status,
+                native_facts: facts,
+                unavailable_code: 'pi_native_quiescence_proof_unavailable',
+                detail: 'Installed Pi events expose only advisory idle/settled and incomplete in-flight observations. Complete queued messages, approvals, external writers and authenticated native stop are unsupported; a managed freeze latch is not quiescence proof.',
+            };
+        },
+        async freeze(token) {
+            const currentSession = contextSessionId(context);
+            if (currentSession !== sessionId || currentSession !== token.sessionId)
+                return freezeFailure(token, currentSession ?? '');
+            return controller.freeze(token);
+        },
+    };
+    return { host, controller, producer, sessionId, cwd };
+}
+function tokenizeCommandArgs(input) {
+    if (input.length > 8192 || input.includes('\u0000'))
+        return null;
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let escaped = false;
+    let started = false;
+    for (const char of input) {
+        if (escaped) {
+            current += char;
+            escaped = false;
+            started = true;
+            continue;
+        }
+        if (char === '\\' && quote !== 'single') {
+            escaped = true;
+            started = true;
+            continue;
+        }
+        if (quote === null && char === "'") {
+            quote = 'single';
+            started = true;
+            continue;
+        }
+        if (quote === 'single' && char === "'") {
+            quote = null;
+            continue;
+        }
+        if (quote === null && char === '"') {
+            quote = 'double';
+            started = true;
+            continue;
+        }
+        if (quote === 'double' && char === '"') {
+            quote = null;
+            continue;
+        }
+        if (quote === null && /\s/.test(char)) {
+            if (started)
+                tokens.push(current);
+            current = '';
+            started = false;
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (escaped || quote !== null)
+        return null;
+    if (started)
+        tokens.push(current);
+    return tokens;
+}
+function parseExtensionCommand(input) {
+    const tokens = tokenizeCommandArgs(input);
+    if (tokens === null)
+        return {
+            ok: false,
+            message: 'Arguments must be balanced and contain no NUL bytes.',
+        };
+    const action = tokens[0];
+    const requestFile = tokens.length === 2
+        ? tokens[1]
+        : tokens.length === 3 && tokens[1] === '--request'
+            ? tokens[2]
+            : undefined;
+    if ((action !== 'plan' && action !== 'apply') ||
+        requestFile === undefined ||
+        !path.isAbsolute(requestFile))
+        return {
+            ok: false,
+            message: 'Use /collab-transition <plan|apply> <absolute-request.json> (or --request <absolute-request.json>).',
+        };
+    return { ok: true, action, requestFile };
+}
+function notify(context, message, level = 'info') {
+    if (!isRecord(context) || !isRecord(context['ui']))
+        return;
+    const ui = context['ui'];
+    const method = ui['notify'];
+    if (typeof method !== 'function')
+        return;
+    try {
+        method.call(ui, message, level);
+    }
+    catch {
+        // A UI notification is diagnostic only and never changes transition state.
+    }
+}
+function summaryLine(report) {
+    return [
+        `pappra transition ${report.status}${report.code === null ? '' : ` (${report.code})`}: ${report.stage}.`,
+        report.next_action,
+    ]
+        .filter((part) => part !== null)
+        .join(' ');
+}
+/**
+ * Explicit Pi extension entry. Loading registers one command; it does not start a successor,
+ * mutate settings, query a model, send a prompt or claim that the host has stop-proof capability.
+ */
+export default function piSessionTransitionExtension(pi) {
+    const commandHost = pi;
+    let runtime = null;
+    let rejectedSessionChange = false;
+    commandHost.registerCommand('collab-transition', {
+        description: 'Plan/apply one guarded collaboration transition. Native quiescence is blocked unless an accepted proof API exists.',
+        handler: async (args, context) => {
+            const parsed = parseExtensionCommand(args);
+            if (!parsed.ok) {
+                notify(context, parsed.message, 'warning');
+                return;
+            }
+            const sessionId = contextSessionId(context);
+            const cwd = contextCwd(context);
+            if (sessionId === null || cwd === null) {
+                notify(context, 'Pi transition requires an exact live session id and absolute cwd.', 'warning');
+                return;
+            }
+            if (runtime === null) {
+                try {
+                    runtime = createPiSessionTransitionHost(pi, context);
+                }
+                catch {
+                    notify(context, 'Pi transition host registration failed; reconcile the extension load before retrying.', 'warning');
+                    return;
+                }
+                if (runtime === null) {
+                    notify(context, 'Pi transition host could not bind the current session/cwd.', 'warning');
+                    return;
+                }
+            }
+            else if (runtime.sessionId !== sessionId || runtime.cwd !== cwd) {
+                rejectedSessionChange = true;
+                notify(context, 'Pi transition host identity changed; reload in the exact source session before continuing.', 'warning');
+                return;
+            }
+            if (rejectedSessionChange) {
+                notify(context, 'Pi transition host remains blocked after a session identity change.', 'warning');
+                return;
+            }
+            const loaded = loadSessionTransitionRequest(parsed.requestFile);
+            if (!loaded.ok) {
+                notify(context, `${loaded.code}: ${loaded.message}`, 'warning');
+                return;
+            }
+            try {
+                const report = parsed.action === 'plan'
+                    ? await planSessionTransition(loaded.value, { host: runtime.host })
+                    : await applySessionTransition(loaded.value, {
+                        host: runtime.host,
+                    });
+                notify(context, summaryLine(report), report.ok ? 'info' : 'warning');
+            }
+            catch {
+                notify(context, 'Transition execution returned an unknown outcome; inspect the task journal and host state before resuming.', 'warning');
+            }
+        },
+    });
+}

package/dist/app/automatic-handoff-events.d.ts

@@ -0,0 +1,26 @@
+import { type AutomaticHandoffConfig, type AutomaticHandoffRuntime, type AutomaticHandoffResult } from './collab-auto-handoff.js';
+import type { SessionTransitionDependencies } from './collab-session-transition.js';
+export declare function loadAutomaticHandoffConfig(file: string): AutomaticHandoffConfig;
+/** A native settled event or registered task update advances one guarded transition. */
+export declare function watchAutomaticHandoff(config: AutomaticHandoffConfig, runtime: AutomaticHandoffRuntime & {
+    subscribe(listener: (event: unknown) => void): () => void;
+}, dependencies?: SessionTransitionDependencies, onRetirement?: (result: AutomaticHandoffResult) => Promise<void>): {
+    refresh: () => Promise<void>;
+    completed: Promise<{
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly code: string;
+    }>;
+    status: () => {
+        result: AutomaticHandoffResult | null;
+        error: string | null;
+        completion: ({
+            readonly ok: true;
+        } | {
+            readonly ok: false;
+            readonly code: string;
+        }) | null;
+    };
+    close(): void;
+};