@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/hosts/codex/protocol.d.ts

@@ -0,0 +1,51 @@
+export interface NativeItem {
+    [key: string]: unknown;
+    type?: string;
+    text?: string;
+    status?: string;
+    exitCode?: number;
+    aggregatedOutput?: string;
+}
+export interface NativeEntry {
+    [key: string]: unknown;
+    id?: string;
+    status?: string;
+    item?: NativeItem;
+}
+export interface NativeThread {
+    [key: string]: unknown;
+    id?: string;
+    cwd?: string;
+    status?: {
+        type: string;
+    };
+}
+export interface NativeReply {
+    [key: string]: unknown;
+    thread?: NativeThread;
+    turn?: NativeEntry;
+    data?: NativeEntry[];
+}
+export interface NativeParams {
+    [key: string]: unknown;
+    threadId?: string;
+    turn?: NativeEntry;
+}
+export interface NativeRecord {
+    id?: string | number;
+    method?: string;
+    params?: NativeParams;
+    result?: NativeReply;
+    error?: {
+        message?: string;
+    };
+}
+export interface NativeEvent {
+    seq: number;
+    method: string;
+    params: NativeParams | null;
+    at: string;
+    error?: never;
+}
+export declare function isReply(value: unknown): value is NativeReply;
+export declare function isRecord(value: unknown): value is NativeRecord;

package/dist/hosts/codex/protocol.js

@@ -0,0 +1,42 @@
+import { object } from '../../collab/validation.js';
+const optionalString = (value) => value === undefined || typeof value === 'string';
+function isEntry(value) {
+    const item = object(value) ? value['item'] : undefined;
+    return (object(value) &&
+        optionalString(value['id']) &&
+        optionalString(value['status']) &&
+        (value['item'] === undefined ||
+            (object(value['item']) &&
+                object(item) &&
+                ['type', 'text', 'status', 'aggregatedOutput'].every((key) => optionalString(item[key])) &&
+                (value['item']['exitCode'] === undefined ||
+                    typeof value['item']['exitCode'] === 'number'))));
+}
+export function isReply(value) {
+    return (object(value) &&
+        (value['thread'] === undefined ||
+            (object(value['thread']) &&
+                optionalString(value['thread']['id']) &&
+                optionalString(value['thread']['cwd']) &&
+                (value['thread']['status'] === undefined ||
+                    (object(value['thread']['status']) &&
+                        typeof value['thread']['status']['type'] === 'string')))) &&
+        (value['turn'] === undefined || isEntry(value['turn'])) &&
+        (value['data'] === undefined ||
+            (Array.isArray(value['data']) && value['data'].every(isEntry))));
+}
+export function isRecord(value) {
+    return (object(value) &&
+        (value['id'] === undefined ||
+            typeof value['id'] === 'string' ||
+            typeof value['id'] === 'number') &&
+        optionalString(value['method']) &&
+        (value['params'] === undefined ||
+            (object(value['params']) &&
+                optionalString(value['params']['threadId']) &&
+                (value['params']['turn'] === undefined ||
+                    isEntry(value['params']['turn'])))) &&
+        (value['result'] === undefined || isReply(value['result'])) &&
+        (value['error'] === undefined ||
+            (object(value['error']) && optionalString(value['error']['message']))));
+}

package/dist/hosts/detect.d.ts

@@ -0,0 +1,28 @@
+import type { EvidenceRef } from '../schemas/evidence.js';
+export type HostName = 'pi' | 'codex' | 'claude';
+export interface PassiveToolObservation {
+    readonly name: string;
+    readonly command: string;
+    readonly executablePath: string | null;
+    readonly discovered: boolean;
+}
+export interface PassiveHostObservation {
+    readonly host: HostName;
+    readonly selected: boolean;
+    readonly executablePath: string | null;
+    readonly discovered: boolean;
+    readonly configPaths: readonly string[];
+    readonly configured: boolean;
+    readonly callable: 'unknown';
+    readonly verification: 'unsupported';
+    readonly evidence: readonly EvidenceRef[];
+}
+export interface HostDetectionOptions {
+    readonly homeDir: string;
+    readonly pathEnv: string;
+    readonly selectedHosts: readonly string[];
+    readonly observedAt?: string;
+}
+export declare function detectPassiveTool(command: string, pathEnv: string): PassiveToolObservation;
+/** Passive host discovery. It never starts a host or reads config contents. */
+export declare function detectPassiveHosts(options: HostDetectionOptions): readonly PassiveHostObservation[];

