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

package/dist/collab/types.d.ts

@@ -0,0 +1,354 @@
+/** Legacy protocol data. Unknown extension fields are preserved without being executed. */
+export interface Identity {
+    agent_id: string;
+    session_id: string;
+    harness: string | null;
+    cwd?: string;
+}
+export interface Coordinator extends Identity {
+    owner_epoch: number;
+    since: string;
+    previous?: Pick<Coordinator, 'agent_id' | 'session_id' | 'owner_epoch'> | null;
+}
+export interface ResourceInput {
+    kind?: string;
+    path?: string;
+    scope?: string;
+    port?: number;
+    value?: string;
+    label?: string;
+    origin?: string;
+    derived?: boolean;
+    shared?: boolean;
+}
+export interface Resource {
+    kind: string;
+    scope: string;
+    key: string;
+    path?: string | null;
+    port?: number | null;
+    existing?: boolean;
+    label: string;
+    origin?: string;
+    derived_from?: string | null;
+}
+export interface Claim extends Resource {
+    claim_id: string;
+    access: string;
+    holder: Identity;
+    resource_epoch: number;
+    claimed_at: string;
+    released_at: string | null;
+    subtask_id: string | null;
+    attempt: number | null;
+    note: string | null;
+    cancel_pending?: boolean;
+    released_by?: string;
+    release_reason?: string | null;
+    transferred_from?: Identity;
+    transferred_at?: string;
+}
+export interface MessageBody {
+    [key: string]: unknown;
+    assignment_ref?: string | null;
+    assignment_digest?: string | null;
+    input_revision?: string | null;
+    approval?: {
+        approved_by: string;
+        reason: string;
+    };
+    status?: string;
+    kind?: string;
+    phase?: string;
+    handoff_id?: string;
+    resources?: string[];
+    reason?: string | null;
+    outputs?: unknown[];
+    native_ref?: unknown;
+    evidence_ref?: string | null;
+    stop_evidence?: unknown;
+}
+export interface Message {
+    [key: string]: unknown;
+    schema: string;
+    message_id: string;
+    type: string;
+    task_id: string;
+    from: Identity;
+    to: Identity;
+    reply_to: string | null;
+    subtask_id: string | null;
+    attempt: number | null;
+    owner_epoch: number | null;
+    created_at: string;
+    content_digest: string | null;
+    body: MessageBody;
+}
+export type MessageInput = Pick<Message, 'type' | 'task_id' | 'from' | 'to'> & Partial<Pick<Message, 'message_id' | 'reply_to' | 'subtask_id' | 'attempt' | 'owner_epoch' | 'created_at' | 'body'>>;
+export interface Transition {
+    from: string | null;
+    to: string;
+    at: string;
+    actor: string;
+    reason: string | null;
+    evidence: unknown;
+    forced?: boolean | undefined;
+}
+export interface NativeBinding {
+    runner: string | null;
+    session_id: string | null;
+    run_id: string | null;
+    mission_id: string | null;
+    observation: string;
+    observed_at: string | null;
+    evidence_ref: string | null;
+    manager?: string;
+    launch_kind?: string;
+    mode?: string;
+    identity_status?: string;
+}
+export interface Attempt {
+    subtask_id: string;
+    attempt: number;
+    state: string;
+    owner_epoch: number | null;
+    assignee: Identity;
+    assignment_message_id: string;
+    assignment_ref: string | null;
+    assignment_digest: string | null;
+    input_revision: string | null;
+    created_at: string;
+    updated_at: string;
+    native: NativeBinding;
+    approval: MessageBody['approval'] | null;
+    transitions: Transition[];
+    closed_at?: string;
+    awaiting?: string;
+    ownership?: string;
+    cancel_requested_at?: string;
+    cwd?: string;
+}
+export interface ResultEntry {
+    schema: string;
+    subtask_id: string;
+    attempt: number;
+    status: string;
+    message_id: string;
+    input_revision: string | null;
+    outputs: unknown[];
+    native_ref: unknown;
+    recorded_at: string;
+    evidence_ref: string | null;
+    classification: string;
+    reason: string | null;
+}
+export interface Uncertainty {
+    uncertainty_id: string;
+    kind: string;
+    subtask_id: string | null;
+    attempt: number | null;
+    detail: string | null;
+    evidence_ref: string | null;
+    resolution_hint: string | null;
+    opened_at: string;
+    resolved_at: string | null;
+    resolution: string | null;
+    resolution_evidence: unknown;
+    auto_restart: boolean;
+    resolved_by?: string;
+    resolution_source?: string;
+}
+export interface OwnershipSnapshot {
+    claim_id: string;
+    holder?: Identity | null;
+    resource_epoch?: number | null;
+    released_at?: string | null;
+    missing?: boolean;
+}
+export interface HandoffStep {
+    [key: string]: unknown;
+    state: string;
+    at: string;
+    actor: string;
+}
+export interface Handoff {
+    schema: string;
+    handoff_id: string;
+    kind: string;
+    subtask_id: string | null;
+    attempt: number | null;
+    from: Identity;
+    to: Identity;
+    resources: string[];
+    ownership_snapshot: OwnershipSnapshot[];
+    state: string;
+    owner_epoch: number;
+    created_at: string;
+    updated_at: string;
+    reason: string | null;
+    steps: HandoffStep[];
+    partial_outputs: unknown[];
+    inflight: unknown[];
+    pending_approvals: unknown[];
+    confirmation_message_id: string | null;
+    snapshot_at?: string;
+    previous_coordinator?: Coordinator | null;
+    resource_transfers?: {
+        claim_id: string;
+        resource_epoch: number;
+        from: Identity;
+    }[];
+}
+export interface AppliedMessage {
+    message_id: string;
+    type: string;
+    subtask_id: string | null;
+    attempt: number | null;
+    from: Identity;
+    to: Identity | null;
+    reply_to: string | null;
+    owner_epoch: number | null;
+    content_digest: string;
+    at: string;
+    applied_at: string;
+    state: string;
+    detail: string;
+    body_kind: string | null;
+}
+export interface Notification {
+    schema: string;
+    kind: string;
+    origin_session: string;
+    target_session: string;
+    depth?: number;
+    task_id: string;
+    subtask_id?: string | null;
+    attempt?: number | null;
+    event?: unknown;
+}
+export interface NotificationEntry {
+    notification_id: string;
+    key: string;
+    kind: string;
+    task_id: string;
+    subtask_id: string | null;
+    attempt: number | null;
+    origin_session: string;
+    target_session: string;
+    depth: number;
+    at: string;
+    decision: string;
+    reason: string | null;
+}
+export interface TaskRecord {
+    [key: string]: unknown;
+    schema: string;
+    task_id: string;
+    domain_id: string;
+    domain_root: string;
+    task_root: string;
+    created_at: string;
+    updated_at: string;
+    state_revision: number;
+    coordinator: Coordinator | null;
+    input_revision: string | null;
+    policy: {
+        [key: string]: unknown;
+    };
+    attempts: Attempt[];
+    messages: AppliedMessage[];
+    claims: Claim[];
+    handoffs: Handoff[];
+    uncertainty: Uncertainty[];
+    results: ResultEntry[];
+    native: unknown[];
+    dispatch_frozen?: boolean;
+    dispatch_released_at?: string;
+    dispatch_released_by?: string;
+    notifications?: NotificationEntry[];
+    notifications_trimmed?: number;
+    launch_reservations?: LaunchReservation[];
+}
+export interface ReservationInput {
+    reservation_id: string;
+    subtask_id: string;
+    attempt: number;
+    kind: string;
+    mode: string;
+    holder: Identity;
+    requested_session_id: string | null;
+    phase?: string;
+    pid?: number;
+    resume_selector?: string | null;
+    transport?: string;
+    [key: string]: unknown;
+}
+export interface LaunchReservation extends ReservationInput {
+    reserved_at: string;
+    released_at: string | null;
+    outcome: string | null;
+    exit_code?: number | null;
+    session_id?: string | null;
+    run_id?: string | null;
+    detail?: string | null;
+    identity_status?: string;
+    expected_identity?: string | null;
+    observed_identity?: string | null;
+}
+export interface Failure {
+    ok: false;
+    reason: string;
+    record?: never;
+    result?: never;
+    commit?: never;
+    [key: string]: unknown;
+}
+export interface UnreadableRecord {
+    task_id: string;
+    __unreadable: true;
+    claims: Claim[];
+}
+export interface Mutation<T = unknown> {
+    ok?: boolean;
+    commit?: boolean;
+    record: TaskRecord;
+    op?: string;
+    summary?: unknown;
+    result?: T;
+    [key: string]: unknown;
+}
+export interface MessageEffect {
+    [key: string]: unknown;
+    entry?: ResultEntry;
+}
+export type TransactionResult<T> = {
+    ok: true;
+    state_revision: number;
+    result: T | null;
+    op: string;
+} | {
+    ok: false;
+    reason: string;
+    [key: string]: unknown;
+};
+export interface LockHolder {
+    schema: string;
+    nonce: string;
+    actor: string;
+    purpose: string;
+    pid: number;
+    hostname: string;
+    acquired_at: string;
+}
+export interface TransactionFile {
+    file: string;
+    revision: unknown;
+    purpose: unknown;
+    actor: unknown;
+}
+export interface Finding {
+    code: string;
+    severity: string;
+    detail: string;
+    [key: string]: unknown;
+}

