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

package/dist/collab/notify.js

@@ -0,0 +1,140 @@
+import { text, isNotification } from './validation.js';
+import { createNonce, nowIso } from './store.js';
+import { canonicalJson } from './envelope.js';
+// Bounded admission for hook/plugin notifications.
+//
+// Why this exists: a hook that fires on every event can wake a model in a loop, a
+// session can notify itself, and an approval request must never be answered by another
+// agent. This gate answers one question — may this notification be delivered? — and it
+// records the decision in the task record. It does not send anything.
+export const DEFAULT_LIMITS = Object.freeze({
+    per_key: 3,
+    window_ms: 60_000,
+    max_depth: 2,
+    max_entries: 200,
+});
+export const NOTIFICATION_KINDS = Object.freeze([
+    'task_event',
+    'turn_complete',
+    'tool_failure',
+    'approval_request',
+    'status_probe',
+    'handoff_note',
+]);
+function assert(condition, field) {
+    if (!condition)
+        throw new Error(`Invalid notification field: ${field}`);
+}
+export function validateNotification(notification) {
+    assert(isNotification(notification), 'notification');
+    assert(notification.schema === 'harness-collab/notification/1', 'notification.schema');
+    assert(text(notification.kind), 'notification.kind');
+    assert(NOTIFICATION_KINDS.includes(notification.kind), 'notification.kind value');
+    assert(text(notification.origin_session), 'notification.origin_session');
+    assert(text(notification.target_session), 'notification.target_session');
+    assert(Number.isSafeInteger(notification.depth ?? 0) &&
+        (notification.depth ?? 0) >= 0, 'notification.depth');
+    assert(text(notification.task_id), 'notification.task_id');
+    return notification;
+}
+/** Stable identity of a notification: everything that decides whether it is the same one. */
+export function notificationKey(notification) {
+    return canonicalJson({
+        kind: notification.kind,
+        task_id: notification.task_id,
+        subtask_id: notification.subtask_id ?? null,
+        attempt: notification.attempt ?? null,
+        origin_session: notification.origin_session,
+        event: notification.event ?? null,
+    });
+}
+/**
+ * Decide whether to deliver. Returns `{admit, reason, human_required}`. An approval
+ * request is recorded but never answerable by another agent, and no decision here
+ * triggers a send, a retry or a model wake.
+ */
+export function admitNotification(record, notification, { clock = Date.now(), limits = {} } = {}) {
+    validateNotification(notification);
+    const effective = { ...DEFAULT_LIMITS, ...limits };
+    const at = nowIso(clock);
+    const key = notificationKey(notification);
+    const entry = {
+        notification_id: `note-${createNonce()}`,
+        key,
+        kind: notification.kind,
+        task_id: notification.task_id,
+        subtask_id: notification.subtask_id ?? null,
+        attempt: notification.attempt ?? null,
+        origin_session: notification.origin_session,
+        target_session: notification.target_session,
+        depth: notification.depth ?? 0,
+        at,
+        decision: 'admitted',
+        reason: null,
+    };
+    const log = record.notifications ?? (record.notifications = []);
+    if (notification.kind === 'approval_request') {
+        // Recorded and surfaced, never answered, and never used to wake another model.
+        log.push({
+            ...entry,
+            decision: 'recorded',
+            reason: 'approval_requests_are_not_auto_answered',
+        });
+        return {
+            admit: false,
+            reason: 'approval_requests_are_not_auto_answered',
+            human_required: true,
+            key,
+        };
+    }
+    if (notification.origin_session === notification.target_session) {
+        log.push({ ...entry, decision: 'dropped', reason: 'self_notification' });
+        return {
+            admit: false,
+            reason: 'self_notification',
+            human_required: false,
+            key,
+        };
+    }
+    if ((notification.depth ?? 0) > effective.max_depth) {
+        log.push({
+            ...entry,
+            decision: 'dropped',
+            reason: 'recursion_depth_exceeded',
+        });
+        return {
+            admit: false,
+            reason: 'recursion_depth_exceeded',
+            human_required: false,
+            key,
+        };
+    }
+    const windowStart = clock - effective.window_ms;
+    const recent = log.filter((item) => item.key === key &&
+        item.decision === 'admitted' &&
+        Number.isFinite(Date.parse(item.at)) &&
+        Date.parse(item.at) >= windowStart);
+    if (recent.length >= effective.per_key) {
+        log.push({ ...entry, decision: 'dropped', reason: 'rate_limited' });
+        return {
+            admit: false,
+            reason: 'rate_limited',
+            delivered_in_window: recent.length,
+            key,
+        };
+    }
+    log.push(entry);
+    return { admit: true, reason: null, human_required: false, key };
+}
+/** Keep the notification log bounded; the newest entries are the ones that matter. */
+export function trimNotificationLog(record, { limits = {} } = {}) {
+    const effective = { ...DEFAULT_LIMITS, ...limits };
+    if (!Array.isArray(record.notifications))
+        return 0;
+    const excess = record.notifications.length - effective.max_entries;
+    if (excess <= 0)
+        return 0;
+    record.notifications = record.notifications.slice(excess);
+    record.notifications_trimmed = (record.notifications_trimmed ?? 0) + excess;
+    return excess;
+}