package/dist/hosts/detect.js

@@ -0,0 +1,73 @@
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+function evidence(path, observedAt) {
+    return {
+        kind: 'file',
+        ref: path,
+        digest: null,
+        observedAt,
+        scope: 'live-owned',
+    };
+}
+function executableOnPath(command, pathEnv) {
+    for (const directory of pathEnv.split(delimiter)) {
+        if (directory === '')
+            continue;
+        const candidate = join(directory, command);
+        try {
+            const stats = statSync(candidate);
+            if (!stats.isFile())
+                continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Continue probing the remaining PATH entries.
+        }
+    }
+    return null;
+}
+export function detectPassiveTool(command, pathEnv) {
+    const executablePath = executableOnPath(command, pathEnv);
+    return {
+        name: command,
+        command,
+        executablePath,
+        discovered: executablePath !== null,
+    };
+}
+/** Passive host discovery. It never starts a host or reads config contents. */
+export function detectPassiveHosts(options) {
+    const observedAt = options.observedAt ?? new Date().toISOString();
+    const configs = {
+        pi: [join(options.homeDir, '.pi')],
+        codex: [join(options.homeDir, '.codex', 'config.toml')],
+        claude: [join(options.homeDir, '.claude', 'settings.json')],
+    };
+    const commands = {
+        pi: 'pi',
+        codex: 'codex',
+        claude: 'claude',
+    };
+    const selected = new Set(options.selectedHosts);
+    return ['pi', 'codex', 'claude'].map((host) => {
+        const executablePath = executableOnPath(commands[host], options.pathEnv);
+        const configPaths = configs[host].filter((path) => existsSync(path));
+        const evidenceRefs = [];
+        if (executablePath !== null)
+            evidenceRefs.push(evidence(executablePath, observedAt));
+        for (const path of configPaths)
+            evidenceRefs.push(evidence(path, observedAt));
+        return {
+            host,
+            selected: selected.has(host),
+            executablePath,
+            discovered: executablePath !== null,
+            configPaths,
+            configured: configPaths.length > 0,
+            callable: 'unknown',
+            verification: 'unsupported',
+            evidence: evidenceRefs,
+        };
+    });
+}

package/dist/hosts/index.d.ts

@@ -0,0 +1,10 @@
+export * as detect from './detect.js';
+export * as codex from './codex/native.js';
+export * as claude from './claude/native.js';
+export * as piRpc from './pi/rpc.js';
+export * as piHistory from './pi/query-result.js';
+export * as pilot from './pilot.js';
+export { HostAdapter, HostIntegrationService, type HostIntegrationOptions, type HostTargetOptions, } from './integration/service.js';
+export { mapNativeHookEvent, readHookInput, runHostHook, type HostHookOptions, type NativeHookMapping, } from './integration/hook.js';
+export { createPiExtension, type PiExtensionLike, } from './integration/pi-extension-runtime.js';
+export { HOST_SUPPORT, nativeEventFor, isSupportedVersion, } from './integration/support.js';

package/dist/hosts/index.js

