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

package/dist/app/collab-preflight.d.ts

@@ -0,0 +1,34 @@
+import { type Check } from '../collab/preflight.js';
+/**
+ * Public, read-only readiness preflight over the existing collaboration
+ * primitive. This module only reads the two configuration files and lets the
+ * primitive inspect pinned inputs/evidence; it never launches, claims, mutates a
+ * task record, emits input bodies, or refreshes evidence.
+ */
+export declare const COLLAB_PREFLIGHT_SCHEMA = "pappra/collaboration-preflight/1";
+export type CollabPreflightStatus = 'ready' | 'needs_input' | 'invalid';
+export interface CollabPreflightReport {
+    readonly schema: typeof COLLAB_PREFLIGHT_SCHEMA;
+    readonly ok: boolean;
+    readonly status: CollabPreflightStatus;
+    readonly task_id?: string;
+    readonly assignment_id?: string;
+    readonly attempt?: number;
+    readonly checked_at?: string;
+    readonly errors: readonly string[];
+    readonly blockers: readonly Check[];
+    readonly warnings: readonly Check[];
+    readonly limits: readonly string[];
+}
+export interface CollabPreflightOptions {
+    readonly assignmentFile: string;
+    readonly capabilitiesFile: string;
+    readonly maxAgeMinutes?: number;
+    readonly now?: number;
+}
+/**
+ * Runs the existing preflight primitive against caller-supplied absolute files.
+ * The result preserves the primitive's status, blockers, warnings and limits;
+ * `ok` is true only for `ready`. This is reported readiness, not authorization.
+ */
+export declare function runCollaborationPreflight(options: CollabPreflightOptions): CollabPreflightReport;

package/dist/app/collab-preflight.js

@@ -0,0 +1,96 @@
+import { preflight } from '../collab/preflight.js';
+import { readBoundedFile } from './bounded-file.js';
+/**
+ * Public, read-only readiness preflight over the existing collaboration
+ * primitive. This module only reads the two configuration files and lets the
+ * primitive inspect pinned inputs/evidence; it never launches, claims, mutates a
+ * task record, emits input bodies, or refreshes evidence.
+ */
+export const COLLAB_PREFLIGHT_SCHEMA = 'pappra/collaboration-preflight/1';
+const MAX_FILE_BYTES = 1024 * 1024;
+function invalidReport(errors) {
+    return {
+        schema: COLLAB_PREFLIGHT_SCHEMA,
+        ok: false,
+        status: 'invalid',
+        errors,
+        blockers: [],
+        warnings: [],
+        limits: [],
+    };
+}
+/**
+ * Reads one bounded regular JSON file through the shared bounded loader, which
+ * refuses special entries from the initial observation and keeps the open
+ * itself nonblocking/no-follow.
+ */
+function readBoundedJson(file, label) {
+    const read = readBoundedFile(file, MAX_FILE_BYTES);
+    if (!read.ok) {
+        const name = label.toLowerCase();
+        switch (read.code) {
+            case 'path_not_absolute':
+                return { ok: false, message: `${label} path must be absolute.` };
+            case 'symlink':
+                return {
+                    ok: false,
+                    message: `${label} must be a regular file, not a symlink.`,
+                };
+            case 'too_large':
+                return {
+                    ok: false,
+                    message: `${label} exceeds the ${MAX_FILE_BYTES}-byte limit.`,
+                };
+            case 'not_regular':
+                return { ok: false, message: `${label} must be a regular file.` };
+            default:
+                return { ok: false, message: `Cannot read ${name} file.` };
+        }
+    }
+    try {
+        return { ok: true, value: JSON.parse(read.text) };
+    }
+    catch {
+        return { ok: false, message: `${label} is not valid JSON.` };
+    }
+}
+/**
+ * Runs the existing preflight primitive against caller-supplied absolute files.
+ * The result preserves the primitive's status, blockers, warnings and limits;
+ * `ok` is true only for `ready`. This is reported readiness, not authorization.
+ */
+export function runCollaborationPreflight(options) {
+    const maxAge = options.maxAgeMinutes ?? 30;
+    if (!Number.isFinite(maxAge) || maxAge <= 0) {
+        return invalidReport(['Maximum age must be a positive finite number.']);
+    }
+    const assignment = readBoundedJson(options.assignmentFile, 'Assignment');
+    if (!assignment.ok)
+        return invalidReport([assignment.message]);
+    const capabilities = readBoundedJson(options.capabilitiesFile, 'Capabilities');
+    if (!capabilities.ok)
+        return invalidReport([capabilities.message]);
+    const result = preflight(assignment.value, capabilities.value, {
+        now: options.now ?? Date.now(),
+        maxAgeMinutes: maxAge,
+    });
+    const hasTask = 'task_id' in result;
+    const status = result.status;
+    return {
+        schema: COLLAB_PREFLIGHT_SCHEMA,
+        ok: status === 'ready',
+        status,
+        ...(hasTask
+            ? {
+                task_id: result.task_id,
+                assignment_id: result.assignment_id,
+                attempt: result.attempt,
+                checked_at: result.checked_at,
+            }
+            : {}),
+        errors: result.errors,
+        blockers: result.blockers,
+        warnings: result.warnings,
+        limits: 'limits' in result ? result.limits : [],
+    };
+}

