@phyzess/pappra 0.1.0-beta.14 → 0.1.0-beta.19

package/dist/app/shell-readiness.js

@@ -0,0 +1,368 @@
+export const SHELL_READINESS_BUDGET_MS = 10_000;
+export const SHELL_READINESS_INTERVAL_MS = 100;
+export const SHELL_READINESS_MAX_SAMPLES = 100;
+const MAX_CAPTURED_PROCESSES = 8;
+const SHELL_NAMES = new Set([
+    'sh',
+    'bash',
+    'dash',
+    'zsh',
+    'fish',
+    'ksh',
+    'mksh',
+    'csh',
+    'tcsh',
+    'elvish',
+    'xonsh',
+    'nu',
+    'pwsh',
+    'powershell',
+    'cmd',
+]);
+const AGENT_NAMES = new Set([
+    'pi',
+    'codex',
+    'claude',
+    'gemini',
+    'cursor',
+    'devin',
+    'agy',
+    'cline',
+    'omp',
+    'opencode',
+    'copilot',
+    'kimi',
+    'kiro',
+    'droid',
+    'amp',
+    'grok',
+    'hermes',
+    'kilo',
+    'qodercli',
+    'qwen',
+    'letta',
+    'maki',
+    'muse',
+]);
+function normalizedName(value) {
+    const tail = value.split(/[\\/]/).at(-1) ?? value;
+    return tail
+        .replace(/^-+/, '')
+        .replace(/\.exe$/i, '')
+        .toLowerCase();
+}
+function validNumber(value) {
+    return value !== null && Number.isSafeInteger(value) && value > 0;
+}
+function identityCode(pane, expected) {
+    if (pane.paneId !== expected.paneId)
+        return 'pane_id_mismatch';
+    if (pane.workspaceId !== expected.workspaceId)
+        return 'workspace_id_mismatch';
+    if (pane.terminalId !== expected.terminalId)
+        return 'terminal_id_mismatch';
+    if (pane.cwd === null)
+        return 'pane_cwd_missing';
+    return pane.cwd === expected.cwd ? null : 'pane_cwd_mismatch';
+}
+function sampleProcessFacts(processInfo) {
+    if (!Array.isArray(processInfo.foregroundProcesses))
+        return {
+            processes: [],
+            truncated: 0,
+            error: 'foreground_processes_malformed',
+        };
+    const processes = [];
+    for (const process of processInfo.foregroundProcesses) {
+        if (!validNumber(process.pid) ||
+            typeof process.name !== 'string' ||
+            process.name.length === 0)
+            return {
+                processes: [],
+                truncated: 0,
+                error: 'foreground_process_fact_malformed',
+            };
+        processes.push({ pid: process.pid, name: normalizedName(process.name) });
+    }
+    return {
+        processes: processes.slice(0, MAX_CAPTURED_PROCESSES),
+        truncated: Math.max(0, processes.length - MAX_CAPTURED_PROCESSES),
+        error: null,
+    };
+}
+function classifyProcessInfo(processInfo) {
+    const shellPid = processInfo.shellPid;
+    const group = processInfo.foregroundProcessGroupId;
+    const facts = sampleProcessFacts(processInfo);
+    const stateBase = {
+        shellPid: validNumber(shellPid) ? shellPid : null,
+        group: validNumber(group) ? group : null,
+        shellName: null,
+        processes: facts.processes,
+        processesTruncated: facts.truncated,
+    };
+    if (shellPid !== null && !validNumber(shellPid))
+        return { ...stateBase, state: 'failed', code: 'shell_pid_malformed' };
+    if (group !== null && !validNumber(group))
+        return {
+            ...stateBase,
+            state: 'failed',
+            code: 'foreground_group_malformed',
+        };
+    if (facts.error !== null)
+        return { ...stateBase, state: 'failed', code: facts.error };
+    if (shellPid === null)
+        return { ...stateBase, state: 'unknown', code: 'shell_pid_missing' };
+    if (group === null)
+        return { ...stateBase, state: 'unknown', code: 'foreground_group_missing' };
+    if (group !== shellPid)
+        return {
+            ...stateBase,
+            state: 'not_ready',
+            code: 'foreground_group_not_shell',
+        };
+    if (processInfo.foregroundProcesses.length === 0)
+        return {
+            ...stateBase,
+            state: 'unknown',
+            code: 'foreground_processes_empty',
+        };
+    if (processInfo.foregroundProcesses.some((process) => process.pid !== shellPid)) {
+        const agent = facts.processes.find((process) => AGENT_NAMES.has(process.name));
+        return agent === undefined
+            ? { ...stateBase, state: 'not_ready', code: 'extra_foreground_process' }
+            : { ...stateBase, state: 'failed', code: `existing_agent:${agent.name}` };
+    }
+    const shellName = facts.processes[0]?.name ?? null;
+    if (shellName === null || !SHELL_NAMES.has(shellName))
+        return {
+            ...stateBase,
+            state: 'not_ready',
+            code: 'unrecognized_shell',
+            shellName,
+        };
+    return {
+        ...stateBase,
+        state: 'ready',
+        code: null,
+        shellName,
+    };
+}
+/**
+ * Verifies the installed Herdr available-shell predicate for one already owned pane.
+ * Process readiness is bounded local polling in the caller's single apply operation;
+ * it is not an event signal, a model wakeup, or an agent-completion wait.
+ */
+export async function verifyAvailableShell(ops, identity, options = {}) {
+    const clock = options.clock ?? Date.now;
+    const sleeper = options.sleeper ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const shouldAbort = options.shouldAbort ?? (() => false);
+    const budgetMs = options.budgetMs ?? SHELL_READINESS_BUDGET_MS;
+    const intervalMs = options.intervalMs ?? SHELL_READINESS_INTERVAL_MS;
+    const maxSamples = options.maxSamples ?? SHELL_READINESS_MAX_SAMPLES;
+    if (!Number.isSafeInteger(budgetMs) ||
+        budgetMs < 1 ||
+        budgetMs > SHELL_READINESS_BUDGET_MS)
+        return immediateFailure(identity, 'budget_invalid');
+    if (!Number.isSafeInteger(intervalMs) ||
+        intervalMs < 1 ||
+        intervalMs > SHELL_READINESS_INTERVAL_MS)
+        return immediateFailure(identity, 'interval_invalid');
+    if (!Number.isSafeInteger(maxSamples) ||
+        maxSamples < 1 ||
+        maxSamples > SHELL_READINESS_MAX_SAMPLES)
+        return immediateFailure(identity, 'sample_limit_invalid');
+    const started = clock();
+    const deadline = started + budgetMs;
+    let attempts = 0;
+    let pinnedShellPid = null;
+    let latest = null;
+    const samples = [];
+    const result = (state, code, pane) => ({
+        status: state,
+        code,
+        evidence: {
+            state,
+            code,
+            attempts,
+            elapsed_ms: Math.max(0, clock() - started),
+            pane_id: pane.paneId,
+            workspace_id: pane.workspaceId,
+            terminal_id: pane.terminalId,
+            cwd: pane.cwd,
+            shell_pid: pinnedShellPid ?? latest?.shell_pid ?? null,
+            foreground_process_group_id: latest?.foreground_process_group_id ?? null,
+            shell_name: latest?.shell_name ?? null,
+            last_state: latest?.state ?? 'not_observed',
+            last_code: latest?.code ?? null,
+            limits: {
+                budget_ms: budgetMs,
+                interval_ms: intervalMs,
+                max_samples: maxSamples,
+                samples_truncated: Math.max(0, attempts - samples.length),
+            },
+            samples: [...samples],
+        },
+    });
+    const recordSample = (sample) => {
+        latest = sample;
+        if (samples.length < maxSamples)
+            samples.push(sample);
+    };
+    const terminal = (state, code) => result(state, code, identity);
+    const checkAbort = () => shouldAbort() ? terminal('aborted', 'abort_requested') : null;
+    const checkDeadline = (code) => clock() >= deadline ? terminal('timeout', code) : null;
+    const initialAbort = checkAbort();
+    if (initialAbort !== null)
+        return initialAbort;
+    const beforeDeadline = checkDeadline('deadline_before_identity');
+    if (beforeDeadline !== null)
+        return beforeDeadline;
+    const initial = await ops.paneGet(identity.paneId, Math.max(1, deadline - clock()));
+    const afterInitialAbort = checkAbort();
+    if (afterInitialAbort !== null)
+        return afterInitialAbort;
+    const afterInitialDeadline = checkDeadline('deadline_after_initial_identity');
+    if (afterInitialDeadline !== null)
+        return afterInitialDeadline;
+    if (!initial.ok)
+        return terminal(initial.status === 'unknown' ? 'unknown' : 'failed', `initial_identity:${initial.code}`);
+    const initialIdentity = identityCode(initial.value, identity);
+    if (initialIdentity !== null)
+        return terminal('failed', initialIdentity);
+    if (initial.value.agent !== null)
+        return terminal('failed', 'existing_agent');
+    for (;;) {
+        const beforeAbort = checkAbort();
+        if (beforeAbort !== null)
+            return beforeAbort;
+        const beforeSampleDeadline = checkDeadline('deadline_before_process_info');
+        if (beforeSampleDeadline !== null)
+            return beforeSampleDeadline;
+        if (attempts >= maxSamples)
+            return terminal('timeout', 'sample_limit_reached');
+        attempts += 1;
+        const sampleStart = clock();
+        const snapshot = await ops.paneProcessInfo(identity.paneId, Math.max(1, deadline - clock()));
+        const afterSampleAbort = checkAbort();
+        if (afterSampleAbort !== null)
+            return afterSampleAbort;
+        const afterSampleDeadline = checkDeadline('deadline_after_process_info');
+        if (afterSampleDeadline !== null)
+            return afterSampleDeadline;
+        if (!snapshot.ok) {
+            const status = snapshot.status === 'unknown' ? 'unknown' : 'failed';
+            recordSample({
+                elapsed_ms: Math.max(0, sampleStart - started),
+                state: status === 'unknown' ? 'unknown' : 'failed',
+                code: snapshot.code,
+                shell_pid: pinnedShellPid,
+                foreground_process_group_id: null,
+                shell_name: null,
+                foreground_processes: [],
+                processes_truncated: 0,
+            });
+            return terminal(status, `process_info:${snapshot.code}`);
+        }
+        const processInfo = snapshot.value;
+        if (processInfo.paneId !== identity.paneId)
+            return terminal('failed', 'pane_id_mismatch');
+        const classified = classifyProcessInfo(processInfo);
+        if (classified.shellPid !== null) {
+            if (pinnedShellPid === null)
+                pinnedShellPid = classified.shellPid;
+            else if (pinnedShellPid !== classified.shellPid) {
+                recordSample({
+                    elapsed_ms: Math.max(0, sampleStart - started),
+                    state: 'failed',
+                    code: 'shell_incarnation_drift',
+                    shell_pid: classified.shellPid,
+                    foreground_process_group_id: classified.group,
+                    shell_name: classified.shellName,
+                    foreground_processes: classified.processes,
+                    processes_truncated: classified.processesTruncated,
+                });
+                return terminal('failed', 'shell_incarnation_drift');
+            }
+        }
+        const sample = {
+            elapsed_ms: Math.max(0, sampleStart - started),
+            state: classified.state,
+            code: classified.code,
+            shell_pid: classified.shellPid,
+            foreground_process_group_id: classified.group,
+            shell_name: classified.shellName,
+            foreground_processes: classified.processes,
+            processes_truncated: classified.processesTruncated,
+        };
+        recordSample(sample);
+        if (classified.state === 'failed')
+            return terminal('failed', classified.code ?? 'process_facts_invalid');
+        if (classified.state === 'ready') {
+            const beforeFinalAbort = checkAbort();
+            if (beforeFinalAbort !== null)
+                return beforeFinalAbort;
+            const beforeFinalDeadline = checkDeadline('deadline_before_final_identity');
+            if (beforeFinalDeadline !== null)
+                return beforeFinalDeadline;
+            const finalIdentity = await ops.paneGet(identity.paneId, Math.max(1, deadline - clock()));
+            const afterFinalAbort = checkAbort();
+            if (afterFinalAbort !== null)
+                return afterFinalAbort;
+            const afterFinalDeadline = checkDeadline('deadline_after_final_identity');
+            if (afterFinalDeadline !== null)
+                return afterFinalDeadline;
+            if (!finalIdentity.ok)
+                return terminal(finalIdentity.status === 'unknown' ? 'unknown' : 'failed', `final_identity:${finalIdentity.code}`);
+            const finalCode = identityCode(finalIdentity.value, identity);
+            if (finalCode !== null)
+                return terminal('failed', finalCode);
+            if (finalIdentity.value.agent !== null)
+                return terminal('failed', 'agent_appeared_before_start');
+            return result('ready', null, identity);
+        }
+        if (attempts >= maxSamples)
+            return terminal('timeout', 'sample_limit_reached');
+        const remaining = deadline - clock();
+        if (remaining <= 0)
+            return terminal('timeout', classified.state === 'unknown'
+                ? 'deadline_unknown'
+                : 'deadline_not_ready');
+        await sleeper(Math.min(intervalMs, remaining));
+        const afterSleepAbort = checkAbort();
+        if (afterSleepAbort !== null)
+            return afterSleepAbort;
+        const afterSleepDeadline = checkDeadline('deadline_after_wait');
+        if (afterSleepDeadline !== null)
+            return afterSleepDeadline;
+    }
+}
+function immediateFailure(identity, code) {
+    return {
+        status: 'failed',
+        code,
+        evidence: {
+            state: 'failed',
+            code,
+            attempts: 0,
+            elapsed_ms: 0,
+            pane_id: identity.paneId,
+            workspace_id: identity.workspaceId,
+            terminal_id: identity.terminalId,
+            cwd: identity.cwd,
+            shell_pid: null,
+            foreground_process_group_id: null,
+            shell_name: null,
+            last_state: 'not_observed',
+            last_code: null,
+            limits: {
+                budget_ms: 0,
+                interval_ms: 0,
+                max_samples: 0,
+                samples_truncated: 0,
+            },
+            samples: [],
+        },
+    };
+}