@@ -0,0 +1,10 @@
+export * as detect from './detect.js';
+export * as codex from './codex/native.js';
+export * as claude from './claude/native.js';
+export * as piRpc from './pi/rpc.js';
+export * as piHistory from './pi/query-result.js';
+export * as pilot from './pilot.js';
+export { HostAdapter, HostIntegrationService, } from './integration/service.js';
+export { mapNativeHookEvent, readHookInput, runHostHook, } from './integration/hook.js';
+export { createPiExtension, } from './integration/pi-extension-runtime.js';
+export { HOST_SUPPORT, nativeEventFor, isSupportedVersion, } from './integration/support.js';

package/dist/hosts/integration/bundle.d.ts

@@ -0,0 +1,16 @@
+import type { HostBundle, HostName } from '../../schemas/host.js';
+export declare const SHARED_SKILL_ID = "pappra";
+export interface HostBundlePayload {
+    readonly bundle: HostBundle;
+    readonly contents: ReadonlyMap<string, Buffer>;
+}
+export declare function installPathForBundleFile(host: HostName, sourcePath: string): string;
+/**
+ * Loads the complete shared skill plus the generated host template. The
+ * digest covers every packaged support file and the exact native template.
+ */
+export declare function loadHostBundle(host: HostName, packageVersion: string, options?: {
+    readonly assetsRoot?: string;
+    readonly runtimeEntry?: string;
+    readonly observedAt?: string;
+}): Promise<HostBundlePayload>;

package/dist/hosts/integration/bundle.js

@@ -0,0 +1,81 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HOST_BUNDLE_SCHEMA } from '../../schemas/host.js';
+import { sha256Digest } from '../../infra/fs.js';
+import { renderHostTemplate } from './templates.js';
+export const SHARED_SKILL_ID = 'pappra';
+function packageRoot() {
+    return dirname(fileURLToPath(import.meta.resolve('@phyzess/pappra/package.json')));
+}
+async function listFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await listFiles(path)));
+        else if (entry.isFile())
+            files.push(path);
+    }
+    return files;
+}
+function portableRelative(root, path) {
+    return relative(root, path).split(sep).join('/');
+}
+export function installPathForBundleFile(host, sourcePath) {
+    if (host === 'pi' && sourcePath === 'templates/pi/entry.ts') {
+        return 'extensions/pappra/index.ts';
+    }
+    return sourcePath;
+}
+/**
+ * Loads the complete shared skill plus the generated host template. The
+ * digest covers every packaged support file and the exact native template.
+ */
+export async function loadHostBundle(host, packageVersion, options = {}) {
+    const root = options.assetsRoot ?? join(packageRoot(), 'assets', 'integrations');
+    const skillRoot = join(root, 'skills', SHARED_SKILL_ID);
+    const paths = await listFiles(skillRoot);
+    if (paths.length === 0) {
+        throw new Error(`No packaged skill files found in ${skillRoot}`);
+    }
+    const contents = new Map();
+    const files = [];
+    for (const path of paths) {
+        const source = portableRelative(root, path);
+        if (source.includes('..') || source.startsWith('/')) {
+            throw new Error(`Unsafe packaged skill path: ${source}`);
+        }
+        const bytes = await readFile(path);
+        contents.set(source, bytes);
+        files.push({
+            path: source,
+            digest: sha256Digest(bytes),
+            kind: source.endsWith('/SKILL.md') ? 'skill' : 'reference',
+        });
+    }
+    const template = renderHostTemplate(host, options.runtimeEntry ??
+        join(packageRoot(), 'dist/hosts/integration/hook-entry.js'));
+    contents.set(template.path, template.bytes);
+    files.push({
+        path: template.path,
+        digest: sha256Digest(template.bytes),
+        kind: template.kind,
+    });
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    const bundleDigest = sha256Digest(files.map((file) => `${file.path}\0${file.digest}`).join('\n'));
+    const observedAt = options.observedAt ?? new Date().toISOString();
+    return {
+        bundle: {
+            schema: HOST_BUNDLE_SCHEMA,
+            host,
+            skillId: SHARED_SKILL_ID,
+            packageVersion,
+            bundleDigest,
+            files,
+            observedAt,
+        },
+        contents,
+    };
+}

