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

package/dist/app/managed-pi-native-observation.js

@@ -0,0 +1,191 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoundedFile } from './bounded-file.js';
+import { openTaskStore, assertTaskStoreCurrent } from './collab-task-store.js';
+import { requestManagedPiControl } from '../hosts/pi/managed-session.js';
+import { managedPiSocketPeerPid } from './managed-pi-repair-stop.js';
+const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Fresh authenticated SDK facts plus OS/pane ownership; never infer native identity from a title. */
+export async function observeOwnedManagedPi(descriptorFile, expected, deps) {
+    try {
+        const stat = fs.lstatSync(descriptorFile);
+        const bytes = readBoundedFile(descriptorFile, 4096);
+        if (!bytes.ok || (stat.mode & 0o077) !== 0 || stat.isSymbolicLink())
+            return null;
+        const descriptor = JSON.parse(bytes.text);
+        if (!object(descriptor) ||
+            descriptor.sessionId !== expected.sessionId ||
+            typeof descriptor.socketPath !== 'string' ||
+            typeof descriptor.runId !== 'string' ||
+            (expected.runId !== undefined && descriptor.runId !== expected.runId))
+            return null;
+        const peer = (deps.peerPid ?? managedPiSocketPeerPid)(descriptor.socketPath);
+        if (peer === null || (expected.pid !== undefined && peer !== expected.pid))
+            return null;
+        const response = await (deps.control ?? requestManagedPiControl)(descriptorFile, 'snapshot');
+        if (response.ok !== true ||
+            !object(response.snapshot) ||
+            !object(response.snapshot.session) ||
+            !object(response.snapshot.process) ||
+            !object(response.automation) ||
+            !object(response.automation.launch))
+            return null;
+        const launch = response.automation.launch;
+        const scope = response.automation.execution_scope;
+        if (expected.taskRoot &&
+            !(object(scope) &&
+                scope.task_root === expected.taskRoot &&
+                scope.session_id === expected.sessionId) &&
+            !(launch.bootstrap_task_root === expected.taskRoot &&
+                expected.bootstrapDigest !== undefined &&
+                launch.bootstrap_config_digest === expected.bootstrapDigest) &&
+            !(launch.initial_task_root === expected.taskRoot &&
+                expected.initialAdmissionDigest !== undefined &&
+                launch.initial_admission_digest === expected.initialAdmissionDigest))
+            return null;
+        if (launch.ready !== true ||
+            launch.runtime !== 'sdk' ||
+            launch.session_id !== expected.sessionId ||
+            response.snapshot.session.sessionId !== expected.sessionId ||
+            response.snapshot.process.pid !== peer ||
+            launch.controller_run_id !== descriptor.runId ||
+            launch.cwd !== expected.cwd ||
+            launch.herdr_pane_id !== expected.paneId ||
+            typeof launch.herdr_agent_name !== 'string' ||
+            (expected.name !== undefined &&
+                launch.herdr_agent_name !== expected.name) ||
+            !object(launch.model) ||
+            launch.model.provider !== 'openrouter' ||
+            typeof launch.model.id !== 'string')
+            return null;
+        const observed = await deps.run('herdr', ['pane', 'process-info', '--pane', expected.paneId], 5000);
+        if (!observed.spawned || observed.code !== 0 || observed.timedOut)
+            return null;
+        const parsed = JSON.parse(observed.stdout);
+        const info = object(parsed) && object(parsed.result)
+            ? parsed.result.process_info
+            : null;
+        if (!object(info) ||
+            info.pane_id !== expected.paneId ||
+            !Array.isArray(info.foreground_processes) ||
+            !info.foreground_processes.some((row) => object(row) && row.pid === peer))
+            return null;
+        const current = readBoundedFile(descriptorFile, 4096);
+        if (!current.ok || current.digest !== bytes.digest)
+            return null;
+        return {
+            descriptorFile,
+            sessionId: expected.sessionId,
+            cwd: expected.cwd,
+            paneId: expected.paneId,
+            name: launch.herdr_agent_name,
+            pid: peer,
+            provider: 'openrouter',
+            model: launch.model.id,
+            provenance: 'owned-pi-sdk-control',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve only task-registered runtimes or this task's reserved managed launch. */
+export async function resolveTaskManagedPi(taskRoot, pane, deps) {
+    if (!pane.paneId || !pane.cwd)
+        return null;
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok || (await assertTaskStoreCurrent(opened.value)))
+        return null;
+    const candidates = [];
+    const initialLaunches = opened.value.record.managed_pi_initial_launches;
+    if (Array.isArray(initialLaunches) && initialLaunches.length <= 64) {
+        for (const row of initialLaunches) {
+            if (!object(row) ||
+                row.schema !== 'pappra/managed-pi-initial-launch/1' ||
+                row.pane_id !== pane.paneId ||
+                typeof row.descriptor_file !== 'string' ||
+                typeof row.session_id !== 'string' ||
+                typeof row.pid !== 'number' ||
+                typeof row.controller_run_id !== 'string' ||
+                typeof row.admission_digest !== 'string')
+                continue;
+            candidates.push({
+                file: row.descriptor_file,
+                sessionId: row.session_id,
+                pid: row.pid,
+                runId: row.controller_run_id,
+                initialAdmissionDigest: row.admission_digest,
+            });
+        }
+    }
+    const registry = opened.value.record.managed_pi_runtime_registry;
+    if (Array.isArray(registry) && registry.length <= 64) {
+        for (const row of registry) {
+            if (!object(row) ||
+                (row.pane_id != null && row.pane_id !== pane.paneId) ||
+                typeof row.descriptor_file !== 'string' ||
+                typeof row.session_id !== 'string' ||
+                typeof row.pid !== 'number' ||
+                typeof row.controller_run_id !== 'string')
+                continue;
+            candidates.push({
+                file: row.descriptor_file,
+                sessionId: row.session_id,
+                pid: row.pid,
+                runId: row.controller_run_id,
+            });
+        }
+    }
+    for (const row of opened.value.record.launch_reservations ?? []) {
+        const bootstrap = row
+            .bootstrap;
+        if (!object(bootstrap) ||
+            typeof bootstrap.request_file !== 'string' ||
+            typeof bootstrap.request_digest !== 'string')
+            continue;
+        const requestBytes = readBoundedFile(bootstrap.request_file, 64 * 1024);
+        if (!requestBytes.ok || requestBytes.digest !== bootstrap.request_digest)
+            continue;
+        let request;
+        try {
+            request = JSON.parse(requestBytes.text);
+        }
+        catch {
+            continue;
+        }
+        if (!object(request) ||
+            request.task_root !== taskRoot ||
+            !object(request.managed_runtime) ||
+            !object(request.participant) ||
+            typeof request.participant.native_session_selector !== 'string' ||
+            typeof request.managed_runtime.journal_path !== 'string' ||
+            !object(request.bootstrap) ||
+            typeof request.bootstrap.config_digest !== 'string' ||
+            (pane.name !== undefined &&
+                pane.name !== null &&
+                bootstrap.herdr_agent !== pane.name))
+            continue;
+        candidates.push({
+            file: `${request.managed_runtime.journal_path}.control.json`,
+            sessionId: request.participant.native_session_selector,
+            bootstrapDigest: request.bootstrap.config_digest,
+        });
+    }
+    const found = new Map();
+    for (const candidate of candidates) {
+        if (!path.isAbsolute(candidate.file))
+            continue;
+        const observed = await observeOwnedManagedPi(candidate.file, {
+            ...candidate,
+            cwd: pane.cwd,
+            paneId: pane.paneId,
+            taskRoot,
+            ...(pane.name ? { name: pane.name } : {}),
+        }, deps);
+        if (observed)
+            found.set(observed.sessionId, observed);
+    }
+    if (found.size !== 1 || (await assertTaskStoreCurrent(opened.value)))
+        return null;
+    return [...found.values()][0] ?? null;
+}

package/dist/app/managed-pi-readiness.d.ts

@@ -0,0 +1,29 @@
+export interface ManagedPiReadinessConfig {
+    readonly assignmentFile: string;
+    readonly templateFile: string;
+    readonly cardFile: string;
+}
+export interface ManagedPiReadinessSource {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly metadataFile: string;
+    readonly expectedProvider?: string;
+    readonly expectedModel?: string;
+}
+export interface ManagedPiReadinessDependencies {
+    readonly beforeRefresh?: () => Promise<void>;
+}
+export interface ManagedPiReadinessResult {
+    readonly status: 'waiting' | 'published' | 'unchanged' | 'blocked';
+    readonly code: string;
+    readonly cardFile: string;
+    readonly preflight: string | null;
+}
+/** Publish startup capabilities only from a matching native resources_ready observation. */
+export declare function publishManagedPiReadiness(config: ManagedPiReadinessConfig, source: ManagedPiReadinessSource): ManagedPiReadinessResult;
+/** Watch only explicit native/config inputs. No timer, model prompt or completion polling. */
+export declare function watchManagedPiReadiness(config: ManagedPiReadinessConfig, source: ManagedPiReadinessSource, onResult?: (result: ManagedPiReadinessResult) => void, dependencies?: ManagedPiReadinessDependencies): {
+    refresh: (force?: boolean) => Promise<void>;
+    status: () => ManagedPiReadinessResult | null;
+    close: () => Promise<void>;
+};

package/dist/app/managed-pi-readiness.js

@@ -0,0 +1,288 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { derivePiStartupCard } from './capability-evidence/pi.js';
+import { readBoundedFile } from './bounded-file.js';
+import { runCollaborationPreflight } from './collab-preflight.js';
+import { isAssignment, isCard } from '../collab/contracts.js';
+import { samePath } from './capability-evidence/shared.js';
+function pinDirectory(directory) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        fs.realpathSync(directory) !== directory)
+        throw new Error('readiness_directory_redirected');
+    return { dev: stat.dev, ino: stat.ino };
+}
+/** Publish startup capabilities only from a matching native resources_ready observation. */
+export function publishManagedPiReadiness(config, source) {
+    const result = (status, code, preflight = null) => ({
+        status,
+        code,
+        cardFile: config.cardFile,
+        preflight,
+    });
+    let temporary = null;
+    try {
+        const files = [
+            config.assignmentFile,
+            config.templateFile,
+            config.cardFile,
+            source.metadataFile,
+        ];
+        if (files.some((file) => !path.isAbsolute(file)))
+            return result('blocked', 'readiness_path_not_absolute');
+        if (!source.sessionId || !path.isAbsolute(source.cwd))
+            return result('waiting', 'readiness_source_identity_missing');
+        if ([config.assignmentFile, config.templateFile, source.metadataFile].some((file) => path.resolve(file) === path.resolve(config.cardFile)))
+            return result('blocked', 'readiness_input_output_conflict');
+        const directory = path.dirname(config.cardFile);
+        const parent = pinDirectory(directory);
+        const assignmentRead = readBoundedFile(config.assignmentFile, 1024 * 1024);
+        if (!assignmentRead.ok)
+            return result(assignmentRead.code === 'unreadable' ? 'waiting' : 'blocked', `readiness_assignment_${assignmentRead.code}`);
+        const templateRead = readBoundedFile(config.templateFile, 1024 * 1024);
+        if (!templateRead.ok)
+            return result(templateRead.code === 'unreadable' ? 'waiting' : 'blocked', `readiness_template_${templateRead.code}`);
+        let assignment;
+        let template;
+        try {
+            assignment = JSON.parse(assignmentRead.text);
+            template = JSON.parse(templateRead.text);
+        }
+        catch {
+            return result('waiting', 'readiness_configuration_invalid');
+        }
+        if (!isAssignment(assignment) || !isCard(template))
+            return result('waiting', 'readiness_configuration_invalid');
+        const derived = derivePiStartupCard({
+            assignment,
+            template,
+            metadataFile: source.metadataFile,
+            sessionId: source.sessionId,
+            cwd: source.cwd,
+            ...(source.expectedProvider === undefined
+                ? {}
+                : { expectedProvider: source.expectedProvider }),
+            ...(source.expectedModel === undefined
+                ? {}
+                : { expectedModel: source.expectedModel }),
+        });
+        if (derived.status !== 'derived')
+            return result('waiting', derived.blockers[0] ?? 'native_card_unavailable');
+        if (derived.card.session_id !== source.sessionId ||
+            !samePath(derived.card.cwd, source.cwd))
+            return result('waiting', 'readiness_source_identity_mismatch');
+        const bytes = Buffer.from(`${JSON.stringify(derived.card, null, 2)}\n`);
+        const existing = fs.lstatSync(config.cardFile, { throwIfNoEntry: false });
+        if (existing) {
+            const prior = readBoundedFile(config.cardFile, 1024 * 1024);
+            if (!prior.ok)
+                return result('blocked', 'readiness_card_target_unsafe');
+            const card = JSON.parse(prior.text);
+            if (!isCard(card) ||
+                card.session_id !== source.sessionId ||
+                !samePath(card.cwd, source.cwd))
+                return result('blocked', 'readiness_card_target_foreign');
+            if (prior.bytes.equals(bytes)) {
+                const preflight = runCollaborationPreflight({
+                    assignmentFile: config.assignmentFile,
+                    capabilitiesFile: config.cardFile,
+                });
+                return result('unchanged', 'native_card_unchanged', preflight.status);
+            }
+        }
+        const current = pinDirectory(directory);
+        if (current.dev !== parent.dev || current.ino !== parent.ino)
+            return result('blocked', 'readiness_directory_changed');
+        temporary = path.join(directory, `.pappra-readiness-${crypto.randomUUID()}.tmp`);
+        const fd = fs.openSync(temporary, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, bytes);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const beforePublish = pinDirectory(directory);
+        if (beforePublish.dev !== parent.dev || beforePublish.ino !== parent.ino)
+            return result('blocked', 'readiness_directory_changed');
+        fs.renameSync(temporary, config.cardFile);
+        temporary = null;
+        const preflight = runCollaborationPreflight({
+            assignmentFile: config.assignmentFile,
+            capabilitiesFile: config.cardFile,
+        });
+        return result('published', 'native_card_published', preflight.status);
+    }
+    catch {
+        return result('blocked', 'readiness_publication_failed');
+    }
+    finally {
+        if (temporary !== null) {
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch {
+                /* only this call's temporary file */
+            }
+        }
+    }
+}
+/** Watch only explicit native/config inputs. No timer, model prompt or completion polling. */
+export function watchManagedPiReadiness(config, source, onResult = () => { }, dependencies = {}) {
+    const inputs = [
+        source.metadataFile,
+        config.assignmentFile,
+        config.templateFile,
+    ];
+    const directories = new Map();
+    const pins = new Map();
+    for (const file of inputs) {
+        if (!path.isAbsolute(file))
+            throw new Error('readiness_path_not_absolute');
+        const directory = path.dirname(file);
+        pins.set(directory, pinDirectory(directory));
+        const names = directories.get(directory) ?? new Set();
+        names.add(path.basename(file));
+        directories.set(directory, names);
+    }
+    let last = null;
+    let lastCause = null;
+    let closed = false;
+    let pending = false;
+    let forcePending = false;
+    let active = null;
+    const watchers = [];
+    const notify = (result) => {
+        try {
+            onResult(result);
+        }
+        catch {
+            /* Observers do not interrupt native lifecycle handling. */
+        }
+    };
+    const inputCause = () => {
+        const hash = crypto.createHash('sha256');
+        for (const file of inputs) {
+            const read = readBoundedFile(file, file === source.metadataFile ? 16 * 1024 * 1024 : 1024 * 1024);
+            hash.update(read.ok ? read.digest : `error:${read.code}`);
+            hash.update('\0');
+        }
+        return hash.digest('hex');
+    };
+    const directoriesCurrent = () => {
+        for (const [directory, pin] of pins) {
+            try {
+                const current = pinDirectory(directory);
+                if (current.dev !== pin.dev || current.ino !== pin.ino)
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    };
+    const refresh = (force = false) => {
+        if (closed)
+            return active ?? Promise.resolve();
+        pending = true;
+        forcePending ||= force;
+        if (active)
+            return active;
+        active = (async () => {
+            while (pending && !closed) {
+                pending = false;
+                const forced = forcePending;
+                forcePending = false;
+                if (!directoriesCurrent()) {
+                    last = {
+                        status: 'blocked',
+                        code: 'readiness_directory_changed',
+                        cardFile: config.cardFile,
+                        preflight: null,
+                    };
+                    notify(last);
+                    continue;
+                }
+                const beforeRefreshCause = inputCause();
+                if (!forced && beforeRefreshCause === lastCause)
+                    continue;
+                try {
+                    await dependencies.beforeRefresh?.();
+                }
+                catch {
+                    last = {
+                        status: 'waiting',
+                        code: 'readiness_refresh_dependency_failed',
+                        cardFile: config.cardFile,
+                        preflight: null,
+                    };
+                    notify(last);
+                    continue;
+                }
+                if (closed)
+                    break;
+                if (!directoriesCurrent()) {
+                    last = {
+                        status: 'blocked',
+                        code: 'readiness_directory_changed',
+                        cardFile: config.cardFile,
+                        preflight: null,
+                    };
+                    notify(last);
+                    continue;
+                }
+                const cause = inputCause();
+                if (!forced && cause === lastCause)
+                    continue;
+                lastCause = cause;
+                last = publishManagedPiReadiness(config, source);
+                notify(last);
+            }
+        })().finally(() => {
+            active = null;
+            if (pending && !closed)
+                void refresh(forcePending);
+        });
+        return active;
+    };
+    try {
+        for (const [directory, names] of directories) {
+            const watcher = fs.watch(directory, (_event, filename) => {
+                if (closed)
+                    return;
+                if (filename === null || names.has(filename.toString()))
+                    void refresh();
+            });
+            watcher.on('error', () => {
+                last = {
+                    status: 'blocked',
+                    code: 'readiness_watch_failed',
+                    cardFile: config.cardFile,
+                    preflight: null,
+                };
+            });
+            watchers.push(watcher);
+        }
+        void refresh();
+    }
+    catch (error) {
+        for (const watcher of watchers)
+            watcher.close();
+        throw error;
+    }
+    return {
+        refresh,
+        status: () => last,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            for (const watcher of watchers)
+                watcher.close();
+            await active;
+        },
+    };
+}

package/dist/app/managed-pi-repair-stop.d.ts

@@ -0,0 +1,21 @@
+import { requestManagedPiControl } from '../hosts/pi/managed-session.js';
+import { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+import type { ManagedPiExecutionScope } from './collab-session-transition.js';
+import type { RoleRepairDependencies } from './collab-role-repair.js';
+import { type ManagedPiSdkResumeAuthorization } from './managed-pi-resume-admission.js';
+/** The owned SDK process registers itself before TUI input; no PID comes from configuration. */
+export declare function registerManagedPiRuntime(controller: ManagedPiSdkSessionController, scope: ManagedPiExecutionScope, descriptorFile: string, options?: {
+    readonly confirmNative?: boolean;
+    readonly resumeAuthorization?: ManagedPiSdkResumeAuthorization;
+}): Promise<void>;
+/** Read-only OS witness for the socket owner; it neither reads nor prints an authentication token. */
+export declare function managedPiSocketPeerPid(socketPath: string): number | null;
+export declare function managedPiRepairDependencies(request: {
+    readonly execution: {
+        readonly task_root: string;
+    };
+    readonly repair_policy?: unknown;
+}, deps?: {
+    readonly control?: typeof requestManagedPiControl;
+    readonly peerPid?: typeof managedPiSocketPeerPid;
+}): RoleRepairDependencies | undefined;