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

package/dist/hosts/pi/managed-session-extension.d.ts

@@ -0,0 +1,20 @@
+type SessionContext = {
+    cwd: string;
+    sessionManager: {
+        getSessionFile(): string | null | undefined;
+        getSessionId(): string;
+    };
+};
+type InputEvent = {
+    text: string;
+    source?: string;
+    streamingBehavior?: string;
+};
+type ManagedExtensionApi = {
+    on(event: 'session_start' | 'session_shutdown' | 'agent_settled', handler: (_event: unknown, context: SessionContext) => void): unknown;
+    on(event: 'input', handler: (event: InputEvent) => {
+        action: 'continue' | 'handled';
+    } | void): unknown;
+};
+export default function managedPiSessionExtension(pi: ManagedExtensionApi): void;
+export {};

package/dist/hosts/pi/managed-session-extension.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+const METADATA_ENV = 'PAPPRA_MANAGED_PI_METADATA_FILE';
+const SCHEMA = 'harness-collab/pi-managed-session/1';
+function appendMetadata(record) {
+    const file = process.env[METADATA_ENV];
+    if (!file || !file.startsWith('/'))
+        return false;
+    let fd;
+    try {
+        fd = fs.openSync(file, 'a', 0o600);
+        const line = Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
+        let written = 0;
+        while (written < line.length) {
+            written += fs.writeSync(fd, line, written, line.length - written);
+        }
+        fs.fsyncSync(fd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // The record was either persisted or its caller observes failure.
+            }
+        }
+    }
+}
+function sessionStartRecord(context) {
+    return {
+        schema: SCHEMA,
+        type: 'session_start',
+        at: new Date().toISOString(),
+        cwd: context.cwd,
+        session_file: context.sessionManager.getSessionFile() ?? null,
+        session_id: context.sessionManager.getSessionId(),
+    };
+}
+export default function managedPiSessionExtension(pi) {
+    pi.on('session_start', (_event, context) => {
+        appendMetadata(sessionStartRecord(context));
+    });
+    pi.on('agent_settled', (_event, context) => {
+        appendMetadata({
+            schema: SCHEMA,
+            type: 'agent_settled',
+            session_id: context.sessionManager.getSessionId(),
+            cwd: context.cwd,
+            session_file: context.sessionManager.getSessionFile() ?? null,
+            at: new Date().toISOString(),
+        });
+    });
+    pi.on('session_shutdown', (_event, context) => {
+        appendMetadata({
+            schema: SCHEMA,
+            type: 'session_shutdown_observed',
+            at: new Date().toISOString(),
+            cwd: context.cwd,
+            session_file: context.sessionManager.getSessionFile() ?? null,
+        });
+    });
+    pi.on('input', (event) => {
+        const text = typeof event.text === 'string' ? event.text : '';
+        const persisted = appendMetadata({
+            schema: SCHEMA,
+            type: 'input_event_observed',
+            at: new Date().toISOString(),
+            source: typeof event.source === 'string' ? event.source : 'unknown',
+            streaming_behavior: typeof event.streamingBehavior === 'string'
+                ? event.streamingBehavior
+                : null,
+            text_sha256: createHash('sha256').update(text, 'utf8').digest('hex'),
+            text_utf8_bytes: Buffer.byteLength(text, 'utf8'),
+        });
+        // The PTY ingress has already been write-ahead journaled. If the semantic observation
+        // cannot be persisted, do not let this input proceed without its controller evidence.
+        return { action: persisted ? 'continue' : 'handled' };
+    });
+}

package/dist/hosts/pi/managed-session.d.ts

