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

package/dist/app/managed-pi-handoff-reference.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson } from '../collab/envelope.js';
+import { readBoundedFile } from './bounded-file.js';
+/** Publish captured context only at the destination explicitly approved by the launch request. */
+export function prepareManagedHandoffContextReference(request) {
+    const bootstrap = readBoundedFile(request.bootstrap_request.ref, 64 * 1024);
+    // The transition reports invalid or missing legacy bootstrap inputs itself.
+    // This hook only adds a context reference for an explicitly pinned managed launch.
+    if (!bootstrap.ok || bootstrap.digest !== request.bootstrap_request.digest)
+        return;
+    const value = JSON.parse(bootstrap.text);
+    if (typeof value !== 'object' ||
+        value === null ||
+        !('managed_runtime' in value))
+        return;
+    const runtime = value.managed_runtime;
+    const file = runtime?.handoff_context_file;
+    if (file === undefined)
+        return;
+    if (typeof file !== 'string' || !path.isAbsolute(file))
+        throw new Error('handoff_context_path_invalid');
+    const parent = fs.lstatSync(path.dirname(file));
+    if (!parent.isDirectory() ||
+        parent.isSymbolicLink() ||
+        parent.mode & 0o077 ||
+        fs.realpathSync(path.dirname(file)) !== path.dirname(file) ||
+        (typeof process.getuid === 'function' && parent.uid !== process.getuid()))
+        throw new Error('handoff_context_parent_not_private');
+    const bytes = `${canonicalJson({
+        schema: 'pappra/managed-handoff-context/1',
+        task_root: request.task_root,
+        transition_id: request.transition_id,
+        intent_id: request.intent.intent_id,
+        handoff_id: request.intent.handoff_id,
+        generation: request.intent.generation,
+        bundle: request.bundle,
+    })}\n`;
+    if (fs.lstatSync(file, { throwIfNoEntry: false })) {
+        const previous = readBoundedFile(file, 64 * 1024);
+        if (!previous.ok || previous.text !== bytes)
+            throw new Error('handoff_context_reference_conflict');
+        return;
+    }
+    const fd = fs.openSync(file, 'wx', 0o600);
+    try {
+        fs.writeFileSync(fd, bytes);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const directory = fs.openSync(path.dirname(file), 'r');
+    try {
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+}

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

@@ -0,0 +1,21 @@
+import { type CommandRunner } from './collab-notify.js';
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+type Runtime = Pick<ManagedPiSdkSessionController, 'snapshot' | 'observe' | 'subscribe' | 'isDisposed'>;
+/** Publish only this process's owned native SDK runtime; publication is not task authority. */
+export declare function publishManagedPiHerdrIdentity(runtime: Runtime, options: {
+    readonly paneId: string;
+    readonly name?: string;
+    readonly run?: CommandRunner;
+}): Promise<{
+    refresh: () => Promise<void>;
+    status: () => {
+        source: string;
+        pane_id: string;
+        native_session_id: string;
+        error: string | null;
+        session_reference: string;
+        limitation: string;
+    };
+    close(): Promise<void>;
+}>;
+export {};

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

@@ -0,0 +1,185 @@
+import { runHerdrCommand } from './collab-notify.js';
+const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Publish only this process's owned native SDK runtime; publication is not task authority. */
+export async function publishManagedPiHerdrIdentity(runtime, options) {
+    if (!/^[A-Za-z0-9]+:p[A-Za-z0-9]+$/.test(options.paneId) ||
+        (options.name !== undefined &&
+            !/^[a-z][a-z0-9_-]{0,31}$/.test(options.name)))
+        throw new Error('managed_herdr_identity_invalid');
+    const run = options.run ?? runHerdrCommand;
+    const source = `pappra-managed-sdk:${runtime.observe().native.sessionId}`;
+    let seq = Date.now() * 1000;
+    let closed = false;
+    let pending = false;
+    let active = null;
+    let lastState = null;
+    let error = null;
+    const invoke = async (args, read = false) => {
+        let result = await run('herdr', args, 5000);
+        // This observation has no native effect. A busy Herdr server can miss the
+        // first deadline while simultaneous SDK/MCP startups enumerate processes.
+        // Mutations and failed ownership observations are never repeated here.
+        if (read && result.timedOut)
+            result = await run('herdr', args, 5000);
+        if (!result.spawned ||
+            result.code !== 0 ||
+            result.timedOut ||
+            result.signal ||
+            result.spawnError)
+            throw new Error(`managed_herdr_operation_failed:${args[0]}:${args[1]}:${result.timedOut ? 'timeout' : result.spawnError ? 'spawn' : String(result.code)}`);
+        if (!read)
+            return null;
+        try {
+            const value = JSON.parse(result.stdout);
+            if (object(value) && object(value.result))
+                return value.result;
+        }
+        catch {
+            /* Never expose raw command output. */
+        }
+        throw new Error('managed_herdr_observation_invalid');
+    };
+    const assertOwnedPane = async () => {
+        const snapshot = runtime.snapshot();
+        if (runtime.isDisposed || snapshot.process.pid !== process.pid)
+            throw new Error('managed_herdr_runtime_not_owned');
+        const result = await invoke(['pane', 'process-info', '--pane', options.paneId], true);
+        const info = result?.process_info;
+        if (!object(info) ||
+            info.pane_id !== options.paneId ||
+            !Array.isArray(info.foreground_processes) ||
+            !info.foreground_processes.some((row) => object(row) && row.pid === process.pid))
+            throw new Error('managed_herdr_pane_not_owned');
+    };
+    const stateOf = () => {
+        const s = runtime.snapshot();
+        const owned = s.ownedRuntime;
+        if (owned.extensionDialogs.pending.length ||
+            owned.queues.internal.activeSelector)
+            return 'blocked';
+        if (owned.work.observation !== 'complete' ||
+            owned.queues.completeness !== 'complete')
+            return 'unknown';
+        return owned.work.isIdle &&
+            !owned.work.isStreaming &&
+            !owned.work.isCompacting &&
+            !owned.work.isBashRunning &&
+            owned.work.pendingToolCalls === 0
+            ? 'idle'
+            : 'working';
+    };
+    const publish = async () => {
+        await assertOwnedPane();
+        const live = runtime.observe();
+        const snapshot = runtime.snapshot();
+        const state = stateOf();
+        const fingerprint = `${live.native.sessionId}:${snapshot.session.sessionFile}:${state}`;
+        if (fingerprint === lastState)
+            return;
+        const ref = snapshot.session.sessionFile
+            ? ['--agent-session-path', snapshot.session.sessionFile]
+            : ['--agent-session-id', live.native.sessionId];
+        await invoke([
+            'pane',
+            'report-agent',
+            options.paneId,
+            '--source',
+            source,
+            '--agent',
+            'pi',
+            '--state',
+            state,
+            '--seq',
+            String(++seq),
+            ...ref,
+        ]);
+        await assertOwnedPane();
+        await invoke([
+            'pane',
+            'report-agent-session',
+            options.paneId,
+            '--source',
+            source,
+            '--agent',
+            'pi',
+            '--seq',
+            String(++seq),
+            ...ref,
+            '--session-start-source',
+            'startup',
+        ]);
+        lastState = fingerprint;
+    };
+    try {
+        await publish();
+        if (options.name) {
+            await assertOwnedPane();
+            await invoke(['agent', 'rename', options.paneId, options.name]);
+        }
+    }
+    catch (failure) {
+        await invoke([
+            'pane',
+            'release-agent',
+            options.paneId,
+            '--source',
+            source,
+            '--agent',
+            'pi',
+        ]).catch(() => { });
+        throw failure;
+    }
+    const refresh = () => {
+        if (closed)
+            return active ?? Promise.resolve();
+        pending = true;
+        if (active)
+            return active;
+        active = (async () => {
+            try {
+                while (pending && !closed) {
+                    pending = false;
+                    await publish();
+                    error = null;
+                }
+            }
+            catch {
+                error = 'managed_herdr_publication_failed';
+            }
+            finally {
+                active = null;
+            }
+        })();
+        return active;
+    };
+    const unsubscribe = runtime.subscribe(() => {
+        void refresh();
+    });
+    return {
+        refresh,
+        status: () => ({
+            source,
+            pane_id: options.paneId,
+            native_session_id: runtime.observe().native.sessionId,
+            error,
+            session_reference: 'published_native_sdk_observation',
+            limitation: 'herdr_may_omit_sdk_session_reference_from_agent_list',
+        }),
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            unsubscribe();
+            await active;
+            await invoke([
+                'pane',
+                'release-agent',
+                options.paneId,
+                '--source',
+                source,
+                '--agent',
+                'pi',
+            ]).catch(() => { });
+        },
+    };
+}

package/dist/app/managed-pi-initial-admission.d.ts

@@ -0,0 +1,28 @@
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+import { type BoundManagedPiExecutionScope } from './managed-pi-transition-host.js';
+import type { ManagedPiExecutionScope } from './collab-session-transition.js';
+type AdmissionState = 'waiting' | 'awaiting_idle' | 'bound' | 'unavailable';
+export interface ManagedPiInitialAdmissionConfig {
+    readonly taskRoot: string;
+    readonly assignmentFile: string;
+    readonly subtaskId: string;
+    readonly attempt: number;
+    readonly ownerEpoch: number;
+    readonly inputRevision: string;
+}
+/**
+ * Wait for a real task-store ASSIGN and its claims before binding a controller-owned Pi runtime.
+ * The startup artifact is only a preview: its contents never grant authority. The admitted Task
+ * assignment_ref/digest becomes authoritative, and its bytes remain pinned after binding.
+ */
+export declare function watchManagedPiInitialAdmission(controller: ManagedPiSdkSessionController, config: ManagedPiInitialAdmissionConfig, onBound: (binding: BoundManagedPiExecutionScope) => Promise<void>): Promise<{
+    refresh: () => Promise<void>;
+    canExecute: () => boolean;
+    status: () => {
+        state: AdmissionState;
+        error: string | null;
+        scope: ManagedPiExecutionScope | null;
+    };
+    close(): Promise<void>;
+}>;
+export {};