package/dist/app/collab-recovery-executor.d.ts

@@ -0,0 +1,161 @@
+import { type RecoveryAction, type RecoveryPolicy } from './collab-recovery-projection.js';
+import type { Identity } from '../collab/types.js';
+import { type CommandRunner, type HerdrTransport } from './collab-notify.js';
+export declare const COLLAB_RECOVERY_EXECUTOR_SCHEMA: 'pappra/collab-recovery-executor/1';
+export type RecoveryExecutionMode = 'plan' | 'apply';
+/** A continuation target is an already-authorised, verified existing session; never a fresh process. */
+export interface RecoveryContinuationTarget {
+    readonly agent_id: string;
+    readonly session_id: string;
+    readonly harness: string | null;
+    readonly pane_id: string | null;
+}
+/** The admitted task participant a dispatch is bound to; verified against the live Herdr participant. */
+export interface RecoveryBindingParticipant {
+    readonly agent: string;
+    readonly session_id: string;
+    readonly cwd: string | null;
+    readonly pane_id: string | null;
+    readonly harness: string | null;
+}
+export interface RecoveryTaskBinding {
+    readonly digest: string;
+    readonly participant: RecoveryBindingParticipant;
+}
+export interface RecoveryExpectedSession {
+    readonly session_id: string;
+    readonly cwd: string | null;
+    /** Digest of the canonical task-local binding file, not a caller-created participant hash. */
+    readonly binding_digest: string | null;
+    readonly target_agent?: string | null;
+    readonly pane_id?: string | null;
+    readonly harness?: string | null;
+    /** Absolute path to the bounded, task-local pappra/collab-binding/1 file. */
+    readonly binding_ref?: string | null;
+    /** Populated only from the file whose digest and task identity were verified. */
+    readonly binding?: RecoveryTaskBinding | null;
+}
+export type RecoveryCauseReason = 'resume_unfinished' | 'progress_review';
+/**
+ * The durable, canonical cause a recovery wake is issued for. The reservation key derives from the cause
+ * identity (task/actor/role/attempt/input/epoch + admitted answer/report identity), NOT from the caller
+ * request id — a different request id for the same cause must not create a second right to send.
+ */
+export interface RecoveryCause {
+    readonly reason: RecoveryCauseReason;
+    readonly task_id: string | null;
+    readonly role: RecoveryPolicy['role'];
+    readonly actor: {
+        readonly agent_id: string;
+        readonly session_id: string;
+    };
+    readonly action_key: string;
+    readonly subtask_id: string | null;
+    readonly attempt: number | null;
+    readonly input_revision: string | null;
+    readonly report_digest: string | null;
+    readonly owner_epoch: number;
+    /** Correlates callers only; it is not part of the dedup key. */
+    readonly request_id: string;
+    readonly is_recovery_wake: true;
+}
+export type RecoveryControllerKind = 'continue' | 'review';
+export interface RecoveryControllerRequest {
+    readonly kind: RecoveryControllerKind;
+    readonly taskRoot: string;
+    readonly target: RecoveryContinuationTarget;
+    readonly expected: RecoveryExpectedSession | null;
+    readonly cause: RecoveryCause;
+    /** A recovery wake message, deliberately distinguishable from a fresh coordinator instruction. */
+    readonly text: string;
+    /**
+     * Re-checks current task authority AFTER the controller's awaited live lookup and immediately before the
+     * prompt, closing the lookup-to-send gap. A `false` result must stop the controller before any effect.
+     */
+    readonly confirmAuthority?: () => Promise<boolean>;
+}
+export type RecoveryControllerDisposition = 'submitted' | 'deferred' | 'refused' | 'unknown' | 'failed' | 'unavailable';
+/**
+ * Honest effect observation.
+ * - `none`: the controller has supported evidence that NO effect was issued (safe to retry).
+ * - `queued`: a submission/queue acceptance only — never consumption or completion; stop.
+ * - `applied`: a supported positive acknowledgement (still not task completion); stop.
+ * - `unknown`: a possible/ambiguous effect (a throw, a post-submit failure) — stop, never retry.
+ */
+export type RecoveryEffectObservation = 'queued' | 'applied' | 'none' | 'unknown';
+export interface RecoveryControllerResult {
+    readonly disposition: RecoveryControllerDisposition;
+    readonly detail: string | null;
+    readonly observation: RecoveryEffectObservation;
+}
+/**
+ * The only component permitted to touch a live host. Injected by the CLI/host controller (real Herdr
+ * transport with exact live-target verification) or by tests. A thrown controller is treated as a possible
+ * effect (observation `unknown`), never retried.
+ */
+export interface RecoveryController {
+    readonly id: string;
+    perform(request: RecoveryControllerRequest): Promise<RecoveryControllerResult>;
+}
+export interface RecoveryExecutionRequest {
+    readonly taskRoot: string;
+    readonly planFile: string;
+    readonly self: Identity;
+    readonly policy: RecoveryPolicy;
+    /** Stable caller correlation id; it does not widen the durable cause dedup. */
+    readonly requestId: string;
+    readonly mode: RecoveryExecutionMode;
+    readonly expectedSession?: RecoveryExpectedSession | null;
+    readonly maxRetries?: number;
+}
+export interface RecoveryExecutionDeps {
+    readonly controller: RecoveryController;
+    readonly now?: () => number;
+    /** Bounded backoff sleeper; defaults to a real timer. Tests inject a synchronous stub. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export type RecoveryExecutionStatus = 'planned' | 'applied' | 'noop' | 'blocked' | 'deferred' | 'unknown' | 'refused';
+export interface ReservationView {
+    readonly key: string;
+    readonly path: string;
+    readonly created: boolean;
+    readonly outcome: string | null;
+}
+export interface RecoveryExecutionResult {
+    readonly schema: typeof COLLAB_RECOVERY_EXECUTOR_SCHEMA;
+    readonly ok: boolean;
+    readonly status: RecoveryExecutionStatus;
+    readonly action: RecoveryAction | null;
+    readonly cause: RecoveryCause | null;
+    readonly reservation: ReservationView | null;
+    readonly performed: RecoveryControllerResult | null;
+    readonly retries: number;
+    readonly notes: readonly string[];
+    readonly limits: readonly string[];
+}
+/**
+ * Execute one durable, idempotent recovery step. `plan` validates and reports the intended action with
+ * zero effect; `apply` reserves atomically by canonical cause through no-follow inode-anchored sidecars
+ * before issuing a single supported continuation/review wake through the injected (exact live-target
+ * verifying) controller. Authority, namespace, sidecar anchors and the live target are re-validated before
+ * every attempt and again inside the controller after its live lookup; only explicit known no-effect
+ * failures retry within a bounded budget, and a possible/ambiguous effect stops as unknown. Persistence
+ * failures become structured outcomes and never throw out of the host callback.
+ */
+export declare function executeRecovery(request: RecoveryExecutionRequest, deps: RecoveryExecutionDeps): Promise<RecoveryExecutionResult>;
+/**
+ * Concrete controller for one visible Herdr target. Apply requires a complete native identity and a bounded,
+ * digest-pinned task-local binding that admits the acting participant and target. The live session identity,
+ * cwd, pane and harness must all match exactly. Task authority and the binding are re-read after the awaited
+ * live lookup and immediately before the prompt. It never spawns a process.
+ */
+export declare function herdrRecoveryController(transport: HerdrTransport, target: {
+    readonly agent: string;
+}): RecoveryController;
+/** Build a Herdr-backed recovery controller from the ambient environment and a target agent. */
+export declare function createHerdrRecoveryController(options: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly run?: CommandRunner;
+}, target: {
+    readonly agent: string;
+}): RecoveryController;