@@ -0,0 +1,177 @@
+export declare const MANAGED_PI_SESSION_SCHEMA: 'harness-collab/pi-managed-session/1';
+/** Launch a fresh interactive TUI using normal Pi configuration and an explicit OpenRouter model. */
+export interface ManagedPiSessionOptions {
+    readonly cwd: string;
+    readonly model: string;
+    readonly journalPath: string;
+    readonly controlSocketPath?: string;
+    readonly piBin?: string;
+    readonly pythonBin?: string;
+    readonly shutdownGraceMs?: number;
+}
+export interface ManagedPiProcessIdentity {
+    readonly runId: string;
+    readonly helperPid: number;
+    readonly piPid: number;
+    readonly sessionId: string;
+}
+export interface ManagedPiControlEndpoint {
+    readonly socketPath: string;
+    readonly descriptorPath: string;
+}
+export interface ManagedPiSessionExit {
+    readonly status: 'exited' | 'unknown';
+    readonly piPid: number;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly helperExitCode: number | null;
+    readonly helperSignal: string | null;
+    readonly reason: string | null;
+}
+export interface ManagedPiTranscriptObservation {
+    readonly status: 'verified' | 'not_observed' | 'mismatch' | 'unreadable';
+    readonly path: string | null;
+    readonly sessionId: string | null;
+    readonly cwd: string | null;
+    readonly sha256: string | null;
+    readonly bytes: number | null;
+    readonly detail: string | null;
+}
+export interface ManagedPiSessionSnapshot {
+    readonly schema: typeof MANAGED_PI_SESSION_SCHEMA;
+    readonly runId: string;
+    readonly provider: 'openrouter';
+    readonly model: string;
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly process: ManagedPiProcessIdentity;
+    readonly processExit: ManagedPiSessionExit | null;
+    readonly readiness: {
+        readonly ownedPiChild: 'started';
+        readonly extensionSessionStart: 'observed';
+        readonly terminalUiRender: 'not_observed';
+    };
+    readonly ingress: {
+        readonly state: 'open' | 'fenced';
+        readonly journalPath: string;
+        readonly sequence: number;
+        readonly headDigest: string;
+        readonly healthy: boolean;
+        readonly rawTerminalInputJournaled: false;
+        readonly terminalInputMetadataJournaled: true;
+    };
+    readonly transcript: ManagedPiTranscriptObservation;
+    readonly nativeInventory: {
+        readonly queuedMessages: 'unknown';
+        readonly approvals: 'unknown';
+        readonly inFlightWork: 'unknown';
+        readonly externalWriters: 'unknown';
+        readonly descendants: 'uncontrolled';
+    };
+    readonly transferReady: false;
+    readonly blockers: readonly string[];
+}
+export interface ManagedPiReceiverConfirmation {
+    readonly receiverSessionId: string;
+    readonly confirmationId: string;
+    readonly confirmedAt: string;
+}
+export interface ManagedPiFirstWorkObservation {
+    readonly receiverSessionId: string;
+    readonly workId: string;
+    readonly observedAt: string;
+}
+export type ManagedPiArchiveResult = {
+    readonly ok: true;
+    readonly archivePath: string;
+    readonly sha256: string;
+    readonly bytes: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface ManagedPiSession {
+    readonly identity: ManagedPiProcessIdentity;
+    readonly journalPath: string;
+    readonly controlEndpoint: ManagedPiControlEndpoint;
+    waitForExit(): Promise<ManagedPiSessionExit>;
+    snapshot(): ManagedPiSessionSnapshot;
+    fenceIngress(reason?: string): void;
+    stopOwnedChild(): Promise<ManagedPiSessionExit>;
+    archiveOriginalTranscript(input: {
+        readonly destinationPath: string;
+        readonly receiverConfirmation: ManagedPiReceiverConfirmation;
+        readonly firstWork: ManagedPiFirstWorkObservation;
+    }): ManagedPiArchiveResult;
+    close(): void;
+}
+export declare class ManagedPiSessionError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+interface JournalRecord {
+    readonly schema: typeof MANAGED_PI_SESSION_SCHEMA;
+    readonly run_id: string;
+    readonly sequence: number;
+    readonly at: string;
+    readonly kind: string;
+    readonly previous_digest: string;
+    readonly digest: string;
+    readonly [key: string]: unknown;
+}
+/** Fsync-backed, hash-chained journal. */
+export declare class ManagedPiJournal {
+    readonly path: string;
+    private readonly fd;
+    private readonly runId;
+    private sequence;
+    private headDigest;
+    private failure;
+    private isClosed;
+    private isFenced;
+    constructor(path: string, fd: number, runId: string);
+    get healthy(): boolean;
+    get fenced(): boolean;
+    get currentSequence(): number;
+    get currentDigest(): string;
+    append(kind: string, fields?: Record<string, unknown>): JournalRecord;
+    fence(reason: string): void;
+    close(): void;
+}
+/** Write-ahead admission metadata, without retaining terminal input or secrets. */
+export declare function forwardJournaledManagedInput(journal: ManagedPiJournal, chunk: Uint8Array, forward: (bytes: Uint8Array) => void): boolean;
+export declare function buildManagedPiArgv(input: {
+    readonly model: string;
+    readonly sessionId: string;
+    readonly extensionPath: string;
+}): string[];
+interface ProcessEventIdentity {
+    readonly runId: string;
+    readonly helperPid: number;
+    readonly piPid: number;
+}
+interface PiExitEvent extends ProcessEventIdentity {
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+}
+/** Exit receipts from the bridge count only when all child identity fields match. */
+export declare function isOwnedManagedPiExit(event: PiExitEvent, identity: ProcessEventIdentity): boolean;
+/** @internal: exercised by the owned PTY bridge regression test. */
+export declare const managedPiPtyBridgeSourceForTests: string;
+export interface ManagedPiJournalArtifacts {
+    readonly journal: ManagedPiJournal;
+    readonly metadataPath: string;
+}
+/** Create private, exclusive journal and Pi observer metadata artifacts for SDK mode. */
+export declare function createManagedPiJournalArtifacts(journalPath: string, runId?: `${string}-${string}-${string}-${string}-${string}`): ManagedPiJournalArtifacts;
+export declare function validateManagedPiArchiveEvidence(input: {
+    readonly sourceExited: boolean;
+    readonly transcript: ManagedPiTranscriptObservation;
+    readonly receiverConfirmation: ManagedPiReceiverConfirmation;
+    readonly firstWork: ManagedPiFirstWorkObservation;
+}): string | null;
+/** Cross-process client for the private descriptor written beside the journal. */
+export declare function requestManagedPiControl(descriptorPath: string, action: 'snapshot' | 'fence' | 'stop' | 'deliver', payload?: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+/** Start Pi as an owned visible TUI; its native screen is passed directly through the PTY. */
+export declare function startManagedPiSession(options: ManagedPiSessionOptions): Promise<ManagedPiSession>;
+export {};