package/dist/collab/types.js

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

package/dist/collab/validation.d.ts

@@ -0,0 +1,10 @@
+import type { TaskRecord, LockHolder, Message, Notification } from './types.js';
+/** Decode external JSON as unknown; protocol validators establish the usable shape. */
+export declare function object(value: unknown): value is Record<string, unknown>;
+export declare function text(value: unknown): value is string;
+export declare function errorCode(error: unknown): string | undefined;
+export declare function parseJson(text: string): unknown;
+export declare function isTaskRecord(value: unknown): value is TaskRecord;
+export declare function isLockHolder(value: unknown): value is LockHolder;
+export declare function isMessage(value: unknown): value is Message;
+export declare function isNotification(value: unknown): value is Notification;

package/dist/collab/validation.js

@@ -0,0 +1,303 @@
+/** Decode external JSON as unknown; protocol validators establish the usable shape. */
+export function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function text(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function errorCode(error) {
+    return object(error) && typeof error['code'] === 'string'
+        ? error['code']
+        : undefined;
+}
+export function parseJson(text) {
+    return JSON.parse(text);
+}
+const string = (value) => typeof value === 'string';
+const number = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+const nullable = (test) => (value) => value === null || test(value);
+const optional = (test) => (value) => value === undefined || test(value);
+const array = (test) => (value) => Array.isArray(value) && value.every(test);
+function shape(value, fields) {
+    return (object(value) &&
+        Object.entries(fields).every(([key, test]) => test(value[key])));
+}
+const identity = (value) => shape(value, {
+    agent_id: string,
+    session_id: string,
+    harness: nullable(string),
+    cwd: optional(string),
+});
+const coordinator = (value) => identity(value) &&
+    shape(value, {
+        owner_epoch: number,
+        since: string,
+        previous: optional(nullable((item) => shape(item, {
+            agent_id: string,
+            session_id: string,
+            owner_epoch: number,
+        }))),
+    });
+const native = (value) => shape(value, {
+    runner: nullable(string),
+    session_id: nullable(string),
+    run_id: nullable(string),
+    mission_id: nullable(string),
+    observation: string,
+    observed_at: nullable(string),
+    evidence_ref: nullable(string),
+    manager: optional(string),
+    launch_kind: optional(string),
+    mode: optional(string),
+    identity_status: optional(string),
+});
+const transition = (value) => shape(value, {
+    from: nullable(string),
+    to: string,
+    at: string,
+    actor: string,
+    reason: nullable(string),
+});
+const approval = (value) => shape(value, { approved_by: string, reason: string });
+const attempt = (value) => shape(value, {
+    subtask_id: string,
+    attempt: number,
+    state: string,
+    owner_epoch: nullable(number),
+    assignee: identity,
+    assignment_message_id: string,
+    assignment_ref: nullable(string),
+    assignment_digest: nullable(string),
+    input_revision: nullable(string),
+    created_at: string,
+    updated_at: string,
+    native,
+    approval: nullable(approval),
+    transitions: array(transition),
+    closed_at: optional(string),
+    awaiting: optional(string),
+    ownership: optional(string),
+    cancel_requested_at: optional(string),
+    cwd: optional(string),
+});
+const claim = (value) => shape(value, {
+    claim_id: string,
+    key: string,
+    kind: string,
+    scope: string,
+    label: string,
+    path: optional(nullable(string)),
+    port: optional(nullable(number)),
+    origin: optional(string),
+    derived_from: optional(nullable(string)),
+    access: string,
+    holder: identity,
+    resource_epoch: number,
+    claimed_at: string,
+    released_at: nullable(string),
+    subtask_id: nullable(string),
+    attempt: nullable(number),
+    note: nullable(string),
+    cancel_pending: optional((item) => typeof item === 'boolean'),
+    released_by: optional(string),
+    release_reason: optional(nullable(string)),
+    transferred_from: optional(identity),
+    transferred_at: optional(string),
+});
+const appliedMessage = (value) => shape(value, {
+    message_id: string,
+    type: string,
+    subtask_id: nullable(string),
+    attempt: nullable(number),
+    from: identity,
+    to: nullable(identity),
+    reply_to: nullable(string),
+    owner_epoch: nullable(number),
+    content_digest: string,
+    at: string,
+    applied_at: string,
+    state: string,
+    detail: string,
+    body_kind: nullable(string),
+});
+const uncertainty = (value) => shape(value, {
+    uncertainty_id: string,
+    kind: string,
+    subtask_id: nullable(string),
+    attempt: nullable(number),
+    detail: nullable(string),
+    evidence_ref: nullable(string),
+    resolution_hint: nullable(string),
+    opened_at: string,
+    resolved_at: nullable(string),
+    resolution: nullable(string),
+    auto_restart: (item) => typeof item === 'boolean',
+    resolved_by: optional(string),
+    resolution_source: optional(string),
+});
+const result = (value) => shape(value, {
+    schema: string,
+    subtask_id: string,
+    attempt: number,
+    status: string,
+    message_id: string,
+    input_revision: nullable(string),
+    outputs: Array.isArray,
+    recorded_at: string,
+    evidence_ref: nullable(string),
+    classification: string,
+    reason: nullable(string),
+});
+const snapshot = (value) => shape(value, {
+    claim_id: string,
+    holder: optional(nullable(identity)),
+    resource_epoch: optional(nullable(number)),
+    released_at: optional(nullable(string)),
+    missing: optional((item) => typeof item === 'boolean'),
+});
+const handoff = (value) => shape(value, {
+    schema: string,
+    handoff_id: string,
+    kind: string,
+    subtask_id: nullable(string),
+    attempt: nullable(number),
+    from: identity,
+    to: identity,
+    resources: array(string),
+    ownership_snapshot: array(snapshot),
+    state: string,
+    owner_epoch: number,
+    created_at: string,
+    updated_at: string,
+    reason: nullable(string),
+    steps: array((item) => shape(item, { state: string, at: string, actor: string })),
+    partial_outputs: Array.isArray,
+    inflight: Array.isArray,
+    pending_approvals: Array.isArray,
+    confirmation_message_id: nullable(string),
+    snapshot_at: optional(string),
+    previous_coordinator: optional(nullable(coordinator)),
+    resource_transfers: optional(array((item) => shape(item, {
+        claim_id: string,
+        resource_epoch: number,
+        from: identity,
+    }))),
+});
+const notificationEntry = (value) => shape(value, {
+    notification_id: string,
+    key: string,
+    kind: string,
+    task_id: string,
+    subtask_id: nullable(string),
+    attempt: nullable(number),
+    origin_session: string,
+    target_session: string,
+    depth: number,
+    at: string,
+    decision: string,
+    reason: nullable(string),
+});
+const reservation = (value) => shape(value, {
+    reservation_id: string,
+    subtask_id: string,
+    attempt: number,
+    kind: string,
+    mode: string,
+    holder: identity,
+    requested_session_id: nullable(string),
+    reserved_at: string,
+    released_at: nullable(string),
+    outcome: nullable(string),
+    phase: optional(string),
+    pid: optional(number),
+    resume_selector: optional(nullable(string)),
+    transport: optional(string),
+    exit_code: optional(nullable(number)),
+    session_id: optional(nullable(string)),
+    run_id: optional(nullable(string)),
+    detail: optional(nullable(string)),
+    identity_status: optional(string),
+    expected_identity: optional(nullable(string)),
+    observed_identity: optional(nullable(string)),
+});
+export function isTaskRecord(value) {
+    return shape(value, {
+        schema: string,
+        task_id: string,
+        domain_id: string,
+        domain_root: string,
+        task_root: string,
+        created_at: string,
+        updated_at: string,
+        state_revision: number,
+        coordinator: nullable(coordinator),
+        input_revision: nullable(string),
+        policy: object,
+        attempts: array(attempt),
+        messages: array(appliedMessage),
+        claims: array(claim),
+        handoffs: array(handoff),
+        uncertainty: array(uncertainty),
+        results: array(result),
+        native: Array.isArray,
+        dispatch_frozen: optional((item) => typeof item === 'boolean'),
+        dispatch_released_at: optional(string),
+        dispatch_released_by: optional(string),
+        notifications: optional(array(notificationEntry)),
+        notifications_trimmed: optional(number),
+        launch_reservations: optional(array(reservation)),
+    });
+}
+export function isLockHolder(value) {
+    return shape(value, {
+        schema: string,
+        nonce: string,
+        actor: string,
+        purpose: string,
+        pid: number,
+        hostname: string,
+        acquired_at: string,
+    });
+}
+export function isMessage(value) {
+    return shape(value, {
+        schema: string,
+        message_id: string,
+        type: string,
+        task_id: string,
+        from: identity,
+        to: identity,
+        reply_to: nullable(string),
+        subtask_id: nullable(string),
+        attempt: nullable(number),
+        owner_epoch: nullable(number),
+        created_at: string,
+        content_digest: nullable(string),
+        body: (body) => shape(body, {
+            assignment_ref: optional(nullable(string)),
+            assignment_digest: optional(nullable(string)),
+            input_revision: optional(nullable(string)),
+            approval: optional(approval),
+            status: optional(string),
+            kind: optional(string),
+            phase: optional(string),
+            handoff_id: optional(string),
+            resources: optional(array(string)),
+            reason: optional(nullable(string)),
+            outputs: optional(Array.isArray),
+            evidence_ref: optional(nullable(string)),
+        }),
+    });
+}
+export function isNotification(value) {
+    return shape(value, {
+        schema: string,
+        kind: string,
+        origin_session: string,
+        target_session: string,
+        task_id: string,
+        depth: optional(number),
+        subtask_id: optional(nullable(string)),
+        attempt: optional(nullable(number)),
+    });
+}

package/dist/continuity/context.d.ts

@@ -0,0 +1,24 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { Checkpoint } from '../schemas/continuity.js';
+import type { MachineConfig } from '../schemas/machine.js';
+import type { WorkspaceConfig } from '../schemas/workspace.js';
+import type { DiscoveredRepository } from '../workspace/types.js';
+export interface ContinuityWorkspace {
+    readonly root: string;
+    readonly config: WorkspaceConfig;
+    readonly machine: MachineConfig | null;
+    readonly repositories: readonly DiscoveredRepository[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ContinuityWorkspaceResult {
+    readonly ok: boolean;
+    readonly workspace: ContinuityWorkspace | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface RepositorySnapshot {
+    readonly record: Checkpoint['repositories'][number];
+    readonly patchBytes: Buffer | null;
+}
+export declare function loadContinuityWorkspace(root: string): Promise<ContinuityWorkspaceResult>;
+export declare function snapshotRepository(workspace: ContinuityWorkspace, repository: DiscoveredRepository, index: number): Promise<RepositorySnapshot>;
+export declare function continuityDiagnostic(message: string, source: string, hint: string): Diagnostic;