package/dist/hosts/integration/hook-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hosts/integration/hook-entry.js

@@ -0,0 +1,68 @@
+import { mapNativeHookEvent, readHookInput, renderHostHookOutput, runHostHook, } from './hook.js';
+import { hostNameSchema } from '../../schemas/host.js';
+import { formatDiagnostic } from '../../schemas/diagnostics.js';
+const EVENTS = [
+    'startup',
+    'resume',
+    'compact',
+    'checkpoint-request',
+];
+function parseEvent(value) {
+    return EVENTS.find((event) => event === value) ?? 'startup';
+}
+function parseHost(value) {
+    const parsed = hostNameSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function writeError(message) {
+    process.stderr.write(`pappra hook: ${message}\n`);
+}
+/**
+ * Command-hook entrypoint. It reads one bounded event, records only a local
+ * observation, and never writes a checkpoint or starts work.
+ */
+async function main() {
+    const host = parseHost(process.argv[2]);
+    if (host === null) {
+        writeError('unknown host');
+        return 1;
+    }
+    const fallbackEvent = parseEvent(process.argv[3]);
+    const input = await readHookInput(process.stdin, 1024 * 1024, 1000);
+    if (!input.ok) {
+        if (typeof process.stdin.destroy === 'function')
+            process.stdin.destroy();
+        writeError(formatDiagnostic(input.diagnostic));
+        process.exit(1);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(input.bytes.toString('utf8'));
+    }
+    catch {
+        writeError('native hook input is not JSON');
+        return 1;
+    }
+    const mapped = mapNativeHookEvent(host, raw, fallbackEvent, process.cwd());
+    if (!mapped.ok) {
+        writeError(formatDiagnostic(mapped.diagnostic));
+        return mapped.event === null ? 1 : 0;
+    }
+    const result = await runHostHook(mapped.input);
+    if (!result.ok) {
+        for (const entry of result.diagnostics) {
+            if (typeof entry === 'object' && entry !== null && 'message' in entry) {
+                const message = entry['message'];
+                if (typeof message === 'string')
+                    writeError(message);
+            }
+        }
+        return result.status === 'invalid' || result.status === 'failed' ? 1 : 0;
+    }
+    const advisory = renderHostHookOutput(host, result);
+    if (advisory !== null)
+        process.stdout.write(advisory);
+    return 0;
+}
+const code = await main();
+process.exitCode = code;

package/dist/hosts/integration/hook.d.ts

@@ -0,0 +1,32 @@
+import type { Diagnostic } from '../../schemas/diagnostics.js';
+import type { HostHookInput, HostHookResult, HostLifecycleEvent, HostName } from '../../schemas/host.js';
+export declare function renderHostHookOutput(host: HostName, result: HostHookResult): string | null;
+export type NativeHookMapping = {
+    readonly ok: true;
+    readonly input: HostHookInput;
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+    readonly host: HostName;
+    readonly event: HostLifecycleEvent | null;
+};
+export declare function mapNativeHookEvent(host: HostName, raw: unknown, _fallbackEvent: HostLifecycleEvent, _fallbackCwd: string | null): NativeHookMapping;
+export interface HostHookOptions {
+    readonly deadlineMs?: number;
+    readonly observedAt?: string;
+    /** Test seam; production uses the monotonic wall clock. */
+    readonly now?: () => number;
+}
+/**
+ * Records one bounded local lifecycle observation. It never reads transcripts,
+ * starts a host/model/network/index, writes a checkpoint, or continues a run.
+ */
+export declare function runHostHook(input: HostHookInput, options?: HostHookOptions): Promise<HostHookResult>;
+export declare function readHookInput(stream: AsyncIterable<Uint8Array | string>, maxBytes?: number, deadlineMs?: number): Promise<{
+    readonly ok: true;
+    readonly bytes: Buffer;
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+}>;
+export declare function readBoundedHookFile(path: string): Promise<Buffer | null>;