package/dist/collab/preflight.d.ts

@@ -0,0 +1,31 @@
+import type { Assignment, CapabilityCard } from './contracts.js';
+export interface Check {
+    code: string;
+    capability?: string;
+}
+export declare function validateContractAndCard(contract: Assignment, card: CapabilityCard): void;
+/** Validate reported readiness, not authorization, resource locking, or task completion. */
+export declare function preflight(contract: Assignment, card: CapabilityCard, { now, maxAgeMinutes }?: {
+    maxAgeMinutes?: number | undefined;
+    now?: number | undefined;
+}): {
+    status: string;
+    errors: string[];
+    blockers: never[];
+    warnings: never[];
+    task_id?: never;
+    assignment_id?: never;
+    attempt?: never;
+    checked_at?: never;
+    limits?: never;
+} | {
+    status: string;
+    task_id: string;
+    assignment_id: string;
+    attempt: number;
+    checked_at: string;
+    errors: never[];
+    blockers: Check[];
+    warnings: Check[];
+    limits: string[];
+};

package/dist/collab/preflight.js

@@ -0,0 +1,271 @@
+import { object, text } from './validation.js';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fingerprintSkill } from './fingerprint.js';
+const record = object;
+const digest = (value) => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const positive = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+const states = new Set([
+    'declared',
+    'discovered',
+    'callable',
+    'verified',
+    'disabled',
+    'unknown',
+]);
+const readyStates = new Set(['callable', 'verified']);
+function assert(condition, field) {
+    if (!condition)
+        throw new Error(`Invalid field: ${field}`);
+}
+function requirements(value, field) {
+    assert(record(value), field);
+    assert(Array.isArray(value.skills) && Array.isArray(value.tools), field);
+    const keys = new Set();
+    for (const skill of value.skills) {
+        assert(record(skill) && text(skill.id) && digest(skill.bundle_digest), `${field}.skills`);
+        assert(!keys.has(`skill:${skill.id}`), `${field}.skills duplicate`);
+        keys.add(`skill:${skill.id}`);
+    }
+    for (const tool of value.tools) {
+        assert(text(tool) && !keys.has(`tool:${tool}`), `${field}.tools`);
+        keys.add(`tool:${tool}`);
+    }
+}
+export function validateContractAndCard(contract, card) {
+    assert(record(contract), 'contract');
+    assert(contract.schema === 'harness-collab/assignment/1', 'contract.schema');
+    for (const key of ['task_id', 'assignment_id', 'objective'])
+        assert(text(contract[key]), `contract.${key}`);
+    assert(positive(contract.attempt), 'contract.attempt');
+    assert(Array.isArray(contract.roles) &&
+        contract.roles.length > 0 &&
+        contract.roles.every(text), 'contract.roles');
+    assert(Array.isArray(contract.acceptance) &&
+        contract.acceptance.length > 0 &&
+        contract.acceptance.every(text), 'contract.acceptance');
+    assert(record(contract.coordinator) &&
+        text(contract.coordinator.agent_id) &&
+        text(contract.coordinator.session_id) &&
+        positive(contract.coordinator.owner_epoch), 'contract.coordinator');
+    assert(record(contract.assignee), 'contract.assignee');
+    for (const key of [
+        'agent_id',
+        'session_id',
+        'harness',
+        'surface',
+        'configuration_id',
+    ]) {
+        assert(text(contract.assignee[key]), `contract.assignee.${key}`);
+    }
+    assert(text(contract.assignee.cwd) && path.isAbsolute(contract.assignee.cwd), 'contract.assignee.cwd');
+    assert(Array.isArray(contract.inputs) && contract.inputs.length > 0, 'contract.inputs');
+    for (const input of contract.inputs) {
+        assert(record(input) &&
+            text(input.ref) &&
+            path.isAbsolute(input.ref) &&
+            digest(input.digest), 'contract.inputs item');
+    }
+    assert(Array.isArray(contract.resources), 'contract.resources');
+    for (const resource of contract.resources) {
+        assert(record(resource) &&
+            text(resource.path) &&
+            path.isAbsolute(resource.path) &&
+            ['read', 'write'].includes(resource.access), 'contract.resources item');
+        if (resource.access === 'write')
+            assert(positive(resource.resource_epoch), 'contract.resources.resource_epoch');
+    }
+    assert(record(contract.runner) &&
+        text(contract.runner.name) &&
+        text(contract.runner.mode) &&
+        Array.isArray(contract.runner.omitted_capabilities) &&
+        contract.runner.omitted_capabilities.every(text), 'contract.runner');
+    requirements(contract.required, 'contract.required');
+    requirements(contract.preferred, 'contract.preferred');
+    assert(record(card) && card.schema === 'harness-collab/capabilities/1', 'capabilities.schema');
+    for (const key of [
+        'agent_id',
+        'session_id',
+        'harness',
+        'surface',
+        'configuration_id',
+    ]) {
+        assert(text(card[key]), `capabilities.${key}`);
+    }
+    assert(text(card.cwd) && path.isAbsolute(card.cwd), 'capabilities.cwd');
+    assert(text(card.observed_at) &&
+        /^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(card.observed_at) &&
+        Number.isFinite(Date.parse(card.observed_at)), 'capabilities.observed_at');
+    assert(['runtime', 'declared'].includes(card.evidence_level), 'capabilities.evidence_level');
+    if (card.evidence_records !== undefined) {
+        assert(Array.isArray(card.evidence_records) && card.evidence_records.length > 0, 'capabilities.evidence_records');
+        for (const item of card.evidence_records) {
+            assert(record(item) &&
+                text(item.ref) &&
+                path.isAbsolute(item.ref) &&
+                digest(item.digest), 'capabilities.evidence_records item');
+        }
+    }
+    for (const kind of ['skills', 'tools']) {
+        assert(Array.isArray(card[kind]), `capabilities.${kind}`);
+        const ids = new Set();
+        for (const item of card[kind]) {
+            assert(record(item) && text(item.id) && states.has(item.state), `capabilities.${kind} item`);
+            assert(!ids.has(item.id), `capabilities.${kind} duplicate`);
+            ids.add(item.id);
+            if (kind === 'skills') {
+                assert(text(item.path) &&
+                    path.isAbsolute(item.path) &&
+                    digest(item.bundle_digest), 'capabilities.skills fingerprint');
+            }
+            if (readyStates.has(item.state))
+                assert(text(item.evidence_ref), `capabilities.${kind} evidence_ref`);
+        }
+    }
+}
+/** Validate reported readiness, not authorization, resource locking, or task completion. */
+export function preflight(contract, card, { now = Date.now(), maxAgeMinutes = 30 } = {}) {
+    try {
+        assert(Number.isFinite(now) &&
+            Number.isFinite(new Date(now).getTime()) &&
+            Number.isFinite(maxAgeMinutes) &&
+            maxAgeMinutes > 0, 'clock/maximum age');
+        validateContractAndCard(contract, card);
+    }
+    catch (error) {
+        return {
+            status: 'invalid',
+            errors: [error instanceof Error ? error.message : String(error)],
+            blockers: [],
+            warnings: [],
+        };
+    }
+    const blockers = [];
+    const warnings = [];
+    const add = (list, code, capability) => list.push({ code, ...(capability ? { capability } : {}) });
+    for (const key of [
+        'agent_id',
+        'session_id',
+        'harness',
+        'surface',
+        'configuration_id',
+    ]) {
+        if (contract.assignee[key] !== card[key])
+            add(blockers, `assignee_${key}_mismatch`);
+    }
+    try {
+        if (!fs.statSync(card.cwd).isDirectory() ||
+            fs.realpathSync(contract.assignee.cwd) !== fs.realpathSync(card.cwd)) {
+            add(blockers, 'assignee_cwd_mismatch');
+        }
+    }
+    catch {
+        add(blockers, 'assignee_cwd_unavailable');
+    }
+    const age = now - Date.parse(card.observed_at);
+    if (age > maxAgeMinutes * 60_000)
+        add(blockers, 'capabilities_stale');
+    if (age < -60_000)
+        add(blockers, 'capabilities_from_future');
+    if (card.evidence_level !== 'runtime')
+        add(blockers, 'runtime_capabilities_unconfirmed');
+    const omitted = contract.runner.omitted_capabilities;
+    if ((omitted.includes('skills') && contract.required.skills.length) ||
+        (omitted.includes('tools') && contract.required.tools.length) ||
+        contract.required.skills.some((skill) => omitted.includes(`skill:${skill.id}`)) ||
+        contract.required.tools.some((tool) => omitted.includes(`tool:${tool}`)) ||
+        (omitted.includes('mcp') &&
+            contract.required.tools.some((tool) => /^(mcp:|mcp__)/.test(tool)))) {
+        add(blockers, 'required_capability_omitted_by_runner');
+    }
+    function evidenceAvailable(item) {
+        if (item.evidence_ref === `session:${card.session_id}`)
+            return true;
+        if (!text(item.evidence_ref) || !path.isAbsolute(item.evidence_ref))
+            return false;
+        try {
+            return fs.statSync(item.evidence_ref).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    function check(group, target) {
+        for (const kind of ['skills', 'tools']) {
+            for (const required of kind === 'skills'
+                ? group.skills
+                : group.tools.map((id) => ({ id, bundle_digest: null }))) {
+                const id = required.id;
+                const item = card[kind].find((candidate) => candidate.id === id);
+                if (!item || !readyStates.has(item.state)) {
+                    add(target, `${kind}_unavailable`, id);
+                    continue;
+                }
+                if (!evidenceAvailable(item))
+                    add(target, `${kind}_evidence_unavailable`, id);
+                if (kind === 'skills') {
+                    if (item.bundle_digest !== required.bundle_digest)
+                        add(target, 'skill_version_mismatch', id);
+                    try {
+                        if (fingerprintSkill(item.path ?? '').bundle_digest !==
+                            item.bundle_digest)
+                            add(target, 'skill_files_changed', id);
+                    }
+                    catch {
+                        add(target, 'skill_files_unavailable', id);
+                    }
+                }
+            }
+        }
+    }
+    check(contract.required, blockers);
+    check(contract.preferred, warnings);
+    for (const evidence of card.evidence_records ?? []) {
+        try {
+            if (!fs.statSync(evidence.ref).isFile() ||
+                fs.statSync(evidence.ref).size > 16 * 1024 * 1024)
+                throw new Error('Evidence limit');
+            const actual = `sha256:${createHash('sha256').update(fs.readFileSync(evidence.ref)).digest('hex')}`;
+            if (actual !== evidence.digest)
+                add(blockers, 'native_evidence_changed');
+        }
+        catch {
+            add(blockers, 'native_evidence_unavailable');
+        }
+    }
+    for (const input of contract.inputs) {
+        try {
+            const stat = fs.statSync(input.ref);
+            if (!stat.isFile() || stat.size > 16 * 1024 * 1024)
+                throw new Error('Input limit');
+            // Read bytes only to hash them; never include the input text in diagnostics.
+            const actual = `sha256:${createHash('sha256').update(fs.readFileSync(input.ref)).digest('hex')}`;
+            if (actual !== input.digest)
+                add(blockers, 'input_changed');
+        }
+        catch {
+            add(blockers, 'input_unavailable');
+        }
+    }
+    if (contract.runner.omitted_capabilities.length)
+        add(warnings, 'runner_capabilities_omitted');
+    if (contract.resources.some((resource) => resource.access === 'write'))
+        add(warnings, 'resource_ownership_not_enforced');
+    return {
+        status: blockers.length ? 'needs_input' : 'ready',
+        task_id: contract.task_id,
+        assignment_id: contract.assignment_id,
+        attempt: contract.attempt,
+        checked_at: new Date(now).toISOString(),
+        errors: [],
+        blockers,
+        warnings,
+        limits: [
+            'reported_runtime_evidence_only',
+            'authorization_not_checked',
+            'no_resource_lock',
+            'no_dispatch',
+        ],
+    };
+}

package/dist/collab/resources.d.ts

@@ -0,0 +1,119 @@
+import type { TaskRecord, Identity, Resource, ResourceInput, Claim, UnreadableRecord } from './types.js';
+export declare const DOMAIN_LOCK = ".domain.lock";
+export declare class DomainLockHeldError extends Error {
+    readonly holder: unknown;
+    constructor(message: string, holder: unknown);
+}
+export declare function acquireDomainLock(domainRoot: string, { waitMs, pollMs, holder, }?: {
+    waitMs?: number;
+    pollMs?: number;
+    holder?: Record<string, unknown>;
+}): {
+    schema: string;
+    scope: string;
+    domain_root: string;
+    nonce: string;
+    pid: number;
+    at: string;
+};
+export declare function releaseDomainLock(domainRoot: string, holder: {
+    nonce: string;
+}): void;
+/**
+ * Resolve the git index/HEAD resources implied by a path inside a work tree.
+ * Only per-worktree index/HEAD are derived automatically; a shared common-dir
+ * operation must be claimed explicitly so ordinary edits in two worktrees stay parallel.
+ */
+export declare function gitResourcesFor(targetPath: string): ResourceInput[];
+export declare function expandResources(requested: ResourceInput[], { includeGit, includeSharedGit }?: {
+    includeGit?: boolean | undefined;
+    includeSharedGit?: boolean | undefined;
+}): Resource[];
+export declare function listDomainRecords(domainRoot: string): (TaskRecord | UnreadableRecord)[];
+export declare function activeClaims(record: TaskRecord | UnreadableRecord): Claim[];
+export declare function scanConflicts(records: (TaskRecord | UnreadableRecord)[], candidates: Resource[], { access, holder }: {
+    access: string;
+    holder: Identity;
+}): ({
+    resource_key: string;
+    kind: string;
+    held_by: null;
+    held_task: string;
+    held_claim: null;
+    held_access: string;
+    relation: string;
+} | {
+    resource_key: string;
+    kind: string;
+    held_by: Identity;
+    held_task: string;
+    held_claim: string;
+    held_access: string;
+    relation: string;
+})[];
+/**
+ * Claim resources for one task. The domain lock serialises the decision so two tasks
+ * cannot both observe an empty domain and then claim the same path.
+ */
+export declare function claimResources(taskRoot: string, { resources, access, holder, waitMs, clock, includeSharedGit, note, subtaskId, attempt, }: {
+    resources: ResourceInput[];
+    access?: string;
+    holder: Identity;
+    waitMs?: number;
+    clock?: number;
+    includeSharedGit?: boolean;
+    note?: string | null;
+    subtaskId?: string | null;
+    attempt?: number | null;
+}): {
+    [key: string]: unknown;
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    claims: Claim[];
+    resource_epoch: number;
+    conflicts: never[];
+};
+export declare function releaseClaim(taskRoot: string, { claimId, holder, reason, clock, }: {
+    claimId: string;
+    holder?: Identity;
+    reason?: string;
+    clock?: number;
+}): {
+    [key: string]: unknown;
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    claim_id: string;
+};
+export declare function domainClaims(record: TaskRecord): {
+    task_id: string;
+    claims: {
+        kind: string;
+        scope: string;
+        key: string;
+        path?: string | null;
+        port?: number | null;
+        existing?: boolean;
+        label: string;
+        origin?: string;
+        derived_from?: string | null;
+        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;
+        task_id: string;
+    }[];
+}[];