package/dist/app/task-pin.d.ts

@@ -1,23 +1,2 @@
-export declare const TASK_PIN_SCHEMA = "pappra/task-pin/1";
-export interface TaskPin {
-    readonly schema: typeof TASK_PIN_SCHEMA;
-    readonly taskId: string;
-    readonly pinnedAt: string;
-}
-export interface TaskPinFailure {
-    readonly ok: false;
-    readonly message: string;
-}
-export declare function readTaskPin(root: string): Promise<TaskPin | null>;
-export declare function pinTask(root: string, taskId: string): Promise<TaskPin | TaskPinFailure>;
-export declare function unpinTask(root: string): Promise<{
-    ok: true;
-}>;
-/**
- * Toggles the workspace-level auto-resume switch. The hook only injects a resume
- * packet when this switch is on and a task pin exists; neither is inferred.
- */
-export declare function setAutoResume(root: string, enabled: boolean): Promise<{
-    ok: true;
-} | TaskPinFailure>;
-export declare function readAutoResume(root: string): Promise<boolean>;
+/** Workspace task selection is a continuity capability. */
+export * from '../continuity/task-pin.js';

package/dist/app/task-pin.js

@@ -1,113 +1,2 @@
-import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { readTextFileBounded } from '../infra/fs.js';
-import { workspaceConfigSchema } from '../schemas/workspace.js';
-export const TASK_PIN_SCHEMA = 'pappra/task-pin/1';
-const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-function pinPath(root) {
-    return join(root, '.pappra', 'local', 'current-task');
-}
-export async function readTaskPin(root) {
-    const read = await readTextFileBounded(pinPath(root), 64 * 1024);
-    if (!read.ok)
-        return null;
-    try {
-        const value = JSON.parse(read.value.text);
-        if (typeof value !== 'object' ||
-            value === null ||
-            !('schema' in value) ||
-            value.schema !== TASK_PIN_SCHEMA ||
-            !('taskId' in value) ||
-            typeof value.taskId !== 'string' ||
-            !TASK_ID.test(value.taskId)) {
-            return null;
-        }
-        return value;
-    }
-    catch {
-        return null;
-    }
-}
-export async function pinTask(root, taskId) {
-    if (!TASK_ID.test(taskId)) {
-        return {
-            ok: false,
-            message: 'task id must be a short identifier (letters, digits, dot, dash, underscore).',
-        };
-    }
-    const pin = {
-        schema: TASK_PIN_SCHEMA,
-        taskId,
-        pinnedAt: new Date().toISOString(),
-    };
-    const target = pinPath(root);
-    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
-    const temporary = `${target}.tmp-${randomUUID()}`;
-    await writeFile(temporary, `${JSON.stringify(pin, null, 2)}\n`, {
-        mode: 0o600,
-    });
-    await rename(temporary, target);
-    return pin;
-}
-export async function unpinTask(root) {
-    const target = pinPath(root);
-    const { rm } = await import('node:fs/promises');
-    await rm(target, { force: true });
-    return { ok: true };
-}
-/**
- * Toggles the workspace-level auto-resume switch. The hook only injects a resume
- * packet when this switch is on and a task pin exists; neither is inferred.
- */
-export async function setAutoResume(root, enabled) {
-    const configPath = join(root, '.pappra', 'workspace.json');
-    const read = await readTextFileBounded(configPath, 1024 * 1024);
-    if (!read.ok) {
-        return { ok: false, message: read.message };
-    }
-    let raw;
-    try {
-        raw = JSON.parse(read.value.text);
-    }
-    catch (error) {
-        return {
-            ok: false,
-            message: `workspace.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-    const parsed = workspaceConfigSchema.safeParse({
-        ...(typeof raw === 'object' && raw !== null ? raw : {}),
-        continuity: { autoResume: enabled },
-    });
-    if (!parsed.success) {
-        return {
-            ok: false,
-            message: `workspace.json rejected the continuity switch: ${parsed.error.issues[0]?.message ?? 'invalid'}`,
-        };
-    }
-    const backup = join(root, '.pappra', 'local', 'backups', `task-pin-${randomUUID()}`, 'workspace.json');
-    await mkdir(dirname(backup), { recursive: true, mode: 0o700 });
-    await writeFile(backup, read.value.text, { mode: 0o600 });
-    const temporary = `${configPath}.tmp-${randomUUID()}`;
-    await writeFile(temporary, `${JSON.stringify(parsed.data, null, 2)}\n`);
-    await rename(temporary, configPath);
-    return { ok: true };
-}
-export async function readAutoResume(root) {
-    const read = await readFile(join(root, '.pappra', 'workspace.json'), 'utf8');
-    try {
-        const raw = JSON.parse(read);
-        if (typeof raw !== 'object' || raw === null || !('continuity' in raw)) {
-            return false;
-        }
-        const continuity = raw.continuity;
-        return (typeof continuity === 'object' &&
-            continuity !== null &&
-            'autoResume' in continuity &&
-            continuity.autoResume === true);
-    }
-    catch {
-        return false;
-    }
-}
+/** Workspace task selection is a continuity capability. */
+export * from '../continuity/task-pin.js';

package/dist/cli/collaboration-router.d.ts

@@ -0,0 +1,17 @@
+import type { CliOutput } from './output.js';
+import { type CliValues } from './options.js';
+import type { getPackageInfo } from '../package-info.js';
+/** Everything the collaboration router needs from one parsed command line. */
+export interface CollaborationRouteRequest {
+    readonly values: CliValues;
+    /** The resolved `collab` action, e.g. `message:send` or `role-run`. */
+    readonly action: string | null;
+    /** Raw argv, for duplicate-flag detection the parser cannot observe. */
+    readonly args: readonly string[];
+    readonly info: ReturnType<typeof getPackageInfo>;
+    readonly rpcRequestTimeout: string | undefined;
+    readonly rpcOperationTimeout: string | undefined;
+    readonly output: CliOutput;
+    readonly json: boolean;
+}
+export declare function routeCollaboration(request: CollaborationRouteRequest): Promise<number>;