sneakoscope 7.0.2 → 7.0.3

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

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { inspectConfinedPath, removeManagedPathVerified } from '../managed-path-safety.js';
+import { EMERGENCY_DENIAL_DIR, MAX_EMERGENCY_DENIALS, MAX_LIFECYCLE_GUARD_BYTES, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME, validBlocker } from './subagent-skill-availability-contract.js';
+import { boundedDirectoryNames, readBoundedConfinedJson, safeWriteJson } from './subagent-skill-availability-guards.js';
+import { sha256 } from '../fsx.js';
+export function uniqueArtifactDirs(...values) {
+    return [...new Set(values
+            .map((value) => String(value || '').trim())
+            .filter(Boolean)
+            .map((value) => path.resolve(value)))];
+}
+export async function persistBlockerEvidence(input) {
+    const emergencyArtifactDirs = input.emergency
+        ? uniqueArtifactDirs(input.artifactDir, input.sessionArtifactDir)
+        : [];
+    const [sharedWrite, emergencyWrites] = await Promise.all([
+        safeWriteJson(path.join(input.artifactDir, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME), path.resolve(input.root), input.blocker),
+        Promise.all(emergencyArtifactDirs.map((artifactDir) => (persistEmergencyDenial(path.resolve(input.root), artifactDir, input.blocker))))
+    ]);
+    return sharedWrite && emergencyWrites.every(Boolean);
+}
+export async function clearMatchingBlockerEvidence(input) {
+    const root = path.resolve(input.root);
+    const artifactDir = path.resolve(input.artifactDir);
+    const file = path.join(artifactDir, SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME);
+    try {
+        const emergencyCleared = (await Promise.all(uniqueArtifactDirs(artifactDir, input.sessionArtifactDir).map((candidate) => (clearMatchingEmergencyDenials(root, candidate, input.threadHash))))).every(Boolean);
+        const inspected = await inspectConfinedPath(root, file);
+        if (!inspected.exists)
+            return emergencyCleared;
+        if (inspected.leafSymlink || !inspected.stat?.isFile())
+            return false;
+        const blockerRead = await readBoundedConfinedJson(root, file, MAX_LIFECYCLE_GUARD_BYTES);
+        if (blockerRead.status !== 'value' || !validBlocker(blockerRead.value))
+            return false;
+        if (blockerRead.value.thread_id_hash !== input.threadHash)
+            return emergencyCleared;
+        await removeManagedPathVerified(root, file);
+        return emergencyCleared && !(await inspectConfinedPath(root, file)).exists;
+    }
+    catch {
+        return false;
+    }
+}
+export async function matchingArtifactBlockers(root, artifactDir, sessionHash, turnHash) {
+    const emergency = await matchingEmergencyDenial(root, artifactDir, sessionHash, turnHash);
+    if (emergency)
+        return emergency;
+    const file = path.join(path.resolve(artifactDir), SUBAGENT_SKILL_AVAILABILITY_BLOCKER_FILENAME);
+    const result = await readBoundedConfinedJson(path.resolve(root), file, MAX_LIFECYCLE_GUARD_BYTES);
+    if (result.status === 'missing')
+        return null;
+    if (result.status !== 'value' || !validBlocker(result.value)) {
+        return invalidArtifactEvidence();
+    }
+    const blocker = result.value;
+    return blocker.session_scope_hash === sessionHash && blocker.turn_id_hash === turnHash
+        ? {
+            blockers: blocker.blockers,
+            missionId: blocker.mission_id,
+            workflowRunId: blocker.workflow_run_id
+        }
+        : null;
+}
+export async function emergencyRunBlockers(root, artifactDir, missionId, workflowRunId) {
+    const records = await readEmergencyDenials(root, artifactDir);
+    const blockers = [];
+    for (const record of records) {
+        if (!record) {
+            blockers.push('subagent_skill_availability_guard_invalid');
+            continue;
+        }
+        if (record.mission_id === missionId && record.workflow_run_id === workflowRunId) {
+            blockers.push(...record.blockers);
+        }
+    }
+    return blockers;
+}
+function emergencyDenialDir(artifactDir) {
+    return path.join(artifactDir, EMERGENCY_DENIAL_DIR);
+}
+function emergencyDenialPath(artifactDir, sessionHash, turnHash) {
+    return path.join(emergencyDenialDir(artifactDir), `deny-${sha256(`${sessionHash}:${turnHash}`)}.json`);
+}
+async function persistEmergencyDenial(root, artifactDir, blocker) {
+    const written = await safeWriteJson(emergencyDenialPath(artifactDir, blocker.session_scope_hash, blocker.turn_id_hash), root, blocker);
+    if (!written)
+        return false;
+    return pruneEmergencyDenials(root, artifactDir);
+}
+async function matchingEmergencyDenial(root, artifactDir, sessionHash, turnHash) {
+    const file = emergencyDenialPath(path.resolve(artifactDir), sessionHash, turnHash);
+    try {
+        const result = await readBoundedConfinedJson(path.resolve(root), file, MAX_LIFECYCLE_GUARD_BYTES);
+        if (result.status === 'missing')
+            return null;
+        if (result.status !== 'value' || !validBlocker(result.value)
+            || result.value.session_scope_hash !== sessionHash
+            || result.value.turn_id_hash !== turnHash) {
+            return invalidArtifactEvidence();
+        }
+        return {
+            blockers: result.value.blockers,
+            missionId: result.value.mission_id,
+            workflowRunId: result.value.workflow_run_id
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function clearMatchingEmergencyDenials(root, artifactDir, threadHash) {
+    const records = await readEmergencyDenialsWithFiles(root, artifactDir);
+    if (records === null)
+        return false;
+    let ok = records.every((entry) => Boolean(entry.blocker));
+    for (const { file, blocker } of records) {
+        if (!blocker || blocker.thread_id_hash !== threadHash)
+            continue;
+        try {
+            const entry = await inspectConfinedPath(root, file);
+            if (entry.leafSymlink || !entry.stat?.isFile() || entry.stat.size > MAX_LIFECYCLE_GUARD_BYTES) {
+                ok = false;
+                continue;
+            }
+            await removeManagedPathVerified(root, file);
+            if ((await inspectConfinedPath(root, file)).exists)
+                ok = false;
+        }
+        catch {
+            ok = false;
+        }
+    }
+    return ok;
+}
+async function pruneEmergencyDenials(root, artifactDir) {
+    const dir = emergencyDenialDir(artifactDir);
+    const records = await readEmergencyDenialsWithFiles(root, artifactDir);
+    if (records === null)
+        return false;
+    const ordered = records
+        .filter((entry) => (Boolean(entry.blocker)))
+        .sort((left, right) => right.blocker.recorded_at.localeCompare(left.blocker.recorded_at));
+    let ok = records.every((entry) => Boolean(entry.blocker));
+    for (const entry of ordered.slice(MAX_EMERGENCY_DENIALS)) {
+        try {
+            await removeManagedPathVerified(root, entry.file);
+            if ((await inspectConfinedPath(root, entry.file)).exists)
+                ok = false;
+        }
+        catch {
+            ok = false;
+        }
+    }
+    const inspected = await inspectConfinedPath(root, dir).catch(() => null);
+    return ok && Boolean(inspected?.exists && inspected.stat?.isDirectory() && !inspected.leafSymlink);
+}
+async function readEmergencyDenials(root, artifactDir) {
+    const records = await readEmergencyDenialsWithFiles(root, artifactDir);
+    return records === null ? [null] : records.map((entry) => entry.blocker);
+}
+async function readEmergencyDenialsWithFiles(root, artifactDir) {
+    const dir = emergencyDenialDir(artifactDir);
+    let inspected;
+    try {
+        inspected = await inspectConfinedPath(root, dir);
+    }
+    catch {
+        return null;
+    }
+    if (!inspected.exists)
+        return [];
+    if (inspected.leafSymlink || !inspected.stat?.isDirectory())
+        return null;
+    const names = await boundedDirectoryNames(dir);
+    if (names === null)
+        return null;
+    const records = [];
+    for (const name of names.filter((item) => /^deny-[a-f0-9]{64}\.json$/.test(item)).sort()) {
+        const file = path.join(dir, name);
+        const result = await readBoundedConfinedJson(root, file, MAX_LIFECYCLE_GUARD_BYTES);
+        records.push({
+            file,
+            blocker: result.status === 'value' && validBlocker(result.value) ? result.value : null
+        });
+    }
+    return records;
+}
+function invalidArtifactEvidence() {
+    return {
+        blockers: ['subagent_skill_availability_guard_invalid'],
+        missionId: null,
+        workflowRunId: null
+    };
+}

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

@@ -0,0 +1,316 @@
+import { constants as fsConstants } from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { sha256, writeJsonAtomic } from '../fsx.js';
+import { ensureConfinedDirectory, inspectConfinedPath, removeManagedPathVerified } from '../managed-path-safety.js';
+import { ADMISSION_SCHEMA, GUARD_DIR, MAX_LIFECYCLE_GUARD_BYTES, MAX_LIFECYCLE_GUARD_ENTRIES, MAX_SUBAGENT_PLAN_BYTES, SUBAGENT_ADMISSION_BLOCKER_RE, SubagentSkillAvailabilityGuardError } from './subagent-skill-availability-contract.js';
+function rootGuardDir(root) {
+    return path.join(root, '.sneakoscope', 'guards', GUARD_DIR);
+}
+function artifactGuardDir(artifactDir) {
+    return path.join(artifactDir, GUARD_DIR);
+}
+function homeGuardDir(home, canonicalRoot) {
+    return path.join(home, '.sneakoscope', 'guards', GUARD_DIR, sha256(canonicalRoot));
+}
+export function threadGuardPath(guardRoot, threadHash) {
+    return path.join(guardRoot, `thread-${threadHash}.json`);
+}
+export function turnGuardPath(guardRoot, sessionHash, turnHash) {
+    return path.join(guardRoot, `turn-${sha256(`${sessionHash}:${turnHash}`)}.json`);
+}
+function validAdmission(value) {
+    const blockers = Array.isArray(value?.blockers) ? value.blockers : null;
+    return value?.schema === ADMISSION_SCHEMA
+        && ['allowed', 'blocked'].includes(String(value?.status || ''))
+        && (value?.mission_id === null || typeof value?.mission_id === 'string')
+        && (value?.workflow_run_id === null || typeof value?.workflow_run_id === 'string')
+        && /^[a-f0-9]{64}$/.test(String(value?.thread_id_hash || ''))
+        && /^[a-f0-9]{64}$/.test(String(value?.session_scope_hash || ''))
+        && /^[a-f0-9]{64}$/.test(String(value?.turn_id_hash || ''))
+        && blockers !== null
+        && (value.status === 'allowed'
+            ? blockers.length === 0
+            : blockers.length > 0 && blockers.every((item) => (SUBAGENT_ADMISSION_BLOCKER_RE.test(String(item || '')))));
+}
+export async function readConfinedJson(boundary, file) {
+    const result = await readBoundedConfinedJson(path.resolve(boundary), path.resolve(file), MAX_SUBAGENT_PLAN_BYTES);
+    return result.status === 'value' ? result.value : null;
+}
+export async function admissionGuardRoots(root, artifactDir) {
+    const projectRoot = path.resolve(root);
+    const canonicalRoot = await fsp.realpath(projectRoot);
+    const home = path.resolve(process.env.HOME || os.homedir());
+    const roots = [
+        { root: rootGuardDir(projectRoot), boundary: projectRoot, missionIndependent: true },
+        ...(artifactDir ? [{
+                root: artifactGuardDir(path.resolve(artifactDir)),
+                boundary: projectRoot,
+                missionIndependent: false
+            }] : []),
+        { root: homeGuardDir(home, canonicalRoot), boundary: home, missionIndependent: true }
+    ];
+    const unique = new Map();
+    for (const entry of roots) {
+        const previous = unique.get(entry.root);
+        if (!previous || (!previous.missionIndependent && entry.missionIndependent)) {
+            unique.set(entry.root, entry);
+        }
+    }
+    return [...unique.values()];
+}
+export async function writeAdmissionPair(root, admission) {
+    const [threadWrite, turnWrite] = await Promise.all([
+        safeWriteJson(threadGuardPath(root.root, admission.thread_id_hash), root.boundary, admission),
+        safeWriteJson(turnGuardPath(root.root, admission.session_scope_hash, admission.turn_id_hash), root.boundary, admission)
+    ]);
+    return threadWrite && turnWrite;
+}
+export async function readAdmissionPair(root, expectedThreadHash, expectedSessionHash, expectedTurnHash) {
+    const turnFile = turnGuardPath(root.root, expectedSessionHash, expectedTurnHash);
+    const turnAdmission = await readAdmission(turnFile, root.boundary);
+    if (expectedThreadHash) {
+        const threadFile = threadGuardPath(root.root, expectedThreadHash);
+        const threadAdmission = await readAdmission(threadFile, root.boundary);
+        if (!turnAdmission && !threadAdmission)
+            return null;
+        if (!turnAdmission || !threadAdmission)
+            throw invalidGuard(true);
+        validateAdmissionBinding(turnAdmission, expectedThreadHash, expectedSessionHash, expectedTurnHash);
+        validateAdmissionBinding(threadAdmission, expectedThreadHash, expectedSessionHash, expectedTurnHash);
+        if (admissionFingerprint(turnAdmission) !== admissionFingerprint(threadAdmission)) {
+            throw invalidGuard(true);
+        }
+        return turnAdmission;
+    }
+    if (!turnAdmission)
+        return null;
+    validateAdmissionBinding(turnAdmission, turnAdmission.thread_id_hash, expectedSessionHash, expectedTurnHash);
+    let threadAdmission;
+    try {
+        threadAdmission = await readAdmission(threadGuardPath(root.root, turnAdmission.thread_id_hash), root.boundary);
+    }
+    catch {
+        throw invalidGuard(true);
+    }
+    if (!threadAdmission || admissionFingerprint(turnAdmission) !== admissionFingerprint(threadAdmission)) {
+        throw invalidGuard(true);
+    }
+    return turnAdmission;
+}
+async function readAdmission(file, boundary) {
+    const result = await readBoundedConfinedJson(boundary, file, MAX_LIFECYCLE_GUARD_BYTES);
+    if (result.status === 'missing')
+        return null;
+    if (result.status === 'invalid')
+        throw invalidGuard(result.childEvidence);
+    if (!validAdmission(result.value))
+        throw invalidGuard(true);
+    return result.value;
+}
+export async function blockedRunAdmissions(guardRoot, missionId, workflowRunId) {
+    let inspected;
+    try {
+        inspected = await inspectConfinedPath(guardRoot.boundary, guardRoot.root);
+    }
+    catch {
+        return ['subagent_skill_availability_guard_invalid'];
+    }
+    if (!inspected.exists)
+        return [];
+    if (inspected.leafSymlink || !inspected.stat?.isDirectory()) {
+        return ['subagent_skill_availability_guard_invalid'];
+    }
+    const names = await boundedDirectoryNames(guardRoot.root);
+    if (names === null)
+        return ['subagent_skill_availability_guard_invalid'];
+    const blockers = [];
+    for (const name of names.filter((item) => /^thread-[a-f0-9]{64}\.json$/.test(item)).sort()) {
+        let admission;
+        try {
+            admission = await readAdmission(path.join(guardRoot.root, name), guardRoot.boundary);
+        }
+        catch {
+            blockers.push('subagent_skill_availability_guard_invalid');
+            continue;
+        }
+        if (!admission
+            || admission.mission_id !== missionId
+            || admission.workflow_run_id !== workflowRunId
+            || admission.status !== 'blocked')
+            continue;
+        blockers.push(...admission.blockers);
+    }
+    return blockers;
+}
+function validateAdmissionBinding(admission, expectedThreadHash, expectedSessionHash, expectedTurnHash) {
+    if (admission.thread_id_hash !== expectedThreadHash
+        || admission.session_scope_hash !== expectedSessionHash
+        || admission.turn_id_hash !== expectedTurnHash) {
+        throw invalidGuard(true);
+    }
+}
+export function invalidGuard(childEvidence) {
+    return new SubagentSkillAvailabilityGuardError(childEvidence);
+}
+export function admissionFingerprint(admission) {
+    return sha256(JSON.stringify([
+        admission.schema,
+        admission.status,
+        admission.mission_id,
+        admission.workflow_run_id,
+        admission.thread_id_hash,
+        admission.session_scope_hash,
+        admission.turn_id_hash,
+        admission.blockers,
+        admission.recorded_at
+    ]));
+}
+export async function safeWriteJson(file, boundary, value) {
+    try {
+        if (Buffer.byteLength(`${JSON.stringify(value, null, 2)}\n`, 'utf8') > MAX_LIFECYCLE_GUARD_BYTES) {
+            return false;
+        }
+        await ensureConfinedDirectory(boundary, path.dirname(file));
+        const before = await inspectConfinedPath(boundary, file);
+        if (before.exists && (before.leafSymlink || !before.stat?.isFile()))
+            return false;
+        await writeJsonAtomic(file, value);
+        const after = await inspectConfinedPath(boundary, file);
+        return after.exists && !after.leafSymlink && Boolean(after.stat?.isFile());
+    }
+    catch {
+        return false;
+    }
+}
+export async function safeRemoveGuard(file, boundary) {
+    try {
+        const inspected = await inspectConfinedPath(boundary, file);
+        if (!inspected.exists)
+            return;
+        if (inspected.leafSymlink || !inspected.stat?.isFile())
+            return;
+        await removeManagedPathVerified(boundary, file);
+    }
+    catch {
+        return;
+    }
+}
+export async function boundedDirectoryNames(directory) {
+    let handle;
+    try {
+        handle = await fsp.opendir(directory);
+        const names = [];
+        for await (const entry of handle) {
+            names.push(entry.name);
+            if (names.length > MAX_LIFECYCLE_GUARD_ENTRIES)
+                return null;
+        }
+        return names.sort((left, right) => left.localeCompare(right));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+export async function readBoundedConfinedJson(boundary, file, maxBytes) {
+    const absoluteBoundary = path.resolve(boundary);
+    const absoluteFile = path.resolve(file);
+    let childEvidence = false;
+    try {
+        const inspected = await inspectConfinedPath(absoluteBoundary, absoluteFile);
+        if (!inspected.exists)
+            return { status: 'missing' };
+        childEvidence = true;
+        if (inspected.leafSymlink || !inspected.stat?.isFile() || inspected.stat.size > maxBytes) {
+            return { status: 'invalid', childEvidence };
+        }
+        const handle = await fsp.open(absoluteFile, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.size > maxBytes)
+                return { status: 'invalid', childEvidence };
+            const buffer = Buffer.alloc(maxBytes + 1);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if (bytesRead > maxBytes || bytesRead !== stat.size) {
+                return { status: 'invalid', childEvidence };
+            }
+            return { status: 'value', value: JSON.parse(buffer.subarray(0, bytesRead).toString('utf8')) };
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    }
+    catch {
+        return { status: 'invalid', childEvidence };
+    }
+}
+export function preToolBlockReason(blockers) {
+    return `SKS blocked this child tool call because managed skill availability failed (${blockers.join(', ')}). Return the blocker to the root parent without using tools.`;
+}
+export function boundedAgentThreadId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const candidate = value.trim();
+    if (!candidate
+        || Buffer.byteLength(candidate, 'utf8') > 512
+        || /[\u0000-\u001f\u007f]/.test(candidate))
+        return null;
+    return candidate;
+}
+export async function officialSubagentThreadIdFromTranscript(value) {
+    const file = String(value || '').trim();
+    if (!file)
+        return null;
+    const sessionsRoot = path.resolve(process.env.CODEX_HOME
+        ? path.join(process.env.CODEX_HOME, 'sessions')
+        : path.join(process.env.HOME || os.homedir(), '.codex', 'sessions'));
+    const [sessionsReal, fileReal] = await Promise.all([
+        fsp.realpath(sessionsRoot).catch(() => null),
+        fsp.realpath(file).catch(() => null)
+    ]);
+    if (!sessionsReal || !fileReal || !pathIsInside(sessionsReal, fileReal))
+        return null;
+    const stat = await fsp.lstat(file).catch(() => null);
+    if (!stat || stat.isSymbolicLink() || !stat.isFile())
+        return null;
+    const handle = await fsp.open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW).catch(() => null);
+    if (!handle)
+        return null;
+    try {
+        const statAfterOpen = await handle.stat();
+        if (!statAfterOpen.isFile() || statAfterOpen.size > 1024 * 1024)
+            return null;
+        const buffer = Buffer.alloc(1024 * 1024);
+        const read = await handle.read(buffer, 0, buffer.length, 0);
+        if (read.bytesRead < 1)
+            return null;
+        const text = buffer.subarray(0, read.bytesRead).toString('utf8');
+        const line = text.split(/\r?\n/, 1)[0]?.trim();
+        if (!line)
+            return null;
+        const row = JSON.parse(line);
+        const source = row?.payload?.source?.subagent;
+        const threadSpawn = source?.thread_spawn;
+        if (row?.type !== 'session_meta' || !source || typeof source !== 'object'
+            || !threadSpawn || typeof threadSpawn !== 'object')
+            return null;
+        return String(row?.payload?.id || row?.payload?.session_id || '').trim() || null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function pathIsInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return Boolean(relative)
+        && relative !== '..'
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}