sneakoscope 7.0.2 → 7.0.3

package/dist/core/hooks-runtime/subagent-skill-availability.js

@@ -0,0 +1,217 @@
+import path from 'node:path';
+import { nowIso, sha256 } from '../fsx.js';
+import { ADMISSION_SCHEMA, MAX_LIFECYCLE_GUARD_BYTES, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_SCHEMA, SubagentSkillAvailabilityGuardError, validBlocker } from './subagent-skill-availability-contract.js';
+import { admissionFingerprint, admissionGuardRoots, blockedRunAdmissions, boundedAgentThreadId, invalidGuard, officialSubagentThreadIdFromTranscript, preToolBlockReason, readAdmissionPair, readBoundedConfinedJson, readConfinedJson, safeRemoveGuard, threadGuardPath, turnGuardPath, writeAdmissionPair } from './subagent-skill-availability-guards.js';
+import { clearMatchingBlockerEvidence, emergencyRunBlockers, matchingArtifactBlockers, persistBlockerEvidence } from './subagent-skill-availability-evidence.js';
+export { SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_SCHEMA } from './subagent-skill-availability-contract.js';
+export function authoritativeSksSkillResolutionBlockers(resolution) {
+    if (!resolution)
+        return ['authoritative_sks_skill_resolution_failed'];
+    const blockers = [
+        ...resolution.unresolved.map((name) => `authoritative_sks_skill_unavailable:${name}`),
+        ...(resolution.blockers.length ? ['authoritative_sks_skill_candidate_rejected'] : [])
+    ];
+    return [...new Set(blockers)];
+}
+export function renderSubagentSkillAvailabilityHandoff(blockers) {
+    const codes = blockers.length ? blockers.join(', ') : 'authoritative_sks_skill_resolution_failed';
+    return [
+        'MANDATORY SKS PARENT-BLOCK HANDOFF:',
+        '- Current managed SKS skill availability was not verified for this child thread.',
+        '- Do not inspect files, call tools, run commands, modify anything, or spawn another agent.',
+        '- Immediately return a concise blocked result to the root parent.',
+        `- Return status=blocked with blockers=[${codes}].`,
+        '- Do not reuse or mention any prior skill location.'
+    ].join('\n');
+}
+export async function persistSubagentSkillAvailabilityBlocker(input) {
+    const threadId = String(input.payload?.agent_id || '').trim();
+    const sessionScope = String(input.payload?.session_id || '').trim();
+    const turnId = String(input.payload?.turn_id || '').trim();
+    if (!threadId || !sessionScope || !turnId) {
+        throw new Error('subagent_skill_availability_guard_identity_missing');
+    }
+    const plan = await readConfinedJson(input.root, path.join(input.artifactDir, 'subagent-plan.json'));
+    const blockers = [...new Set(input.blockers.map((item) => String(item || '').trim()).filter(Boolean))];
+    const admission = {
+        schema: ADMISSION_SCHEMA,
+        status: blockers.length ? 'blocked' : 'allowed',
+        mission_id: String(input.state?.mission_id || plan?.mission_id || '').trim() || null,
+        workflow_run_id: String(input.state?.official_subagent_run_id || plan?.workflow_run_id || '').trim() || null,
+        thread_id_hash: sha256(threadId),
+        session_scope_hash: sha256(sessionScope),
+        turn_id_hash: sha256(turnId),
+        blockers,
+        recorded_at: nowIso()
+    };
+    const roots = await admissionGuardRoots(input.root, input.artifactDir);
+    const guardedAdmission = blockers.length
+        ? admission
+        : {
+            ...admission,
+            status: 'blocked',
+            blockers: ['subagent_skill_availability_blocker_artifact_write_failed']
+        };
+    const rootWrites = await Promise.all(roots.map((guardRoot) => writeAdmissionPair(guardRoot, guardedAdmission)));
+    const stableGuardMissing = !rootWrites.some((written, index) => (written && roots[index]?.missionIndependent));
+    const evidenceBlockers = stableGuardMissing
+        ? [...new Set([...blockers, 'subagent_skill_availability_guard_persistence_failed'])]
+        : blockers;
+    let evidenceWrite;
+    if (evidenceBlockers.length) {
+        const blocker = {
+            schema: SUBAGENT_SKILL_AVAILABILITY_BLOCKER_SCHEMA,
+            status: 'blocked',
+            mission_id: admission.mission_id,
+            workflow_run_id: admission.workflow_run_id,
+            thread_id_hash: admission.thread_id_hash,
+            session_scope_hash: admission.session_scope_hash,
+            turn_id_hash: admission.turn_id_hash,
+            blockers: evidenceBlockers,
+            recorded_at: admission.recorded_at
+        };
+        evidenceWrite = await persistBlockerEvidence({
+            root: input.root,
+            artifactDir: input.artifactDir,
+            sessionArtifactDir: input.sessionArtifactDir,
+            blocker,
+            emergency: stableGuardMissing
+        });
+    }
+    else {
+        evidenceWrite = await clearMatchingBlockerEvidence({
+            root: input.root,
+            artifactDir: input.artifactDir,
+            sessionArtifactDir: input.sessionArtifactDir,
+            threadHash: admission.thread_id_hash
+        });
+    }
+    if (stableGuardMissing)
+        throw new Error('subagent_skill_availability_guard_persistence_failed');
+    if (!evidenceWrite)
+        throw new Error('subagent_skill_availability_blocker_artifact_write_failed');
+    if (!blockers.length) {
+        const allowedWrites = await Promise.all(roots.map((guardRoot) => writeAdmissionPair(guardRoot, admission)));
+        const guardedRootCommitFailed = rootWrites.some((guardedWrite, index) => (guardedWrite && !allowedWrites[index]));
+        const stableAllowedCommitMissing = !allowedWrites.some((written, index) => (written && roots[index]?.missionIndependent));
+        if (stableAllowedCommitMissing || guardedRootCommitFailed) {
+            throw new Error('subagent_skill_availability_guard_persistence_failed');
+        }
+    }
+    return admission;
+}
+export async function subagentSkillAvailabilityPreToolBlockReason(root, payload, artifactDir, activeBinding) {
+    const rawPayloadThreadId = payload?.agent_id;
+    const payloadThreadId = boundedAgentThreadId(rawPayloadThreadId);
+    const payloadThreadIdClaimed = typeof rawPayloadThreadId === 'string'
+        ? Boolean(rawPayloadThreadId.trim())
+        : rawPayloadThreadId !== undefined && rawPayloadThreadId !== null;
+    if (payloadThreadIdClaimed && !payloadThreadId)
+        throw invalidGuard(true);
+    const rawTranscriptThreadId = await officialSubagentThreadIdFromTranscript(payload?.transcript_path);
+    const transcriptThreadId = boundedAgentThreadId(rawTranscriptThreadId);
+    if (rawTranscriptThreadId && !transcriptThreadId)
+        throw invalidGuard(true);
+    if (payloadThreadId && transcriptThreadId && payloadThreadId !== transcriptThreadId) {
+        throw invalidGuard(true);
+    }
+    const threadId = payloadThreadId || transcriptThreadId;
+    const threadHash = threadId ? sha256(threadId) : null;
+    const activeMissionId = String(activeBinding?.missionId || '').trim() || null;
+    const activeWorkflowRunId = String(activeBinding?.workflowRunId || '').trim() || null;
+    if (threadId && (!activeMissionId || !activeWorkflowRunId)) {
+        return preToolBlockReason(['subagent_skill_availability_guard_invalid']);
+    }
+    const sessionScope = String(payload?.session_id || '').trim();
+    const turnId = String(payload?.turn_id || '').trim();
+    if (!sessionScope || !turnId) {
+        return threadId ? preToolBlockReason(['subagent_skill_availability_admission_missing']) : null;
+    }
+    const sessionHash = sha256(sessionScope);
+    const turnHash = sha256(turnId);
+    const artifactEvidence = artifactDir
+        ? await matchingArtifactBlockers(root, artifactDir, sessionHash, turnHash)
+        : null;
+    const admissions = [];
+    const errors = [];
+    for (const guardRoot of await admissionGuardRoots(root, artifactDir)) {
+        try {
+            const admission = await readAdmissionPair(guardRoot, threadHash, sessionHash, turnHash);
+            if (admission)
+                admissions.push(admission);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    const invalidChildEvidence = errors.some((error) => (error instanceof SubagentSkillAvailabilityGuardError && error.childEvidence));
+    if (artifactEvidence) {
+        if (!activeMissionId
+            || !activeWorkflowRunId
+            || artifactEvidence.missionId !== activeMissionId
+            || artifactEvidence.workflowRunId !== activeWorkflowRunId) {
+            return preToolBlockReason(['subagent_skill_availability_guard_invalid']);
+        }
+        return preToolBlockReason(artifactEvidence.blockers);
+    }
+    if (errors.length && (threadId || admissions.length || invalidChildEvidence))
+        throw errors[0];
+    if (errors.length)
+        return null;
+    if (!admissions.length) {
+        return threadId ? preToolBlockReason(['subagent_skill_availability_admission_missing']) : null;
+    }
+    if (!activeMissionId
+        || !activeWorkflowRunId
+        || admissions.some((admission) => (admission.mission_id !== activeMissionId
+            || admission.workflow_run_id !== activeWorkflowRunId))) {
+        return preToolBlockReason(['subagent_skill_availability_guard_invalid']);
+    }
+    const fingerprints = new Set(admissions.map(admissionFingerprint));
+    if (fingerprints.size !== 1)
+        return preToolBlockReason(['subagent_skill_availability_guard_invalid']);
+    const admission = admissions[0];
+    return admission.status === 'blocked' ? preToolBlockReason(admission.blockers) : null;
+}
+export async function clearSubagentSkillAvailabilityGuards(root, payload, artifactDir) {
+    const threadId = String(payload?.agent_id || '').trim();
+    const sessionScope = String(payload?.session_id || '').trim();
+    const turnId = String(payload?.turn_id || '').trim();
+    const roots = await admissionGuardRoots(root, artifactDir);
+    const files = [];
+    if (threadId)
+        files.push(...roots.map((guardRoot) => ({
+            file: threadGuardPath(guardRoot.root, sha256(threadId)),
+            boundary: guardRoot.boundary
+        })));
+    if (sessionScope && turnId) {
+        const sessionHash = sha256(sessionScope);
+        const turnHash = sha256(turnId);
+        files.push(...roots.map((guardRoot) => ({
+            file: turnGuardPath(guardRoot.root, sessionHash, turnHash),
+            boundary: guardRoot.boundary
+        })));
+    }
+    await Promise.all(files.map(({ file, boundary }) => safeRemoveGuard(file, boundary)));
+}
+export async function subagentSkillAvailabilityRunBlockers(root, artifactDir, missionId, workflowRunId) {
+    const blockers = [];
+    for (const guardRoot of await admissionGuardRoots(root, artifactDir)) {
+        blockers.push(...await blockedRunAdmissions(guardRoot, missionId, workflowRunId));
+    }
+    blockers.push(...await emergencyRunBlockers(root, artifactDir, missionId, workflowRunId));
+    const file = path.join(artifactDir, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME);
+    const blockerRead = await readBoundedConfinedJson(path.resolve(root), file, MAX_LIFECYCLE_GUARD_BYTES);
+    if (blockerRead.status === 'missing')
+        return [...new Set(blockers)];
+    if (blockerRead.status !== 'value' || !validBlocker(blockerRead.value)) {
+        return [...new Set([...blockers, 'subagent_skill_availability_blocker_artifact_invalid'])];
+    }
+    const blocker = blockerRead.value;
+    if (!missionId || blocker.mission_id !== missionId) {
+        return [...new Set([...blockers, 'subagent_skill_availability_blocker_artifact_invalid'])];
+    }
+    if (!workflowRunId || blocker.workflow_run_id !== workflowRunId)
+        return [...new Set(blockers)];
+    return [...new Set([...blockers, ...blocker.blockers])];
+}