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

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

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { continuityTaskPaths, writeContinuityBytes, } from '../continuity/paths.js';
+import { readBoundedFile } from './bounded-file.js';
+import { applySessionTransition, planSessionTransition, } from './collab-session-transition.js';
+const MAX_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+function transcript(file, sessionId, cwd) {
+    const before = fs.lstatSync(file);
+    const read = readBoundedFile(file, MAX_TRANSCRIPT_BYTES);
+    const after = fs.lstatSync(file);
+    if (!read.ok ||
+        before.dev !== after.dev ||
+        before.ino !== after.ino ||
+        before.size !== after.size ||
+        before.mtimeMs !== after.mtimeMs)
+        throw new Error('retirement_transcript_unstable');
+    let header;
+    try {
+        header = JSON.parse(read.text.split('\n', 1)[0]);
+    }
+    catch {
+        throw new Error('retirement_transcript_invalid');
+    }
+    if (header.type !== 'session' ||
+        header.id !== sessionId ||
+        header.cwd !== cwd)
+        throw new Error('retirement_transcript_identity_mismatch');
+    return read;
+}
+/** Native disposal and retention follow authoritative transfer + successor first work. */
+export async function retireManagedPiSource(request, runtime, dependencies = {}) {
+    const observed = runtime.observe();
+    if (observed.native.sessionId !== request.intent.from.session_id ||
+        path.resolve(observed.cwd) !== path.resolve(request.intent.from.cwd ?? ''))
+        throw new Error('retirement_source_identity_mismatch');
+    // Check read-only first: retirement must never advance bootstrap or transfer.
+    const planned = await planSessionTransition(request, dependencies);
+    if (!planned.ok || planned.stage !== 'task_retired')
+        throw new Error('retirement_first_work_gate_unsatisfied');
+    const verified = await applySessionTransition(request, dependencies);
+    if (!verified.ok || verified.stage !== 'task_retired')
+        throw new Error('retirement_first_work_gate_unsatisfied');
+    const { root, continuity_task_id: taskId } = request.bundle;
+    const directory = path.join(continuityTaskPaths(root, taskId).taskDir, 'retired-sessions');
+    const archiveFile = path.join(directory, `${request.transition_id}.jsonl`);
+    const receiptFile = path.join(directory, `${request.transition_id}.receipt.json`);
+    const nativeFile = runtime.snapshot().session.sessionFile;
+    if (!nativeFile)
+        throw new Error('retirement_transcript_unavailable');
+    const prior = fs.lstatSync(receiptFile, { throwIfNoEntry: false });
+    if (prior) {
+        const read = readBoundedFile(receiptFile, 16 * 1024);
+        if (!read.ok)
+            throw new Error('retirement_receipt_unreadable');
+        const value = JSON.parse(read.text);
+        const archive = readBoundedFile(archiveFile, MAX_TRANSCRIPT_BYTES);
+        if (!runtime.isDisposed ||
+            value.schema !== 'pappra/managed-pi-retirement/1' ||
+            value.transition_id !== request.transition_id ||
+            value.source_session_id !== observed.native.sessionId ||
+            value.successor_session_id !== request.intent.to.session_id ||
+            value.status !== 'runtime_disposed_and_transcript_retained' ||
+            value.transcript?.source !== nativeFile ||
+            value.stop?.status !== 'runtime_disposed' ||
+            value.stop.process_exit !== 'not_owned' ||
+            value.transcript?.ref !==
+                path.relative(root, archiveFile).split(path.sep).join('/') ||
+            !archive.ok ||
+            archive.digest !== value.transcript.digest)
+            throw new Error('retirement_receipt_conflict');
+        transcript(archiveFile, observed.native.sessionId, observed.cwd);
+        return { receipt: value, receiptFile, duplicate: true };
+    }
+    transcript(nativeFile, observed.native.sessionId, observed.cwd);
+    const stopped = await runtime.stopOwnedRuntime();
+    if (stopped.status !== 'runtime_disposed' ||
+        stopped.sessionId !== observed.native.sessionId ||
+        stopped.process.exit !== 'not_owned' ||
+        !stopped.finalSnapshot.scopedQuiescent)
+        throw new Error('retirement_runtime_stop_unknown');
+    const bytes = transcript(nativeFile, observed.native.sessionId, observed.cwd);
+    const existing = fs.lstatSync(archiveFile, { throwIfNoEntry: false });
+    if (existing) {
+        const saved = readBoundedFile(archiveFile, MAX_TRANSCRIPT_BYTES);
+        if (!saved.ok || saved.digest !== bytes.digest)
+            throw new Error('retirement_archive_conflict');
+    }
+    else {
+        const saved = await writeContinuityBytes(root, taskId, archiveFile, bytes.bytes, true);
+        if (!saved.ok)
+            throw new Error(saved.code);
+    }
+    const receipt = {
+        schema: 'pappra/managed-pi-retirement/1',
+        transition_id: request.transition_id,
+        source_session_id: observed.native.sessionId,
+        successor_session_id: request.intent.to.session_id,
+        status: 'runtime_disposed_and_transcript_retained',
+        stop: { status: 'runtime_disposed', process_exit: 'not_owned' },
+        transcript: {
+            source: nativeFile,
+            ref: path.relative(root, archiveFile).split(path.sep).join('/'),
+            digest: bytes.digest,
+            original: 'retained-in-place',
+        },
+        native_history: 'unchanged',
+    };
+    const saved = await writeContinuityBytes(root, taskId, receiptFile, Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`), true);
+    if (!saved.ok)
+        throw new Error(saved.code);
+    return { receipt, receiptFile, duplicate: false };
+}

package/dist/app/managed-pi-sdk-control.d.ts

@@ -0,0 +1,7 @@
+import type { ManagedPiSdkSessionController } from '../hosts/pi/managed-sdk-session.js';
+/** Private local endpoint for a runtime created by this process. Never adopts a PID. */
+export declare function serveManagedPiSdkControl(controller: ManagedPiSdkSessionController, journalPath: string, requestedSocket?: string, automationStatus?: () => unknown, deliver?: (request: Readonly<Record<string, unknown>>) => Promise<Readonly<Record<string, unknown>>>): Promise<{
+    runId: string;
+    stopped: Promise<void>;
+    close(): void;
+}>;

package/dist/app/managed-pi-sdk-control.js

@@ -0,0 +1,169 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+/** Private local endpoint for a runtime created by this process. Never adopts a PID. */
+export async function serveManagedPiSdkControl(controller, journalPath, requestedSocket, automationStatus = () => null, deliver) {
+    const directory = path.dirname(journalPath);
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        (stat.mode & 0o077) !== 0 ||
+        fs.realpathSync(directory) !== directory ||
+        (typeof process.getuid === 'function' && stat.uid !== process.getuid()))
+        throw new Error('sdk_control_directory_not_private');
+    const descriptorPath = `${journalPath}.control.json`;
+    if (fs.lstatSync(descriptorPath, { throwIfNoEntry: false }))
+        throw new Error('sdk_control_path_unavailable');
+    // macOS's per-user temp root and task paths can exceed sockaddr_un limits.
+    const socketDirectory = requestedSocket
+        ? null
+        : fs.mkdtempSync(path.join(process.platform === 'darwin' ? '/private/tmp' : os.tmpdir(), 'pi-ctl-'));
+    const socketPath = requestedSocket ?? path.join(socketDirectory, 'c.sock');
+    if (!path.isAbsolute(socketPath) ||
+        Buffer.byteLength(socketPath) > 100 ||
+        fs.existsSync(socketPath) ||
+        fs.existsSync(descriptorPath))
+        throw new Error('sdk_control_path_unavailable');
+    const token = randomBytes(32).toString('hex');
+    const runId = randomBytes(16).toString('hex');
+    const peers = new Set();
+    let busy = false;
+    let resolveStopped;
+    const stopped = new Promise((resolve) => {
+        resolveStopped = resolve;
+    });
+    const server = net.createServer((socket) => {
+        peers.add(socket);
+        socket.once('close', () => peers.delete(socket));
+        socket.setTimeout(75_000, () => socket.destroy());
+        const chunks = [];
+        let requestBytes = 0;
+        let handled = false;
+        const send = (result) => socket.end(`${JSON.stringify(result)}\n`);
+        socket.on('data', (chunk) => {
+            if (handled)
+                return;
+            requestBytes += chunk.length;
+            if (requestBytes > 8192) {
+                handled = true;
+                send({ ok: false, reason: 'request_too_large' });
+                return;
+            }
+            chunks.push(chunk);
+            if (!chunk.includes(0x0a))
+                return;
+            const data = Buffer.concat(chunks).toString('utf8');
+            const newline = data.indexOf('\n');
+            handled = true;
+            void (async () => {
+                try {
+                    const request = JSON.parse(data.slice(0, newline));
+                    const provided = Buffer.from(typeof request?.token === 'string' ? request.token : '');
+                    const expected = Buffer.from(token);
+                    if (provided.length !== expected.length ||
+                        !timingSafeEqual(provided, expected)) {
+                        send({ ok: false, reason: 'unauthorized' });
+                        return;
+                    }
+                    if (request.command === 'snapshot') {
+                        send({
+                            ok: true,
+                            snapshot: controller.snapshot(),
+                            automation: automationStatus(),
+                        });
+                        return;
+                    }
+                    if (request.command === 'deliver') {
+                        if (!deliver)
+                            send({ ok: false, reason: 'delivery_not_configured' });
+                        else
+                            send(await deliver(request));
+                        return;
+                    }
+                    if (busy) {
+                        send({ ok: false, reason: 'operation_in_progress' });
+                        return;
+                    }
+                    if (!['fence', 'stop'].includes(request.command)) {
+                        send({ ok: false, reason: 'unsupported_command' });
+                        return;
+                    }
+                    busy = true;
+                    try {
+                        if (request.command === 'fence')
+                            send({
+                                ok: true,
+                                snapshot: await controller.quiesce('authenticated_control_request'),
+                            });
+                        else {
+                            const exit = await controller.stopOwnedRuntime();
+                            send({ ok: true, exit });
+                            // Resolve after the response has entered the socket, before CLI cleanup.
+                            socket.once('close', resolveStopped);
+                        }
+                    }
+                    finally {
+                        busy = false;
+                    }
+                }
+                catch {
+                    send({ ok: false, reason: 'control_operation_failed' });
+                }
+            })();
+        });
+        socket.on('error', () => { });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(socketPath, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    fs.chmodSync(socketPath, 0o600);
+    const socketIdentity = fs.lstatSync(socketPath);
+    try {
+        const fd = fs.openSync(descriptorPath, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify({
+                schema: 'harness-collab/pi-managed-control/1',
+                socketPath,
+                token,
+                runId,
+                sessionId: controller.observe().native.sessionId,
+            })}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (error) {
+        server.close();
+        throw error;
+    }
+    return {
+        runId,
+        stopped,
+        close() {
+            for (const peer of peers)
+                peer.destroy();
+            server.close();
+            const current = fs.lstatSync(socketPath, { throwIfNoEntry: false });
+            if (current?.isSocket() &&
+                current.dev === socketIdentity.dev &&
+                current.ino === socketIdentity.ino)
+                fs.unlinkSync(socketPath);
+            if (socketDirectory) {
+                try {
+                    fs.rmdirSync(socketDirectory);
+                }
+                catch {
+                    /* preserve unexpected contents */
+                }
+            }
+        },
+    };
+}

package/dist/app/managed-pi-sdk-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { ManagedPiRequest } from './managed-pi.js';
+/** Native SDK CLI lifecycle, including a receiver's deferred authoritative task binding. */
+export declare function runManagedPiSdkRuntime(request: ManagedPiRequest): Promise<number>;